Aidd methodology

Skill Bbar0n234/llm-engineer-skills/skills/aidd-methodology

Battle-tested Claude Code skills for LLM engineers — structured output patterns, prompt engineering principles, and more

Install

npx -y skills add Bbar0n234/llm-engineer-skills --skill aidd-methodology

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

AI-Driven Development — методология и принципы написания документации для проектов с LLM-агентом. Используй когда: AIDD, AI-driven, планирование проекта, idea.md, vision.md, workflow.md, архитектура, документация, написание документации, обновление документации, doc, md-файл, Context First, итерация, tasklist, ADR.

SKILL.md

18.1 KB, ~4.3k tokens by cl100k_base, as published. Nobody here has run it

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

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

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

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

В 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

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

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

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

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

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

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

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

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

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

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

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 имеет приоритет.