Всем привет! Меня зовут Катя, я развиваю Gramax — базу знаний для ИТ-команд.

Мы в команде давно и настойчиво говорим об одном: документация — это не довесок к разработке, это ее часть. Писать доку нужно до кода, вместе с кодом, а не после — когда контекст уже размылся, а решения давно забыты. Считаем, что это инженерная культура, без которой появляется куча проблем: медленный онбординг, повторяющиеся споры об уже принятых решениях, техдолг.

Один из примеров такой документации — Architecture Decision Records — короткие структурированные документы, которые фиксируют одно конкретное архитектурное решение вместе с контекстом, рассмотренными альтернативами и принятыми trade-off'ами.

На эту статью меня вдохновил испанский ИИ-слоп и тред на Hacker News вокруг вопроса «как вы фиксируете ПОЧЕМУ инженерных решений, а не только ЧТО?». В статье напомню, зачем нужен ADR и какие есть стандартные проблемы. Также приведу выжимки из кейсов, в которых описаны любопытные ИИ-автоматизации.

Контекст проблемы

Популярная проблема: новый разработчик с десятью годами опыта (нанятый именно потому что «сильный») три недели занимается тем, что называют code archaeology — раскопками. Он пытается понять почему этот код именно такой.

Чтобы исправить ситуацию, команды проходят один и тот же путь. Сначала «давайте писать нормальные описания к PR» -> потом «заведем wiki» -> потом «добавим шаблон к PR с обязательным полем». Почему это часто не работает:

  • Комментарии в коде объясняют как, но не почему.

  • Описания PR — это летопись намерений в момент написания. «fix bug», «refactor», «add feature».

  • Wiki умирают от устаревания. Страницу создают в момент, когда решение принято и контекст свеж. Через полгода страница описывает архитектуру, которой уже нет, а удалить ее жалко, потому что там что-то написано.

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

Результат — то, что в англоязычном сообществе называют knowledge debt.

Коротко про ADR

Architecture Decision Records — короткие структурированные документы, которые фиксируют одно конкретное архитектурное решение вместе с контекстом, рассмотренными альтернативами и принятыми trade-off'ами. Минимальная структура ADR:

  • Заголовок и статус — Proposed / Accepted / Deprecated / Superseded.

  • Контекст — какая ситуация спровоцировала это решение, какие были ограничения.

  • Решение — что конкретно было решено.

  • Рассмотренные альтернативы — что отвергли и почему.

  • Последствия — что стало проще, что стало сложнее, какие trade-off'ы приняты.

Важная деталь, которую часто упускают: ADR не редактируются. Если решение изменилось — старый ADR помечается как Superseded by ADR-XXX и создается новый. Референсный проект adr.github.io поддерживает открытые шаблоны и CLI-инструменты для управления ADR прямо из репозитория.

Для команд, которым нужно что-то еще проще, есть формат Y-Statement:

