Когда мы работаем в паре с LLM-агентом, нужно принимать во внимание природу нашего "партнёра". Агент опирается только на тексты, действует в пределах ограниченного контекста и не удерживает долгосрочную историю. Поэтому особенно важным становится то, какие тексты мы ему предоставляем и как они структурированы.
Ниже - компактная, прикладная схема верхнего уровня, которую можно использовать в собственных проектах. Она помогает держать порядок, снижает шум для модели и делает работу агента более предсказуемой.
Общий принцип
Проект лучше разделять на три смысловых слоя:
./ctx/
product/
rules/
agent/Это мой рабочий подход, сформировавшийся из личного опыта взаимодействия с LLM-агентами.
Каждый слой отвечает за свою часть когнитивной нагрузки и используется агентом по-разному.
./product/ - смысловой каркас продукта
В этом каталоге находятся документы, которые описывают продукт как идею:
назначение продукта;
ключевые сценарии;
цели и ограничения;
особенности, которые определяют направление разработки.
Это "скелет" приложения. Здесь нет технических деталей. Этот слой задаёт вектор: зачем существует продукт и что именно должно быть реализовано.
Документы в ./product/ небольшие по объёму, но определяют весь остальной проект.
./rules/ - нормативы разработки
Этот каталог служит опорной точкой для любой генерации кода. Здесь собираются технические правила:
соглашения по организации модулей;
архитектурные решения;
структура слоёв приложения;
особенности платформы (например, DI, файловая организация, правила взаимодействия между зонами);
требования к стилю и оформлению кода.
./rules/ - это набор норм, которые направляют агента. Если они сформулированы ясно, модель работает стабильнее, предсказуемее и реже ошибается.
Этот каталог - основной инструмент для управления качеством генерации.
./agent/ - фиксация хода работы
Этот каталог предназначен для фиксации итераций:
отчёты агента по выполненным задачам;
(опционально) журнал поставленных задач.
Эти материалы помогают восстановить контекст спустя время или при подключении новых людей.
Каталог ./agent/ делает процесс разработки наблюдаемым и прозрачным.
Итоговая схема
Структура верхнего уровня каталогов в ADSM:
./ctx/
product/ - что мы делаем
rules/ - как мы это делаем
agent/ - что было сделаноТакой подход помогает упорядочить работу с LLM-агентами и уменьшить вероятность ошибок, связанных с перегрузкой контекста и смешением смыслов.
Полное изложение и обоснование
Более подробное обоснование почему у меня сложилась именно такая структура и как я к ней пришёл — здесь. Для этой публикации на Хабре я специально представил только самую суть.
Внимание - это ресурс, который быстро заканчивается.
Благодарю за внимание!
Посмотреть результат применения излагаемого подхода можно в проекте "flancer64/pwa-home-call".
Комментарии (7)
funca
22.11.2025 09:59Как расшифровывается ADSM? У меня только одна ассоциация: сказал A, говори и B.
flancer Автор
22.11.2025 09:59Я рассматривал оба варианта. Но народу зашло с "А".
funca
22.11.2025 09:59Шедевриально.
BDSM — Business Driven Software Management
ADSM — Agent Driven Software Management
Вы думаете, что смена инструмента как-то влияет на суть?
flancer Автор
22.11.2025 09:59BDSM — Bot Driven Software Management
ADSM — Agent Driven Software Management
Если в основе бота/агента лежит LLM, то суть не изменяется. Но название - да. Название меняется. Как и отношение людей к тому, что стоит за тем или иным названием.
Но до сути надо ещё докопаться, а название - оно вот, перед глазами.
Kamil_GR
Выглядит логично. Ещё бы промпт связки посмотреть.
flancer Автор
У меня только отчёты агентов по работам фиксируются. Сами запросы есть в логах моей учётки (облачная версия) или в IDE (консольная версия). Могу выложить, если интересно. Но я стараюсь задавать рамки агенту скорее через контекст, чем через запрос.
Хотя некоторые запросы довольно развесистые получались - я их делал через GPT. Анализировал через него кодовую базу, корпус документов, обговаривал детали итерации и просил поставить задачу для агента. Но в некоторых случаях я просто правил документы контекста и просил агента привести код к новой версии документов.
Да, у меня довольно плотное общение идёт с чатиком перед постановкой задачи - в целях экономии токенов Codex-агента.
flancer Автор
У меня, получается, есть два типа промптов.
1) Ссылочные промпты: в запросе указываю докуменатцию, на которую надо ориентироваться, и что нужно исправить.
2) Детальные промпты: совместно с ChatGPT обсуждаю документы контекста и прошу его сформулировать постановку задачи для Агента:
Скрытый текст
Обновление цветовой темы веб-приложения «HomeCall»
Цель
Применить к веб-интерфейсу новую палитру, основанную на галапагосском зелёном (Pantone 18-5725 TSX), и переработать стили для лучшей визуальной доступности пожилых пользователей.
Обновления касаются UI-стилей, не архитектуры и не namespace.
Требования к цветовой схеме
1. Основной акцентный цвет
Использовать галапагосский зелёный (18-5725 TSX) как главный акцентный цвет приложения.
Рекомендуемый HEX-эквивалент:
#0E6251
2. Градиенты
Ввести мягкие градиенты на:
фон домашнего экрана,
большую кнопку «Связать»,
возможные акцентные элементы.
Рекомендуемые градиенты:
Фон (горизонтальный или вертикальный):
от
#002D2A(очень тёмный зелёно-чёрный)к
#0E6251(галапагосский зелёный).Кнопка (центр светлее, края темнее):
от
#0FAF8F(осветлённая версия галапагосского)к
#0E6251(основной).Градиенты должны быть мягкими, без резкого перехода.
3. Дополнительная палитра (поддерживающие цвета)
Для сеньоров важна высокая контрастность, плавность восприятия и отсутствие “слепящих” оттенков.
Текст
Основной текст:
#EAF2F1(почти белый с лёгким зелёным оттенком — мягче на глаз).Вторичный текст / хинты:
#B8C7C3.Иконки
Акцентные иконки на кнопках:
#FFFFFFили#F0F7F6.Иконка настроек:
#EAF2F1.Статусы
Информация:
#6ECFC0Предупреждение:
#E9A944Ошибка:
#D95C4AВсе статусы должны иметь мягкие тени и хорошо смотреться на тёмном фоне.Разделители и линии
Использовать прозрачный белый:
rgba(255,255,255,0.08).4. UX для пожилых пользователей
Агент должен обеспечить:
высокую контрастность текста и кнопок;
достаточный отступ вокруг элементов;
отсутствие мелких шрифтов ниже 15–16 px;
мягкие тени для улучшения различимости.
5. Изменения в коде
Агент должен:
Обновить глобальные CSS/SCSS файлы, подключённые к интерфейсу, под новую палитру.
Переработать градиенты кнопки «Связать» и фона домашних экранов.
Проверить контрастность всех надписей на тёмном фоне.
Обновить цвета статусов, используя новую палитру.
Проверить SVG-иконки (телефон, шестерёнка, статусы):
заливки должны соответствовать новой схеме;
никаких “кислотных” оттенков.
Сохранить существующие namespace-модули
HomeCall_— ребрендинг касается только UI.6. HTML-файлы
Проверить файл
web/ui/enter.html.Рекомендация: переименовать в
web/ui/home.htmlдля консистентности.После переименования — обновить ссылки на HTML-файл.
Ограничения
Запрещено изменять существующие отчёты в
ctx/agent/report/**.Новый отчёт — создавать по правилам контекста (не задавать конкретное имя в постановке).
Результат
После выполнения:
домашняя страница должна выглядеть «глубокой», спокойной, дорогой;
интерфейс должен легко читаться пожилыми пользователями;
кнопка «Связать» должна выделяться, но не слепить;
палитра должна быть консистентной во всём UI.
Во втором случае я делаю конкатенацию документов из соответствующего каталога контекста (например,
ctx/rules/web/ui/) и чатик на основании этих документов делает постановку задачи агенту.В целом получается такой итерационный процесс, когда ты с удивлением смотришь на результат работы агента, а потом находишь и правишь в документации контекста те места, которые позволили агенту нагенерить ерунду.
Совершенно очевидно, что таким образом нельзя создавать приложения типа MS Office - слишком велик объём документации даже в иерархии, но своя ниша у такого способа разработки ПО явно есть.