ADSM: каталоги верхнего уровня
Краткое резюме
Для эффективной работы с LLM-агентом проект следует структурировать по слоям: ./product/ (описание продукта), ./rules/ (технические правила) и ./agent/ (отчёты агента). Такая организация данных улучшает предсказуемость и качество работы модели.
При совместной работе с LLM-агентом необходимо учитывать особенности его функционирования. Агент оперирует исключительно текстовой информацией, действует в рамках ограниченного контекста и не сохраняет долгосрочную историю взаимодействий. Поэтому критически важно, какие тексты мы предоставляем агенту и как они структурированы.
Ниже представлена компактная схема верхнего уровня, которая может быть использована в собственных проектах. Она помогает поддерживать порядок, снижает «шум» для модели и делает работу агента более предсказуемой.
**Общий принцип**
Проект рекомендуется разделять на три смысловых слоя:
* ./ctx/;
* ./product/;
* ./rules/;
* ./agent/.
Это рабочий подход, сформированный на основе личного опыта взаимодействия с LLM-агентами. Каждый слой выполняет свою часть когнитивной нагрузки и используется агентом по-разному.
**Слой ./product/** представляет собой смысловой каркас продукта. В этом каталоге находятся документы, описывающие продукт как идею:
* назначение продукта;
* ключевые сценарии;
* цели и ограничения;
* особенности, определяющие направление разработки.
Этот слой задаёт вектор: зачем существует продукт и что именно должно быть реализовано. Документы в ./product/ небольшие по объёму, но определяют весь остальной проект.
**Каталог ./rules/** служит опорной точкой для любой генерации кода. Здесь собираются технические правила:
* соглашения по организации модулей;
* архитектурные решения;
* структура слоёв приложения;
* особенности платформы (например, DI, файловая организация, правила взаимодействия между зонами);
* требования к стилю и оформлению кода.
Это набор норм, которые направляют агента. Если они сформулированы ясно, модель работает стабильнее, предсказуемее и реже ошибается. Этот каталог — основной инструмент для управления качеством генерации.
**Каталог ./agent/** предназначен для фиксации итераций:
* отчёты агента по выполненным задачам;
* (опционально) журнал поставленных задач.
Эти материалы помогают восстановить контекст спустя время или при подключении новых людей. Каталог ./agent/ делает процесс разработки наблюдаемым и прозрачным.
**Итоговая схема**
Структура верхнего уровня каталогов в ADSM выглядит следующим образом:
* ./ctx/;
* ./product/ — что мы делаем;
* ./rules/ — как мы это делаем;
* ./agent/ — что было сделано.
Такой подход помогает упорядочить работу с LLM-агентами и уменьшить вероятность ошибок, связанных с перегрузкой контекста и смешением смыслов.
Более подробное обоснование структуры и путь к её формированию можно найти по ссылке. В этой публикации на Хабре представлено только самое главное.
Результат применения излагаемого подхода можно увидеть в проекте «flancer64/pwa-home-call».
Благодарю за внимание!