ADSM: 7 уровней проектной документации

Меня зовут Алекс Гусев. Я продолжаю делиться своими наработками в области применения LLM-агентов для разработки приложений. В этот раз я покажу своё мини-приложение для перевода постов из русскоязычного телеграм-канала на английский и испанский, а заодно расскажу про 7 уровней проектной документации в ADSM.

LLM как синхронизатор мышления

В одной из дискуссий на Хабре у меня сформировалось ^[1] понимание того факта, что современные LLM-модели с одной стороны являются агрегаторами совокупного опыта ^[2] человечества, а с другой – форматируют отдельных людей под этот опыт (ну, кто поддаётся, разумеется).

Я, например, до общения с GPT-чатом не употреблял слова типа “нарратив“, “онтология“, “оптика” и т.п. В русскоязычных текстах, генерируемых LLM, я часто вижу “кальку” с английских оборотов речи. И постепенно привыкаю к этим терминам и сам начинаю их употреблять.

Что касается 7 уровней документации в ADSM ^[3], то они появились чисто под давлением GPT (коллективного человеческого опыта). Как результат наших с ним дискуссий. Я бы сам точно сделал по-другому.

7 уровней

Тем не менее, в результате нашего совместного с GPT творчества ^[4] мы сформулировали вот такие уровни:

1. AGENTS — правила работы с агентом и требования к формализации знаний.

2. Constraints — жёсткие рамки и запреты, ограничивающие пространство решений.

3. Product — смысл системы, её назначение и предметные инварианты.

4. Architecture — структурная форма: агрегаты, границы, внешние интерфейсы.

5. Composition — модель выполнения: run-cycle, фазы и точки завершения.

6. Environment — условия исполнения: runtime-предпосылки и инфраструктурные ограничения.

7. Code — инженерная реализация: контракты, DI, тестирование, обработка ошибок.

Все эти уровни можно увидеть на примере: @flancer64/tg-wa-blog-post ^[5]

AGENTS

Это самый важный уровень – инструкции для агентов ^[6]. Я работаю только и исключительно с OpenAI Codex. Как реагируют на эти инструкции другие агенты – я не в курсе. Codex реагирует отлично.

Уровень AGENTS регламентирует поведение ^[7] LLM-агента по отношению ко всему корпусу проекта: документации, исходному коду, тестам, конфигурации и структуре каталогов. Эти документы распределены по различным разделам проекта и задают правила чтения, изменения и расширения материалов. Уровень определяет стиль формализации, требования к непротиворечивости и границы допустимых действий агента, обеспечивая управляемость эволюции системы. Именно с этого уровня идут ссылки на другие документы контекста.

Constraints

Constraints ^[8] определяет жёсткие рамки проектирования: что допускается и что исключено. Этот уровень ограничивает пространство решений до начала архитектурных обсуждений. Он предотвращает бесконтрольное усложнение и защищает инварианты системы от размывания.

Product

Product ^[9] формализует смысл системы: её назначение, предметную область и базовые инварианты. Здесь фиксируется, что система делает и в каких границах существует её ценность. Этот уровень отвечает на вопрос «зачем» и служит основанием для всех последующих решений.

Architecture

Architecture ^[10] описывает структурную форму системы: ключевые сущности, границы, внешние интерфейсы и инварианты целостности. Он переводит смысл в устойчивую модель формы. Архитектурный уровень отвечает на вопрос «из чего и как устроено».

Composition

Composition ^[11] формализует поведение ^[12] системы как целостный сценарий: фазы выполнения, переходы состояний, точки завершения. Этот уровень связывает архитектурные элементы в управляемую динамику. Он отвечает на вопрос «как система работает во времени».

Environment

Environment ^[13] фиксирует условия существования системы: предпосылки исполнения, инфраструктурные зависимости и внешние ограничения среды. Этот уровень отделяет логическую модель системы от контекста её запуска и эксплуатации.

Code

Code ^[14] описывает инженерные инварианты реализации: правила связывания зависимостей, обработку ошибок, тестирование, наблюдаемость. Он переводит все вышестоящие уровни в исполняемую форму, не изменяя их смысл. Это уровень материализации контекста в конкретной технологии.

Выводы из практики

Если рассматривать эти уровни в совокупности, становится видно, что они различаются по характеру и объёму.

Уровень AGENTS невозможно выделить в один отдельный каталог. Это совокупность файлов, распределённых по всему проекту. Они не очень большие, но их много.

Product и Architecture получились относительно компактными и при этом содержательными. В нескольких документах фиксируются смысл системы и её структурная форма. Эти уровни помогают удерживать целостность проекта и задают устойчивую основу для последующих решений.

Constraints и Composition появились во многом в ходе диалога с GPT. Изначально я не выделял их как самостоятельные уровни, однако в процессе работы стало ясно, что разделение запретов и сценария выполнения облегчает формализацию знаний и снижает количество разночтений. Сейчас я воспринимаю их как отдельные элементы структуры, за которыми стоит определённая логика ^[15].

Environment для меня выглядит естественным слоем, описывающим условия существования системы. Он относительно небольшой по объёму.

Самым объёмным остаётся Code: по количеству документов он превосходит остальные уровни. При этом речь идёт не о написании кода, а о фиксации правил его организации и развития.

В итоге получилась неоднородная структура с разной «мощностью» уровней. Тем не менее именно в таком виде она позволяет поддерживать ясность контекста и постепенно развивать проект вместе с агентом.

Результат

На формирование корпуса документации для этой утилиты у меня ушло около четырёх с половиной часов. После этого агент за пять–семь минут сгенерировал код, который заработал после двух небольших правок. Я использую собственную библиотеку для внедрения зависимостей @tefw/di ^[16], что явно не облегчает жизнь агентам, и одна из ошибок была связана с циркулярной зависимостью. Тем не менее итог оказался рабочим и воспроизводимым — при тестировании сообщение в русскоязычный канал дублировалось на английском и испанском языках после запуска утилиты.

Главное впечатление ^[17] — перенос центра тяжести. Существенная часть времени уходит на формализацию контекста. Документы контекста в несколько раз объёмнее, чем документы кода. Работа смещается в сторону анализа предметной области, структурирования инвариантов и фиксации правил. В этом режиме я всё чаще выступаю как системный аналитик и архитектор, удерживая целостность модели.

При дальнейших итерациях проявляется другая особенность. Агент уверенно создаёт первичную версию, однако при расширениях начинает задевать существующие связи. Мне даже кажется, что агенту проще перегенерировать весь код с нуля, чем внести правки в существующий код. Если какие-то ограничения заранее не зафиксированы в контексте, это отражается в коде, и требуется разбор и корректировка. Для управления процессом по-прежнему нужно понимать архитектуру и реализацию. И уметь пользоваться отладчиком :)

Резюме

Разговоры о полном вытеснении программистов LLM-агентами, на мой взгляд, выглядят преждевременными. Разработка с LLM требует сочетания ролей: аналитика, архитектора, продакта и инженера. Контекст становится основным инструментом, а код — его следствием.

В принципе, для контекста уровня 2-5 даже не особо важно, на каком ЯП и в каком окружении будет реализовываться приложение. Это достаточно абстрактная документация. Уровни 1, 6, 7 уже “привязывают” проект “к земле“.

В качестве пруфа – мои каналы, для которых я делал приложение:

• ru ^[18]

• en ^[19]

• es ^[20]

Если подписаться на все три, то можно будет увидеть утилиту в действии ;)

Мой сайт: wiredgeese.com ^[21]

Спасибо всем, кто дочитал!