Markdown предлагают хранить в /src как код, а не документацию

Carson Gross, профессор Университета штата Монтана, который параллельно с преподаванием занимается ИИ-консалтингом, опубликовал эссе с тезисом: в компаниях, которые делают ставку на агентный кодинг (когда код по промптам разработчика пишет ИИ-агент), Markdown-файлы перестают быть вспомогательной документацией и фактически становятся исходным кодом системы.

Его аргумент устроен так. При агентном кодинге разработчик формулирует задачу серией промптов, агент генерирует код, и именно этот код остаётся единственным «источником истины» по фиче, потому что сами промпты нигде не сохраняются. Этим агентный процесс отличается от классического компилятора: компиляторные конвейеры сохраняют исходный код, из которого получена низкоуровневая машинная инструкция, а ИИ-конвейеры обычно теряют исходные промпты сразу после того, как код сгенерирован.

Гросс ссылается на более раннее эссе Хартли Броди «Markdown is the new source code» («Markdown, это новый исходный код»): по словам Броди, логика приложения всё больше определяется и редактируется именно в Markdown, а код, который выдаёт агент, превращается в низкоуровневую деталь реализации.

Предложение самого Гросса: завести в проекте отдельную директорию /src/md, рядом с исходным кодом, а не в вики или таск-трекере, и переносить туда архитектурные и низкоуровневые решения по устройству данных. Именно из этих файлов, по его мысли, должны выводиться код и тесты, а не создаваться заново из очередной сессии промптов. Черновая структура, которую он предлагает как отправную точку: /src/md/README.md, точка входа для агентов и людей, TODO.md, список открытых задач модуля, OVERVIEW.md, технический обзор, а также опциональные поддиректории features/, data/, api/ и infrastructure/ под описания функциональности, моделей данных, API и инфраструктуры соответственно.

Гросс называет главным преимуществом такого подхода локальность: логика «почему сделано именно так» лежит рядом с кодом, а не разбросана по вики, Notion, Confluence или Jira, и агентам не нужно искать контекст где-то ещё. При этом он подчёркивает: сам /src/md должен писаться и курироваться в основном людьми, а не агентами, это ограничение, а не побочный эффект предложения.

Отдельно он разбирает соотношение с тестами. Тесты, по его схеме, остаются в /test и выводятся уже из Markdown-спецификации, но не заменяют её: в тестах, пишет он, много формальностей, из-за которых не видно, что именно проверяется, они рассчитаны на более низкий уровень детализации, чем нужен большинству людей для понимания системы, а более высокоуровневые объяснения вроде диаграмм Mermaid в тестовый код просто не помещаются.

Гросс прямо называет предложенную структуру /src/md самой слабой частью своего эссе: он сам не использовал её сколько-нибудь широко и подаёт текст как приглашение к обсуждению, а не как готовый, проверенный на практике стандарт.

Ключевые факты

Carson Gross (профессор Университета штата Монтана, параллельно ИИ-консультант) утверждает: там, где код пишут ИИ-агенты, Markdown перестаёт быть документацией и становится исходным кодом
Предлагает завести директорию /src/md рядом с кодом: архитектурные и низкоуровневые решения хранятся там, код и тесты выводятся из них, а не создаются заново из очередных промптов
Черновая структура: README.md как точка входа для агентов, TODO.md, OVERVIEW.md плюс опциональные features/, data/, api/, infrastructure/
Тесты остаются в отдельной папке /test и выводятся из Markdown, но не заменяют его, в них много формальностей, а диаграммы вроде Mermaid туда не помещаются
Сам /src/md, по мысли Гросса, должны писать и курировать в основном люди, а не агенты; саму структуру он называет самой слабой, непроверенной частью эссе

Почему это важно

При агентном кодинге разработчик обычно видит промпт и результат, сгенерированный код, а сама постановка задачи нигде не фиксируется и теряется вместе с сессией чата. Гросс формулирует это как смену статуса Markdown: из вспомогательной документации, живущей в вики или тикетах, он превращается в источник истины, из которого выводится код, то есть в исходный код в собственном смысле слова, который нужно хранить рядом с проектом, а не рядом с обсуждением задачи.

Кому это важно

Тем, кто уже сегодня строит рабочий процесс вокруг агентного кодинга, разработчикам, техлидам и командам, где ИИ-агент пишет заметную долю кода по промптам. Эссе адресовано именно практике организации репозитория и рабочего процесса, а не выбору конкретного инструмента или модели.

Как это применить

Завести директорию /src/md рядом с исходным кодом модуля и переносить туда архитектурные, а не только высокоуровневые проектные, решения: README.md как точку входа для агентов, TODO.md с открытыми задачами модуля, OVERVIEW.md с техническим обзором, и по необходимости, features/, data/, api/, infrastructure/ под описания функциональности, моделей данных, API и инфраструктуры. Дальше код и тесты выводятся из этих файлов, а не генерируются заново из очередной сессии промптов; изменения, которые вносятся напрямую в сгенерированный код, при необходимости переносятся обратно в Markdown.

Можно ли доверять

Это личное мнение практикующего ИИ-консультанта, основанное на его собственном опыте работы с клиентами, а не результат исследования или опрос индустрии: в тексте нет ни названных компаний или проектов, подтверждающих тренд, ни инструментов и фреймворков, которые уже реализуют такую структуру. Сам автор прямо называет предложенную структуру /src/md самой слабой и наименее опробованной частью эссе.

Риски и подводные камни

Конвенция ещё не проверена на практике даже самим автором. Ключевой риск, рассинхронизация: если разработчики правят сгенерированный код напрямую, а изменения не переносят обратно в Markdown, /src/md быстро устаревает и перестаёт быть источником истины. Дисциплина «агенты не пишут в /src/md», это ограничение, которое нужно поддерживать вручную, и сам Гросс не даёт готового ответа, как удерживать эти Markdown-файлы «чистыми, хорошо факторизованными и на правильном уровне абстракции» по мере роста проекта.

«Такое ощущение, что логика приложения всё больше определяется и редактируется в Markdown, а код, который генерирует агент, становится своего рода низкоуровневой деталью реализации.»

— Хартли Броди, эссе «Markdown is the new source code», процитировано Carson Gross