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

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

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

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

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

./ctx/
    product/
    rules/
    agent/

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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