«Поскольку [контекст], мы решили [решение], чтобы достичь [желаемый результат], принимая [последствия или trade-off'ы].»

Docs as Code: документация встраивается в рабочий процесс команды

Одна из структурных пробл��м документации состоит в том, что она живет за пределами рабочего процесса инженера. Решение — Docs as Code: документация хранится в том же Git-репозитории, что и код, ревьюится в том же PR, версионируется в том же коммите.

Это подразумевает:

  • Хранить ADR в том же Git-репозитории, что и код (например, в папке /docs/decisions/).

  • Ревьюить ADR в том же PR, что реализует архитектурное изменение.

  • Автоматизировать проверки (битые ссылки, формат, обязательные поля) в CI/CD-пайплайне.

  • Версионировать ADR: когда решение меняется, предыдущий ADR не удаляется — он помечается как Superseded by ADR-XXX, и создается новый.

Согласно лучшим практикам, задокументированным Xenoss и AltexSoft, этот подход резко снижает устаревание, потому что документация и код эволюционируют в одном коммите.

Следующий шаг — ИИ-автоматизация. Смотрим кейсы

Идем дальше: если практика написания ADR уже прижилась и документы хранятся в легковесном Markdown — почему бы не автоматизировать какую-то работу с помощью ИИ?

Мы нашли несколько статей, авторы которых так или иначе упростили себе работу. Возможно, вас они вдохновят.

Сразу оговорка: ИИ везде выступает генератором черновика, а не автором решения. Человек в петле — обязательное условие. И второй общий момент: качество результата определяется не тем, насколько умен ИИ, а тем, насколько хорошо ему передан контекст.

Кейс 1: ИИ сам находит незадокументированные решения в коде

Задокументированный на Adolfi.dev кейс показывает, как использовался Claude Code для сканирования существующего Umbraco-проекта. Задача необычная: не написать ADR для нового решения, а найти решения, которые уже были приняты, но нигде не зафиксированы. Инструкция была буквально такой:

I want to scan my code base for high-priority ADR using the template described in template.md.
Each individual ADR record should be created in folder /ADR/records.

Агент проанализировал код, выявил паттерны принятых решений и сгенерировал черновики ADR. Важный момент: это именно черновики. Инженер проверяет, обогащает контекстом и утверждает. Без этого шага ценность теряется — агент не знает, какие ограничения действовали в тот момент.

Следующий шаг — непрерывная генерация. В конфигурацию agents.md добавляется инструкция: «всякий раз, когда вно��ятся изменения, затрагивающие архитектуру, создавай ADR».

Кейс 2: десятки ADR за одно утро

Equal Experts в октябре 2025 описали, как команда столкнулась с задачей ретроспективно задокументировать десятки архитектурных решений на крупном платформенном проекте. Использовали Gemini 2.5 и ChatGPT, без специализированных инструментов — только стандартные веб-интерфейсы.

Их ключевая техника — metaprompting: сначала собираются «ядра истины» (kernel of truth) — однострочные формулировки типа «22 апреля решили использовать DBT, потому что SQL-based, open-source и работает с Databricks». Потом метапромпт превращает каждое такое ядро в полноценный черновик ADR. Результат: десятки ADR за одно утро.

Самое ценное в статье — честное описание проблем. ИИ стабильно галлюцинировал: придумывал несуществующие API, страницы документации, фичи продуктов. Логика обоснований иногда не совпадала с реальным контекстом решения.

Как исправили: добавили в промпт явные указания — «ссылки ДОЛЖНЫ существовать, проверь каждую», «не выдумывай фичи продукта». И подключили второй LLM в роли судьи, который критикует сгенерированный ADR на логические противоречия до того, как его увидит человек.

Кейс 3: методология Salesforce

Salesforce опубликовал свою методологию и принцип там сформулирован довольно четко: human-led, AI-powered. Архитектор определяет контекст и критерии оценки — безопасность, масштабируемость, стоимость, поддерживаемость. ИИ исследует альтернативы, оценивает trade-off'ы и составляет черновик ADR. Финальное решение и весь качественный контекст — только от человека. Они даже дали этому отдельное название — HITL (human-in-the-loop) — и посвятили ему отдельный раздел методологии.

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

Еще одно их наблюдение: ИИ снижает предвзятость. Когда архитектурное решение принимает конкретный инженер, на него влияют личные предпочтения и усталость от технологий, которые он уже использовал. ИИ оценивает альтернативы без замыленного глаза.

Кейс 4: многоагентная система для написания ADR

Еще один кейс описан архитектором NN Group — он столкнулся с задачей спроектировать future-state архитектуру для data & AI платформы и задокументировать все ключевые решения. Когда он начал считать количество ADR, которые нужно написать, стало понятно — вручную это нереально.

Он построил ADR Writer Agent на базе OpenAI Agent SDK с разделением ответственности между тремя специализированными агентами:

  • Главный агент (ADR Writer) — ведет диалог с пользователем, генерирует черновик ADR на основе загруженного PDF с архитектурным предложением и шаблона в формате Markdown.

  • Агент-валидатор — проверяет черновик на наличие всех обязательных полей перед финализацией. Если чего-то не хватает — возвращает на доработку и запрашивает у пользователя недостающую информацию.

  • Агент-форматировщик — принимает валидированный контент, проверяет корректность Markdown и записывает финальный файл на диск.

Отдельный важный момент для тех, кто работает в энтерпрайзе: агент работает внутри корпоративной инфраструктуры NN Group через Azure OpenAI с аутентификацией через Entra ID — не через публичный API. Это значит, что архитектура безопасности и compliance-требования были заложены с самого начала, а не прикручены потом.

Главный вывод, который он сформулировал сам: удивительно, как мало кода нужно при агентном подходе. Промпты часто заменяют бизнес-логику — вместо жесткого кодирования правил тщательно написанные инструкции агентам.

Зачем мы это исследуем в контексте Gramax

Gramax — база знаний для ИТ-команд.

  • Вся документация хранится в легковесном MD на вашем сервере. В одном репозитории с кодом или отдельно — как пожелаете.

  • Версионируется с помощью Git. Сделали ветку по задаче — добавили в эту ветку документацию.

  • Для нетехнических специалистов мы сделали удобный визуальный редактор, а технические могут работать с докой в привычной IDE. Из любого представления дока открывается в едином источнике правды.

  • Простая реализация Docs as Code для автоматизации.

Это значит, что любой из описанных пайплайнов с ИИ — сканирование кодовой базы, metaprompting, многоагентная генерация — подключается напрямую. Агент пишет MD-файл в папку /docs/decisions/, он сразу появляется в Gramax с навигацией, поиском и историей изменений.

Так ADR выглядит для менеджера:

А вот так для разработчика:

Все атрибуты ADR сохраняются во фронтматтере, описание архитектуры — в Mermaid-диаграмме. А текст — это просто MD-текст. Все легко читается как человеком, так и машиной.

Открыто, бесплатно, и с сообществом