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

Когда мы работаем в паре с LLM-агентом, нужно принимать во внимание природу нашего «партнёра». Агент опирается только на тексты, действует в пределах ограниченного контекста и не удерживает долгосрочную историю. Поэтому особенно важным становится то, какие тексты мы ему предоставляем и как они структурированы.

Ниже — компактная, прикладная схема верхнего уровня, которую можно использовать в собственных проектах. Она помогает держать порядок, снижает шум для модели и делает работу агента более предсказуемой.

Общий принцип

Проект лучше разделять на три смысловых слоя:

./ctx/ product/ rules/ agent/

Это мой рабочий подход, сформировавшийся из личного опыта взаимодействия с LLM-агентами.

Каждый слой отвечает за свою часть когнитивной нагрузки и используется агентом по-разному.

./product/ — смысловой каркас продукта

В этом каталоге находятся документы, которые описывают продукт как идею:

• назначение продукта;

• ключевые сценарии;

• цели и ограничения;

• особенности, которые определяют направление разработки.

Это «скелет» приложения. Здесь нет технических деталей. Этот слой задаёт вектор: зачем существует продукт и что именно должно быть реализовано.

Документы в ./product/ небольшие по объёму, но определяют весь остальной проект.

./rules/ — нормативы разработки

Этот каталог служит опорной точкой для любой генерации кода. Здесь собираются технические правила:

• соглашения по организации модулей;

• архитектурные решения;

• структура слоёв приложения;

• особенности платформы (например, DI, файловая организация, правила взаимодействия между зонами);

• требования к стилю и оформлению кода.

./rules/ — это набор норм, которые направляют агента. Если они сформулированы ясно, модель работает стабильнее, предсказуемее и реже ошибается.

Этот каталог — основной инструмент для управления качеством генерации.

./agent/ — фиксация хода работы

Этот каталог предназначен для фиксации итераций:

• отчёты агента по выполненным задачам;

• (опционально) журнал поставленных задач.

Эти материалы помогают восстановить контекст спустя время или при подключении новых людей.

Каталог ./agent/ делает процесс разработки наблюдаемым и прозрачным.

Итоговая схема

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

./ctx/ product/ — что мы делаем rules/ — как мы это делаем agent/ — что было сделано

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

Полное изложение и обоснование

Более подробное обоснование почему у меня сложилась именно такая структура и как я к ней пришёл — здесь. Для этой публикации на Хабре я специально представил только самую суть.

Внимание — это ресурс, который быстро заканчивается.

Благодарю за внимание!

Посмотреть результат применения излагаемого подхода можно в проекте «flancer64/pwa-home-call».

Источник: habr.com