ADSM: каталоги верхнего уровня

Дата публикации: 2025-11-22

Языковая природа агентов

В основе самых популярных ныне агентов, используемых для создания программных приложений, лежат Большие Языковые Модели (LLM). Главное, что делает "интеллектуальный" агент - готовит запрос для LLM (промпт), а затем разбирает результат выполнения запроса и фиксирует его в виде нового текстового файла (например, с исходным кодом) или в виде изменений к существующим.

На данный момент я могу сформулировать 4 положения, которые я назвал "4 аксимомы ADSM":

Языковая модель в силу своей природы способна служить инструментом преобразования знаний в код без необходимости их понимания.
Всё взаимодействие с моделью происходит только через текст.
Модель работает лишь с текстами, статистически значимыми для неё.
Инференс модели выполняется в пределах конечного контекста, внутри которого с ростом объёма падает плотность статистических связей.

Мой подход к структурированию файлов в проектах обусловлен как раз этими аксиомами. Я уже отмечал, что взаимодействие человека и агента происходит итерационно через иерархически структурированный массив текстов. В этой публикации я опишу, к какой структуре каталогов верхнего уровня в своих проектах с использованием LLM-агентов я пришёл на данный момент.

Код и документы

Изначально у меня был подход с разделением всех файлов на два репозитория на GitHub'е:

документы по проекту: когнитивный контекст, в котором совместно работают человек и LLM-агент.
код приложения (исходники): конечный результат их взаимодействия.

Чтобы агент мог действовать в обоих пространствах, два отдельных репозитория собирались в одну файловую структуру при настройке окружения Codex-агента в его облачной версии. Я монитировал репозиторий с документами в каталог ./ctx базового репозитория (с исходниками) при запуске Codex-агента и для него это была единая файловая структура, хотя по факту она была разнесена по различным репозиториям. При этом агент мог коммитить изменения только в базовый репозиторий. Документы по проекту использовались им в режиме read-only.

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

Понятно, что выбранный для имплементации язык программирования налагает свои требования к файловой структуре репозитория с исходным кодом. Файлы проекта на python будет отличаться от файлов nodejs-проекта, но в обоих случаях в репозитории с исходным кодом можно примонтировать каталог ./ctx/ и разместить в нём документы когнитивного контекста. Или даже не монтировать, а сразу создавать каталог ./ctx/ прямо в репозитории с исходным кодом - если проект не слишком велик. В этом случае появляется бонус - агент может также изменять и документацию, если надо.

Продукт и приложение

Следствием этого понимания стала мысль, что всю документацию в каталоге ./ctx/ можно поделить на две неравные части:

бизнес-описание продукта: малый корпус документов, описывающих идею продукта.
правила создания соответствующего ему приложения: бОльший по объёму корпус документов, регламентирующий правила создания продукта на выбранном ЯП или группе ЯП.

./ctx/
    product/
    rules/

Документы в каталоге product/ задают скелет будущего приложения. Они регламентируют, что должно делать приложение, но не говорят, как. По сути, эти документы форматируют поле действий для агента и направляют его внимание на важные с точки зрения бизнеса моменты. Это изложение статистически уникальных положений. Как правило каждая бизнес-идея стремится отличаться от конкурирующих и эти документы содержат такие положения, которые вряд ли входили в обучающую выборку модели, на которой базируется агент.

Документы в каталоге rules/ являются наиболее важной частью для генерации/правки кода агентом. Они регламентируют действия агента на уровне, необходимом для написания исходного кода. В силу статистической природы LLM, чем более "средневзвешенно" сформулированы эти документы, чем ближе они к "среднему" по обучающей выборке - тем меньше нужно текста в этих документах, чтобы агент мог генерировать работющий исходный код, руководствуясь этими правилами.

Я в своём демо-проекте создавал веб-приложение с применением моего собственного контейнера объектов с внедрением зависимостей в конструкторе, что потребовало нескольких отдельных документов в ./rules/, регламентирующих правила создания новых es6-модулей, которые могли бы использоваться моим контейнером.

Общение человека с агентом

./ctx/
    agent/

По большому счёту, в этом каталоге находится оперативная информация, которая сразу же становится архивной. Через этот каталог агент сообщает своему руководителю (человеку) о том, какие действия он предпринял в рамках текущей итерации работы над кодом (выполнением поставленной задачи). Как правило, человек, ставящий агенту задачу, находится в контексте задачи на момент её постановки, но очень быстро (примерно в течение двух недель, по моему опыту) этот контекст рассасывается и забывается.

Если человек работает над проектом в одиночку, как в моём случае, то необходимость таких отчётов неочевидна - агенты работают достаточно быстро, чтобы я не успевал выпасть из контекста задачи (меньше часа). Но для командной разработки или разработке, растянутой во времени, такие отчёты полезны в силу их возможности помочь любому члену команды "кожаных" восстановить контекст разработки при его потере. Также такие отчёты бывают весьма полезны в случае неправильного выполнения команд агентом - анализ этих отчётов помогает обнаружить причины, почему агент неправильно понял постановку задачи.

Изначально, когда я разделял документы контекста и исходники по разным репозиториям, этот каталог не входил в когнитивный контекст, так как должен был являться частью базового репозитория, чтобы иметь возможность коммитить изменения в облачной версии Codex-агента. В случае запуска CLI-версии агента или если и исходники, и когнитивный контекст находятся в одном репозитории, каталог ./agent/ можно держать внутри когнитивного контекста (./ctx).

Резюме

Так как основой любого агента, а не только Codex'а, является подготовка промпта для LLM и преобразование результата инференса, то файлы в проекте нужно структурировать так, чтобы они учитывали природу LLM. В моём случае у меня получается такая структура для каталогов верхнего уровня:

./ctx/
    agent/
    product/
    rules/

Такая структура не является сколько-то признанной - это просто отображение моего опыта взаимодействия с Codex-агентом. По-большому счёту, я отрефлексировал и зафиксировал в этой публикации свою практику. Структура подкаталогов уровнями пониже уже просматривается, но пока что я не готов её зафиксировать. Посмотреть описанную мной структуру каталогов можно в моём демо-проекте.