| name | aidd-methodology |
| description | AI-Driven Development — методология и принципы написания документации для проектов с LLM-агентом. Используй когда: AIDD, AI-driven, планирование проекта, idea.md, vision.md, workflow.md, архитектура, документация, написание документации, обновление документации, doc, md-файл, Context First, итерация, tasklist, ADR.
|
AI-Driven Development (AIDD)
Суть методологии
Разработчик = технический директор / архитектор.
LLM-агент = исполнитель, которому делегируется написание кода.
AIDD — это методология, в которой разработчик фокусируется на:
- Проработке архитектуры системы
- Определении соглашений и контрактов
- Ведении проектной документации
- Принятии технических решений
Реализация (написание кода, boilerplate, типовые паттерны) делегируется LLM-агенту на основе подготовленного контекста.
Агент не принимает архитектурных решений самостоятельно. Все планы и решения проходят ревью архитектора перед реализацией.
Context First
Качество результата определяется качеством входного контекста.
Документация — основной инструмент передачи контекста агенту. Чем точнее и полнее описаны архитектура, контракты и ограничения — тем меньше итераций на исправление.
Правило: согласуй архитектуру и подходы до начала генерации кода. Переделывать дороже, чем планировать.
Опирайся на существующую документацию проекта, не отклоняйся от зафиксированных спецификаций. Открытые вопросы и неоднозначности — прорабатывай через архитектора.
Написание документации
Баланс краткости и полноты
Правило: каждый абзац несёт сигнал, не шум. Избегать воды, повторов, очевидностей из соседнего контекста. Но краткость не должна приводить к потере:
- Ключевых инсайтов и нетривиальных решений
- Контекста "почему так" (не только "что")
- Ограничений, рисков, неочевидных зависимостей
Если информация уже представлена в одном формате (таблица), не дублировать в другом (список) без явной необходимости.
Уровень абстракции
Документация остаётся на уровне интерфейсов, контрактов, ответственностей — не реализации.
Фильтр: документируй решения и контракты, не их воплощение. Конкретные имена модулей, параметры конфигурации, конструкции фреймворков — это воплощение, оно живёт в коде и меняется независимо от архитектуры.
Избегать:
- Boilerplate-код и типовые реализации
- Детали, очевидные из названия метода/класса
- Пошаговые инструкции там, где достаточно указать направление
Погружаться в детали только когда:
- Пользователь явно просит
- Деталь критична для понимания (неочевидное поведение, edge case, хак)
- Без неё решение нельзя воспроизвести
Глубина по типу документа
Разные типы документов занимают разные ниши по уровню детализации. Смешивание уровней делает документы нечитаемыми — деталь реализации во вводной архитектурного документа отвлекает от главного, а обобщённое описание в implementation plan не даёт агенту работать.
| Тип | Уместно | Не уместно |
|---|
Архитектурные документы (tech/, product/, idea.md, vision.md) | Компоненты, контракты, инварианты, архитектурные диаграммы | Детали реализации классов, private-методы, внутренние шаги отладки |
| Design-brief | Контекст, решения, trade-offs, диаграммы. Должен быть пригоден для показа команде | Импл-детали уровня implementation plan, пошаговые планы фаз |
| Implementation plan | Импл-детали, фазы, verification steps | Архитектурные обоснования (их место — design-brief / ADR) |
| Research, reference | Свободный технический стиль, глубокий анализ, техничные термины без пояснений | — |
Уровень документа определяет уровень деталей. Архитектурный документ описывает компоненты и их ответственности. Какая конкретная технология используется — фиксируется один раз (в секции стека или при первом упоминании компонента), не при каждом упоминании. Если документ описывает, что Checkpointer хранит состояние — этого достаточно. Что он использует PostgreSQL, а не SQLite — это деталь стека, не архитектуры.
От общего к частному. Вводная часть документа отвечает на «что он описывает и для кого». Детали реализации, внутренние слои, инварианты — в подсекциях, не в первом абзаце. Частый антипаттерн — архитектурный документ, который во втором предложении вводной уходит в детали упаковки логики по слоям: читатель, ищущий «что делает эта система», получает «как она спрятана внутри».
Пример — плохо:
class ImageService:
def __init__(self, minio_client):
self.minio = minio_client
def upload(self, image_bytes, filename):
self.minio.put_object(...)
Пример — хорошо:
ImageService
├── upload(image) → presigned_url
├── get_variants(prompt) → [url, url, url]
└── edit(url, instructions) → new_url
Код — это шум. Интерфейс — это сигнал.
Что фиксировать обязательно
При документировании решений и архитектуры сохранять:
- Почему — причины выбора, отвергнутые альтернативы
- Инсайты — неочевидные выводы, к которым пришли в процессе
- Ограничения — что не работает, где границы применимости
- Контекст — при каких условиях решение валидно
Эти элементы часто теряются со временем и восстанавливаются дорого.
Single Source of Truth
Любая информация подробно описывается только в одном месте. В связанных документах — ссылка и краткий тезис (1-2 предложения).
Это предотвращает "дрейф документации": когда меняем в одном месте, забываем в другом, и документы начинают противоречить друг другу.
Формат ссылки:
Аутентификация реализована через JWT. Подробнее: [auth.md](./auth.md)
Один концепт — разные документы для разных целей: ADR (обоснование решения) и архитектурный документ (описание работы) для одного концепта — допустимая практика. Каждый документ отвечает на свой вопрос (почему vs как). Дублирование фактов минимизируется: архитектурный документ ссылается на ADR для обоснования, а не повторяет его.
Внутри документа — тот же принцип. Деталь (технология, решение, ограничение) фиксируется один раз в релевантной секции. В остальных местах — упоминание без повторения деталей. Повторение допустимо только когда контекст секции действительно требует эту деталь для понимания.
Типичный антипаттерн: технология указана в секции "Стек", а затем повторяется при каждом упоминании компонента по всему документу.
Структура следует за автором
По умолчанию сохранять порядок изложения, который задал пользователь. Документ может отражать ход мысли автора: к чему пришёл сначала, потом, в итоге.
Типовые академические шаблоны (введение → основная часть → заключение) не обязательны. Если структура неясна — лучше уточнить у пользователя.
Outline-first
При создании нового документа или существенном изменении существующего:
- Предложи аутлайн (структуру)
- Архитектор ревьюит, даёт обратную связь, прорабатывает открытые вопросы
- На основе утверждённого аутлайна — пиши полный документ
Визуализации в документах
В Markdown-документах: диаграммы — Mermaid, таблицы — Markdown tables. ASCII-art допустим только в интерактивном диалоге (чат), где Mermaid не рендерится.
Языковая гигиена
Применимо, когда язык документации не совпадает с языком кода (например, документация на русском, код на английском). Правило определяет, какие иностранные термины сохраняются в тексте, а какие переводятся.
Правило по умолчанию: сохраняй оригинал. Перевод — активное действие, требующее обоснования; сохранение — нет. Причина: оригинальные термины связаны с кодом, документацией инструментов, литературой и другими документами проекта. Перевод эту связь рвёт.
Сохраняем:
- Имена из кода: классы, функции, API, event types, константы
- Идентификаторы стандартов и категорий (имена алгоритмов, кодов, классов стандартов) — работают как имя, не как описание
- Технические термины, устоявшиеся в сообществе / литературе / коде проекта — перевод, даже точный, ухудшает связь с источниками
- Имена продуктов и инструментов
- Заголовки секций, работающие как конвенция и повторяющиеся между документами проекта
Переводим:
- Составные кальки через дефис, где перевод передаёт смысл без потерь
- Прилагательные с нормальным русским (или целевого языка) эквивалентом
- Общие слова, используемые не как термин
Тест перед переводом: передаёт ли перевод тот же смысл с той же точностью и узнаваемостью? Теряется специфичность (термин становится более общим словом), рвётся связь с источниками, падает поисковая находимость — сохраняем оригинал.
Консистентность выбора в пределах документа. Если для двуязычного термина выбран вариант (оригинал или перевод) — держи его последовательно в пределах одной таблицы, секции или главы. Не чередуй без явной причины.
Если не уверен — проверь в коде. Если термин выглядит как возможное имя из кода или тега шаблона, но без обратных кавычек или контекста — загляни в соответствующий файл (imports, definitions, текстовый поиск). Это не блокирующее требование: при отсутствии быстрого способа уточнить — сохраняй оригинал (bias на сохранение).
Применимость к диаграммам и визуализациям. Правила распространяются на содержимое любых визуальных представлений — Mermaid, ASCII-диаграммы (графы, таблицы, блок-схемы), Graphviz и прочие. Текст нод, label'ы связей, легенды, подписи подчиняются тем же критериям, что и основной markdown.
Маркеры «это имя из кода» (сохраняются даже без обратных кавычек): угловые скобки (<tag> — XML-тег или плейсхолдер шаблона), snake_case / CamelCase идентификаторы, конструкции вида .method(), a.b.c. В диаграммах такие имена легко теряются при переформулировке — специально не перерабатывать.
Актуализация
В AIDD документация — основной интерфейс между сессиями. Неактуальная документация означает сломанный контекст для следующей сессии. Это делает дрейф документации особенно дорогим.
Актуализация — обязательный этап после реализации. При завершении существенной работы (не каждого мелкого ответа) — проверить, что затронутые документы отражают фактическое состояние. При сомнениях — уточнить у архитектора.
Когда создавать новый документ
Сигналы к выделению в отдельный документ:
- Кросс-сервисный концепт — затрагивает несколько сервисов или слоёв
- Самодостаточность — секция в существующем документе обросла собственной иерархией подсекций и связями
- Объём — концепт занимает значительную часть документа (как правило, следствие предыдущих пунктов)
- Собственный жизненный цикл — концепт будет развиваться независимо
- Ключевая доменная абстракция — центральная концепция продукта
Сигналы НЕ выделять:
- Концепт используется только внутри одного документа и не имеет потенциала роста
- Информации мало и нет сложных подтем
Структура документации проекта
Типовая структура (адаптируется под конкретные нужды):
doc/ # Корневая директория документации
├── idea.md # Идея, проблема, целевая аудитория
├── vision.md # Техническое видение, стек, архитектура верхнего уровня
├── workflow.md # Рабочий процесс (опционально)
├── index.md # Навигация по документации (опционально)
│
├── product/ # Продуктовая документация
│ ├── use-cases.md # Сценарии использования
│ ├── backlog.md # Бэклог продукта
│ └── research/ # Продуктовые исследования
│
├── tech/ # Техническая документация
│ ├── adr/ # Архитектурные решения (ADR-001, ADR-002...)
│ ├── architecture/ # Схемы, диаграммы
│ └── <scope>/ # По сервисам/областям
│
└── tasks/ # Управление задачами
├── tasklist-<scope>.md # Списки задач по скоупам
└── iterations/ # Итерации разработки
├── frontend/
├── backend/
└── ...
| Элемент | Назначение |
|---|
idea.md | Что делаем и зачем, какую проблему решаем |
vision.md | Технический стек, архитектура, ключевые решения |
workflow.md | Рабочий процесс, соглашения команды |
doc/product/ | Продуктовая документация: use cases, бэклог, исследования |
doc/tech/<scope>/ | Техническая документация по областям: frontend/, backend/, api/, infra/ |
doc/tech/adr/ | Architecture Decision Records — фиксация архитектурных решений |
doc/tasks/ | Списки задач и итерации, сгруппированные по скоупам |
Структура гибкая — это отправная точка, не догма. Скоупы и разделы создаются по мере необходимости.
ADR и архитектурные документы
ADR (Architecture Decision Record) и архитектурный документ служат разным целям:
| Документ | Вопрос | Когда читают |
|---|
| ADR | Почему приняли решение? Альтернативы, контекст, последствия | При пересмотре решения, onboarding |
| Архитектурный документ | Как концепт устроен и работает? Компоненты, потоки, контракты | При реализации, интеграции, отладке |
ADR и архитектурный документ для одного концепта — не нарушение Single Source of Truth (см. выше). Архитектурный документ ссылается на ADR для обоснования, ADR — на архитектурный документ для деталей.
Архитектурные документы описывают как сервисы (backend.md — "концепт = бэкенд"), так и кросс-сервисные концепты (auth.md, streaming.md). Тип документа один — архитектурный, различается только scope концепта.
Обкатанный шаблон рабочего процесса: workflow-template.md
Режимы работы
Новый проект (с нуля)
Документация → Задачи → Реализация
- Проработка документации — idea.md, vision.md, техническая архитектура
- Декомпозиция — составление списка задач, распил на итерации по скоупам
- Реализация — последовательное выполнение итераций
Вся архитектура и контракты фиксируются до написания кода.
Существующий проект (развитие)
Планирование → Реализация → Актуализация документации
- Планирование (архитектор) — tasklist-запись, ADR при архитектурных решениях, design brief при наличии зазора между архитектурой и реализацией (см. Артефакты итерации)
- Реализация (агент) — implementation plan → код
- Актуализация — обновление существующей документации на основе фактического результата
Документация обновляется после реализации, отражая то, что получилось на практике.
Жизненный цикл итерации
1. Планирование (архитектор)
- Создать запись итерации в tasklist
- ADR — если есть архитектурные решения
- Design brief — при развитии существующей системы (см. Артефакты итерации)
2. Реализация (агент)
- Implementation plan: верификация решений, пошаговый план. При работе с новыми или быстро меняющимися библиотеками — верифицировать актуальное API доступными средствами: inspect установленных пакетов, MCP-серверы документации, веб-поиск, специализированные скиллы. Какие источники доступны и уместны — такие и использовать.
- Код: реализация по плану, итеративное улучшение
3. Верификация (агент + архитектор)
- Верификация проводится всегда, когда есть что протестировать
- test-cases.md — опциональный отдельный документ с детальными тестовыми кейсами (чек-лист с prerequisites, слои: automated → API → E2E). Создаётся после plan.md. Для простых итераций достаточно верификации по критериям приёмки из tasklist
- Процесс прохождения:
- Агент поднимает инфраструктуру (
make targets), проходит кейсы последовательно
- Каждый кейс отмечается сразу:
- [x] + лаконичный результат, достаточный для наблюдаемости — что проверялось, что получилось, значимые нюансы. По заполненному чек-листу должно быть наглядно видно, что всё работает корректно, без повторного прохождения
- Кейс требует ручного действия или агент не может пройти — эскалация архитектору с описанием, что нужно проверить. Архитектор проверяет → агент записывает результат
- Непройденные кейсы — явно помечены с причиной
- Результаты верификации фиксируются в summary.md (общий итог + ссылка на test-cases.md, если есть)
4. Завершение
- Post-implementation summary (отклонения, решения, нюансы)
- Актуализация документации:
- Обновить затронутые существующие документы
- Появился новый концепт, не покрытый отдельным документом? (критерии — "Когда создавать новый документ") → создать
- Были архитектурные решения без ADR? → создать ADR
- Добавлены новые документы? → обновить навигацию (index.md)
- Индексация документации в записи итерации
Артефакты итерации
Итерация может порождать несколько документов. Все хранятся в директории итерации:
<type>-<NNN>-<desc>/
├── design-brief.md # Контекст реализации (опционально)
├── reference-*.md # Опорный материал (опционально)
├── plan.md # Implementation plan
├── test-cases.md # Детальные тестовые кейсы (опционально)
└── summary.md # Post-implementation summary
Design Brief
Мост между архитектурными решениями (ADR) и implementation plan. ADR фиксирует почему решили. Plan описывает как по шагам. Design brief заполняет зазор — что конкретно строить: точки интеграции с существующим кодом, контракты, конфигурация, схемы.
Когда нужен: при развитии существующей системы, когда между архитектурной документацией и тем, что агенту нужно для реализации, есть зазор. При разработке с нуля (первая фаза) архитектурные доки сами являются контекстом — design brief избыточен.
Уровень абстракции: намеренно детальнее архитектурных документов. Аудитория design brief — агент-исполнитель, которому нужны конкретные схемы, endpoints, env-переменные. Это не нарушение принципа "документируй интерфейсы, не реализацию" — разные документы служат разным аудиториям.
Scope boundaries: рекомендуемая завершающая секция — что явно НЕ входит в scope итерации. Предотвращает scope creep, документирует сознательные trade-offs, формирует кандидатов для будущих итераций.
Temporary conventions: design brief может содержать соглашения (семантика уровней, naming patterns), которые после реализации мигрируют в conventions проекта. Если design brief содержит такие соглашения — зафиксировать миграцию как задачу на этапе завершения.
Визуализация: design brief — документ, по которому можно рассказать суть фичи архитектурно и концептуально, без погружения в код. Для этого он должен содержать Mermaid-диаграммы, показывающие как новые компоненты встраиваются в существующую архитектуру (before/after, data flows, layer maps). Диаграммы идут в начале технических секций — читатель сначала видит картину, потом погружается в детали.
Reference-документы
Опорный материал из другого проекта или внешнего источника, адаптированный под текущий контекст. В шапке — ключевые отличия от текущего проекта.
Read-only: не актуализируется после реализации. При конфликте с design brief — design brief имеет приоритет.
