Это стадия 3 AFKP (погружение).
Стадия 2 (резонанс) описывается в
блоге.
Языковая природа агентов
В основе самых популярных ныне агентов, используемых для создания программных приложений, лежат Большие Языковые Модели (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-агентом. По-большому счёту, я отрефлексировал и зафиксировал в этой публикации свою практику. Структура подкаталогов уровнями пониже уже просматривается, но пока что я не готов её зафиксировать. Посмотреть описанную мной структуру каталогов можно в моём демо-проекте.
При желании 4-ю стадию по AFKP (осмысление) можно реализовать в этом телеграм-канале.