---
title: "ADSM: каталоги верхнего уровня"
date: 2025-11-22
---

*Это стадия 3 AFKP (погружение).\
Стадия 2 (резонанс) описывается [в
блоге](/ru/blog/2025/20251122-01-adsm-top-level-directories.html).*

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

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

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

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

Мой подход к структурированию файлов в проектах обусловлен как раз этими
аксиомами. Я уже [отмечал](https://habr.com/ru/articles/948282/), что
взаимодействие человека и агента происходит итерационно через
иерархически структурированный массив текстов. В этой публикации я
опишу, к какой структуре каталогов верхнего уровня в своих проектах с
использованием 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-агентом. По-большому
счёту, я отрефлексировал и зафиксировал в этой публикации свою практику.
Структура подкаталогов уровнями пониже уже просматривается, но пока что
я не готов её зафиксировать. Посмотреть описанную мной структуру
каталогов можно в моём
[демо-проекте](https://github.com/flancer64/pwa-home-call/tree/milestone/20251122-adsm-top-level-dirs).

*При желании 4-ю стадию по AFKP (осмысление) можно реализовать в этом
[телеграм-канале](https://t.me/alexgusev_lab_ru).*