# Aidd Methodology

> >

- **Type:** Skill
- **Install:** `agentstack add skill-bbar0n234-learnflow-ai-aidd-methodology`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Bbar0n234](https://agentstack.voostack.com/s/bbar0n234)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [Bbar0n234](https://github.com/Bbar0n234)
- **Source:** https://github.com/Bbar0n234/learnflow-ai/tree/main/.claude/skills/aidd-methodology

## Install

```sh
agentstack add skill-bbar0n234-learnflow-ai-aidd-methodology
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 — это деталь стека, не архитектуры.

**От общего к частному.** Вводная часть документа отвечает на «что он описывает и для кого». Детали реализации, внутренние слои, инварианты — в подсекциях, не в первом абзаце. Частый антипаттерн — архитектурный документ, который во втором предложении вводной уходит в детали упаковки логики по слоям: читатель, ищущий «что делает эта система», получает «как она спрятана внутри».

**Пример — плохо:**
```python
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

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

### Визуализации в документах

В Markdown-документах: диаграммы — Mermaid, таблицы — Markdown tables. ASCII-art допустим только в интерактивном диалоге (чат), где Mermaid не рендерится.

### Языковая гигиена

Применимо, когда язык документации не совпадает с языком кода (например, документация на русском, код на английском). Правило определяет, какие иностранные термины сохраняются в тексте, а какие переводятся.

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

**Сохраняем:**
- Имена из кода: классы, функции, API, event types, константы
- Идентификаторы стандартов и категорий (имена алгоритмов, кодов, классов стандартов) — работают как имя, не как описание
- Технические термины, устоявшиеся в сообществе / литературе / коде проекта — перевод, даже точный, ухудшает связь с источниками
- Имена продуктов и инструментов
- Заголовки секций, работающие как конвенция и повторяющиеся между документами проекта

**Переводим:**
- Составные кальки через дефис, где перевод передаёт смысл без потерь
- Прилагательные с нормальным русским (или целевого языка) эквивалентом
- Общие слова, используемые не как термин

**Тест перед переводом:** передаёт ли перевод тот же смысл с той же точностью и узнаваемостью? Теряется специфичность (термин становится более общим словом), рвётся связь с источниками, падает поисковая находимость — сохраняем оригинал.

**Консистентность выбора в пределах документа.** Если для двуязычного термина выбран вариант (оригинал или перевод) — держи его последовательно в пределах одной таблицы, секции или главы. Не чередуй без явной причины.

**Если не уверен — проверь в коде.** Если термин выглядит как возможное имя из кода или тега шаблона, но без обратных кавычек или контекста — загляни в соответствующий файл (imports, definitions, текстовый поиск). Это не блокирующее требование: при отсутствии быстрого способа уточнить — сохраняй оригинал (bias на сохранение).

**Применимость к диаграммам и визуализациям.** Правила распространяются на содержимое любых визуальных представлений — Mermaid, ASCII-диаграммы (графы, таблицы, блок-схемы), Graphviz и прочие. Текст нод, label'ы связей, легенды, подписи подчиняются тем же критериям, что и основной markdown.

**Маркеры «это имя из кода»** (сохраняются даже без обратных кавычек): угловые скобки (`` — 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/               # Схемы, диаграммы
│   └── /                    # По сервисам/областям
│
└── tasks/                          # Управление задачами
    ├── tasklist-.md         # Списки задач по скоупам
    └── iterations/                 # Итерации разработки
        ├── frontend/
        ├── backend/
        └── ...
```

| Элемент | Назначение |
|---------|------------|
| `idea.md` | Что делаем и зачем, какую проблему решаем |
| `vision.md` | Технический стек, архитектура, ключевые решения |
| `workflow.md` | Рабочий процесс, соглашения команды |
| `doc/product/` | Продуктовая документация: use cases, бэклог, исследования |
| `doc/tech//` | Техническая документация по областям: `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](./references/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. Верификация** (агент + архитектор)

- Верификация проводится всегда, когда есть что протестировать
- **test-cases.md** — единый дом тестового трека, живёт в `tracks//test-cases.md` (три секции: дизайн автотестов, ручные кейсы + run-log флипов, находки ревью со severity и владельцем фикса). Авторится автономно ролью test-author из design-brief — не архитектором и не «после plan.md». Для простых итераций без тестируемой поверхности достаточно верификации по критериям приёмки из tasklist
- Процесс прохождения:
  - Агент поднимает инфраструктуру (`make` targets), проходит кейсы последовательно
  - Каждый кейс отмечается сразу: `- [x]` + лаконичный результат, достаточный для наблюдаемости — что проверялось, что получилось, значимые нюансы. По заполненному чек-листу должно быть наглядно видно, что всё работает корректно, без повторного прохождения
  - Кейс требует ручного действия или агент не может пройти — эскалация архитектору с описанием, что нужно проверить. Архитектор проверяет → агент записывает результат
  - Непройденные кейсы — явно помечены с причиной
- Результаты верификации (run-log флипов ручных кейсов) фиксируются in-place в `tracks//test-cases.md` трека; содержательные решения и обоснования — в секции `## Решения и обоснования` `tracks//summary.md`

**4. Завершение**

- Post-implementation summary (отклонения, решения, н

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Bbar0n234](https://github.com/Bbar0n234)
- **Source:** [Bbar0n234/learnflow-ai](https://github.com/Bbar0n234/learnflow-ai)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-bbar0n234-learnflow-ai-aidd-methodology
- Seller: https://agentstack.voostack.com/s/bbar0n234
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.