aidd-methodology

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, хак)
• Без неё решение нельзя воспроизвести

Уровень документа определяет уровень деталей. Архитектурный документ описывает компоненты и их ответственности. Какая конкретная технология используется — фиксируется один раз (в секции стека или при первом упоминании компонента), не при каждом упоминании. Если документ описывает, что 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)

Внутри документа — тот же принцип. Деталь (технология, решение, ограничение) фиксируется один раз в релевантной секции. В остальных местах — упоминание без повторения деталей. Повторение допустимо только когда контекст секции действительно требует эту деталь для понимания.

Типичный антипаттерн: технология указана в секции "Стек", а затем повторяется при каждом упоминании компонента по всему документу.

Структура следует за автором

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

Типовые академические шаблоны (введение → основная часть → заключение) не обязательны. Если структура неясна — лучше уточнить у пользователя.

Outline-first

При создании нового документа или существенном изменении существующего:

1. Предложи аутлайн (структуру)
2. Архитектор ревьюит, даёт обратную связь, прорабатывает открытые вопросы
3. На основе утверждённого аутлайна — пиши полный документ

Актуализация

В 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/	Списки задач и итерации, сгруппированные по скоупам

Структура гибкая — это отправная точка, не догма. Скоупы и разделы создаются по мере необходимости.

Обкатанный шаблон рабочего процесса: workflow-template.md

Режимы работы

Новый проект (с нуля)

Документация → Задачи → Реализация

1. Проработка документации — idea.md, vision.md, техническая архитектура
2. Декомпозиция — составление списка задач, распил на итерации по скоупам
3. Реализация — последовательное выполнение итераций

Вся архитектура и контракты фиксируются до написания кода.

Существующий проект (развитие)

Планирование → Реализация → Актуализация документации

1. Планирование (архитектор) — tasklist-запись, ADR при архитектурных решениях, design brief при наличии зазора между архитектурой и реализацией (см. Артефакты итерации)
2. Реализация (агент) — implementation plan → код
3. Актуализация — обновление существующей документации на основе фактического результата

Документация обновляется после реализации, отражая то, что получилось на практике.

Жизненный цикл итерации

1. Планирование (архитектор)

• Создать запись итерации в tasklist
• ADR — если есть архитектурные решения
• Design brief — при развитии существующей системы (см. Артефакты итерации)

2. Реализация (агент)

• Implementation plan: верификация решений, пошаговый план. При работе с новыми или быстро меняющимися библиотеками — верифицировать актуальное API доступными средствами: inspect установленных пакетов, MCP-серверы документации, веб-поиск, специализированные скиллы. Какие источники доступны и уместны — такие и использовать.
• Код: реализация по плану, итеративное улучшение

3. Завершение

• Post-implementation summary (отклонения, решения, нюансы)
• Актуализация связанной документации
• Индексация документации в записи итерации

Артефакты итерации

Итерация может порождать несколько документов. Все хранятся в директории итерации:

<type>-<NNN>-<desc>/
├── design-brief.md       # Контекст реализации (опционально)
├── reference-*.md         # Опорный материал (опционально)
├── plan.md                # Implementation plan
└── 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 содержит такие соглашения — зафиксировать миграцию как задачу на этапе завершения.

Reference-документы

Опорный материал из другого проекта или внешнего источника, адаптированный под текущий контекст. В шапке — ключевые отличия от текущего проекта.

Read-only: не актуализируется после реализации. При конфликте с design brief — design brief имеет приоритет.