LLM — не один большой «мозг», а команда ролей. Как собрать AI-workflow в Claude Code и уйти от вайб-коддинга

Большие языковые модели часто используют как один большой “мозг”: написал промпт, нажал Enter – и сразу запускаешь сгенерированный код. Быстро, удобно и наполненно магией. Такой подход можно называть вайб-коддингом.

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

В этой статье я покажу, как относиться к LLM не как к “герою-одиночке”, а как к команде ролей (аналитик, ресерчер, архитектор, разработчик, ревьюер, QA, техписатель, валидатор) и собрать полноценный AI-Driven Development (AIDD) процесс с понятными договорами и quality-гейтами на каждом шаге.

Это практический how-to: от минимальной версии до более строгого процесса с ролями, гейтами и интеграцией с CI. Все примеры – на базе Claude Code, но принципы подхода можно перенести и на другие инструменты (Cursor, Copilot, локальные агенты и т.п.).

Для кого статья

Статья будет полезна, если вы:

• разработчик или тимлид;

• уже пользуетесь LLM в работе (хотя бы “чатик в браузере” или IDE-плагин);

• устали от режима “/dev сделай всё” и хотите воспроизводимый AI-workflow для команды;

• готовы немного покрутить репозиторий и процесс, а не только «подкрутить промпт».

Как читать эту статью

• Хотите идею с минимально описанной реализацией -> читайте разделы 1-5.

• Хотите встроить AIDD в свой процесс разработки с Claude Code -> добавьте разделы 6-9.

• Хотите только чек лист -> не пропускайте раздел 10 (чек-лист внедрения).

• Итоги и идеи -> раздел 11

Итак, начнем:

1. Вайб-коддинг vs инженерная AI-разработка

Под “чистым вайб-коддингом” я буду понимать экстремальный режим работы с ИИ:

1. Разработчик описывает желаемое поведение на естественном языке.

2. ИИ генерирует код.

3. Код почти сразу запускается – без PRD, архитектурного дизайна, декомпозиции и нормальных тестов.

Плюсы:

• очень низкий порог входа;

• супербыстрый путь от идеи до первого прототипа;

• классный режим “посмотреть, на что вообще способен ассистент”.

Минусы, которые в долгую перевешивают все плюсы скорости и простоты:

1. Структура и качество. Модель не знает ваших архитектурных соглашений, паттернов и инфраструктурных ограничений. Код получается:

   1. избыточным и непоследовательным;

   2. с техдолгом по умолчанию;

   3. плохо масштабируемым.

2. Ошибки и уязвимости. Размытая постановка заставляет модель додумывать детали:

   1. небезопасные решения;

   2. отсутствие валидации;

   3. возможные секреты в коде;

   4. странные зависимости и/или решения.

3. Масштабирование и командная работа. Хаотичный AI-код:

   1. усложняет ревью и интеграцию;

   2. без нормального покрытия тестами увеличивает стоимость регресса и страх трогать любой файл.

Вывод: вайб-коддинг годится для одноразовых прототипов и “пощупать идею”.
Для продукта в свою очередь нужен инженерный процесс, куда AI встроен в привычный SDLC:

соглашения -> спецификация -> архитектура -> задачи -> реализация -> ревью и тесты -> финальное QA -> документация.

2. AI-Driven Development: LLM как команда ролей

Под AI-Driven Development (AIDD) я буду понимать не волшебную методологию, а вполне приземленный процесс:

LLM – не оракул “сделай всё”, а команда специалистов (которая помогает на каждом шаге привычного SDLC), у каждого – своя зона ответственности и выходные артефакты.

Типичный набор ролей:

• Analyst – собирает требования, ведет Q&A, формирует PRD.

• Researcher – исследует кодовую базу и внешние ограничения.

• Architect / Planner – проектирует архитектуру, пишет ADR, составляет план.

• Implementer (Dev) – пишет код маленькими шагами по задачам.

• Reviewer – делает code review, отлавливает архитектурные и стилевые проблемы.

• QA – думает, как сломать то что сделали, формирует тест-план и отчет.

• Tech Writer – приводит документацию в порядок.

• Validator – следит за прохождением quality-гейтов по тикету/релизу.

В Claude Code эти роли удобно оформлять как subagents в .claude/agents/*.md: у каждого свой промпт, список доступных tools и ожидаемые артефакты.

3. Minimal AIDD: что можно собрать за вечер

Чтобы не пытаться сделать полноценный процесс разработки с одного наскока, начнем с минимальной версии – без hooks, CI и кучи агентов.

3.1. Что входит в Minimal AIDD

Минимальный набор:

• CLAUDE.md — один главный проектный файл, где зафиксированы базовые договорённости с LLM.

• Один шаблон PRD и один шаблон плана.

• docs/tasklist/<ticket>.md как чек-лист задач по фиче.

Этого уже достаточно, чтобы перестать делать “/dev сделай всё” и начать работать через роли и артефакты.

На более строгом уровне (Full AIDD) эти договорённости можно разделить: вынести общие правила в conventions.md, а CLAUDE.md оставить как инструкцию именно для Claude Code.

3.2. Minimal AIDD: пошаговый чек-лист

Теперь используем состав из пункта 3.1 как чек-лист внедрения.
Цель — перестать вайб-кодить и ввести базовый AIDD без сложной автоматизации, чтобы почувствовать, как можно вписать AI в ваш процесс разработки.

• [ ] Создать CLAUDE.md.
  В минимальной версии это ваш единственный «договор» с LLM. Сложите сюда всё:

  • какие языки и форматтеры вы используете;

  • какие есть архитектурные слои;

  • как логируете ошибки;

  • какие требования к тестам;

  • как работать с секретами;

  • как выбирать текущий тикет;

  • что надо посмотреть перед правками (PRD/план/tasklist);

  • что делать после (diff, текст коммита, обновление tasklist).

• [ ] Добавить шаблоны PRD/плана/tasklist.
  Простые markdown-шаблоны, которые будете копировать под каждую фичу: пара заголовков, блоки “Контекст”, “Цели”, “Сценарии”, “Метрики”, “Задачи”.

• [ ] Завести docs/prd/<ticket>.prd.md и docs/tasklist/<ticket>.md хотя бы для одной фичи.
  PRD — договор о том, что делаем и зачем. Tasklist — список задач, по которым можно работать маленькими шагами.

• [ ] Подружить LLM с этими файлами.
  Просить модель не “написать эндпоинт”, а:

  • “собери PRD по этим заметкам”;

  • “предложи tasklist по этому плану”;

  • “дополни tests для этого изменения”.

• [ ] Прогнать одну фичу по цепочке Minimal AIDD.
  PRD → план → tasklist → реализация маленькими шагами → ревью.
  После — честно посмотреть, где модель помогла, а где мешала, и подправить CLAUDE.md.

Когда такой уровень начнет работать, Full AIDD будет уже не “еще одна громоздкая методология”, а естественное развитие вашего мини-процесса.

4. Full AIDD: agreements, артефакты, агенты, команды

А теперь – полная версия, с которой можно построить полноценный процесс.

4.1. Agreements: конституция процесса

Agreements – это в сути своей договоры между вами и LLM:

• как писать код;

• в каком порядке работать;

• когда можно переходить на следующий шаг.

Для полноценного AIDD можно распределить “ответственность” на такой набор файлов:

• conventions.md – общие конвенции проекта для людей:

  • кодстайл и форматтеры;

  • архитектурные принципы, слои;

  • правила ошибок и логирования;

  • требования к тестам;

  • правила работы с секретами;

  • allowlist/banlist зависимостей.

• CLAUDE.md – инструкция для Claude Code:

  • как использовать conventions;

  • как работать с тикетами;

  • что делать до/после правок;

  • как относиться к PRD/планам/tasklist.

• workflow.md – человеческое описание процесса:

  • шаги pipeline;

  • роли;

  • quality‑гейты;

  • когда считается “готово”.

• .claude/agents/* – роли (subagents).

• .claude/commands/* – слэш‑команды.

• .claude/settings.json – hooks и общие настройки.

conventions.md
workflow.md
CLAUDE.md

.claude/
  agents/
    analyst.md
    researcher.md
    planner.md
    implementer.md
    reviewer.md
    qa.md
    validator.md
    tech-writer.md
    task-planner.md
  commands/
    idea.md
    researcher.md
    plan.md
    review-prd.md
    tasks.md
    implement.md
    review.md
    qa.md
    validate.md
    feature-development.md
    docs-update.md
  settings.json
  hooks/
    gate-workflow.sh
    after-edit.sh

docs/
  .active_ticket
  prd/
    T-104.prd.md
  plan/
    T-104.md
  tasklist/
    T-104.md
  research/
    T-104.md

reports/
  qa/
    T-104.md

CHANGELOG.md

4.2. Артефакты тикета – контекст вместо “памяти чата”

Чтобы перестать полагаться на “память чата” и сделать агента более гибким, для каждой фичи/тикета заводим мини-набор файлов:

docs/prd/T-104.prd.md       # Product Requirements Document
docs/plan/T-104.md          # архитектура и план
docs/tasklist/T-104.md      # чеклист задач
docs/research/T-104.md      # отчет по кодовой базе
reports/qa/T-104.md         # отчет QA-агента
docs/releases/R-12.3.md     # состав релиза, связанные тикеты и заметки

Именно эти файлы читает Claude Code, когда вы запускаете /idea, /researcher, /plan, /tasks, /implement, /review, /qa по этому тикету или релизу.

Контекст работы – это структурированная память проекта, а не “последние 20 сообщений в чате”.

4.3. Роли как subagents

Роли оформляем в .claude/agents/*.md:

.claude/agents/
  analyst.md
  researcher.md
  planner.md
  implementer.md
  prd-reviewer.md
  reviewer.md
  qa.md
  validator.md
  tech-writer.md
  task-planner.md

У каждого файла:

• YAML-фронтматтер (name, description, tools, model, permissionMode),

• дальше – по сути должностная инструкция: входные артефакты, ожидаемый выход, ограничения.

4.4. Команды: кто делает vs что запускаем

Важно различать:

• Агент (subagent) – кто делает (роль / персона). Примеры: analyst, planner, qa, reviewer, task-planner.

• Команда (/slash-команда) – что и когда делаем. Примеры: /idea, /plan, /qa, /validate, /feature-development, /docs-update.

Команды описываются в .claude/commands/*.md и превращаются в слэш-команды в интерфейсе Claude Code.

Примеры связки:

• /idea -> агент analyst;

• /plan -> planner;

• /tasks -> task-planner;

• /qa -> qa;

• /validate -> validator;

• /docs-update -> tech-writer.

Детальные примеры .md для агентов и команд будут описаны прямо в пошаговом примере (раздел 7).

5. Quality-gates: где стоят стоп-сигналы

Чтобы AIDD не превратился в тот же вайб-коддинг, только с красивыми файлами, нужны стоп-сигналы – quality-гейты между этапами.

Примерный набор:

Каждый гейт можно реализовать на трех уровнях:

1. Ручной – статус в Markdown + чек-лист.

   1. Пример: Status: PRD_READY в docs/prd/T-104.prd.md.

2. AI-уровень – валидатор /validate, который:

   1. смотрит PRD, план, tasklist, QA;

   2. пишет, что уже ок, а что не дотянуто.

3. Жесткий – hooks в .claude/settings.json, которые не дают нарушить договор:

   1. блокируют Edit/Write, если не выполнены гейты по активному тикету. AGREEMENTS_ON относится ко всему проекту, его удобно фиксировать разово (например, чек-лист в docs/process-status.md).

6. Этап 0. Онбординг AI-команды в проект

С этого раздела начинается блок, где мы подробно разберем весь процесс по шагам.
Этап 0 – это то, что вы делаете один раз на проект, а дальше только тюните под свои конвенции, архитектуру и развитие процесса. Вся остальная работа по тикетам уже опирается на эти договоренности и не требует каждый раз заново придумывать правила.

Прежде чем просить LLM писать код, с ней надо сделать то же, что вы делаете с новым разработчиком, а именно онбординг.

6.1. Conventions и CLAUDE.md

В корне репозитория:

• conventions.md – все, что обычно живет “в головах” и в устных договоренностях.

• CLAUDE.md – главный системный промпт для Claude Code.

Пример фрагмента CLAUDE.md:

• Всегда опирайся на conventions.md.

• Перед любыми правками кода:

  1. Найди активный тикет в docs/.active_ticket.

  2. Посмотри PRD, план и tasklist по нему.

  3. Сформулируй план изменений и дождись моего “ОК”.

• После правок:

  • покажи diff;

  • предложи текст коммита с тикетом;

  • обнови чекбоксы в docs/tasklist/<ticket>.md;

  • остановись и жди ревью.

6.2. Workflow и базовые команды

Рабочий процесс фиксируем в workflow.md, например:

idea -> research -> plan -> PRD review -> tasks -> implement -> review -> QA -> docs

Под этот флоу описываем слэш-команд (примеры md файлов команд будут описаны ниже):

.claude/commands/
  idea.md               # /idea
  researcher.md         # /researcher
  plan.md               # /plan
  review-prd.md         # /review-prd
  tasks.md              # /tasks
  implement.md          # /implement
  review.md             # /review
  qa.md                 # /qa
  validate.md           # /validate
  feature-development.md# /feature-development (оркестратор)
  docs-update.md        # /docs-update

Quality-gate: AGREEMENTS_ON

Минимум:

• есть conventions.md, workflow.md, CLAUDE.md;

• базовые агенты и команды лежат в .claude/agents и .claude/commands;

• в docs/process-status.md отмечено, что эти артефакты заведены.

7. Пошаговый процесс по тикету (пример T-104)

Теперь давайте посмотрим весь workflow на примере одной конкретной задачи, чтобы не оставаться в абстракции и увидеть, как шаги работают вместе.

Возьмем условный тикет:

T-104: GET /invoices/{id} в сервисе billing-api

По нему пройдем весь путь:
PRD -> архитектура -> задачи -> реализация -> ревью -> QA -> доки.

7.1. Шаг 1. Идея и PRD

Вместо “/dev сделай эндпоинт” – сначала PRD.

1. Вы набрасываете идею: “Нужен эндпоинт GET /invoices/{id} для поддержки и бухгалтерии”.

2. Вызываете:

   /idea T-104 "GET /invoices/{id} в сервисе billing-api"
   

3. Команда /idea использует агента analyst, который:

   1. создает docs/prd/T-104.prd.md по шаблону,

   2. задает вопросы,

   3. помогает докрутить требования.

---
name: analyst
description: "Собирает исходную идею, уточняет требования и оформляет PRD по тикету."
tools: Read, Glob, Grep, Write
model: inherit
---

## Роль

Ты - продуктовый аналитик. Твоя задача - превратить сырую идею
и артефакты из репозитория в понятный, структурированный PRD.

## Входные артефакты
- docs/.active_ticket - текущий тикет.
- docs/prd/<ticket>.prd.md - черновик PRD (если есть).
- docs/research/<ticket>.md - отчет ресерча (если есть).

## Выход
- Обновленный docs/prd/<ticket>.prd.md:
  - цель и контекст,
  - user stories и сценарии,
  - метрики и критерии успеха,
  - ограничения и риски,
  - открытые вопросы.

Правила:

- Не придумывай бизнес-требования, если они не следуют из контекста.
- Если информации не хватает - явно выпиши вопросы в "Открытых вопросах".

---
description: "Инициализация фичи: зафиксировать тикет и собрать черновик PRD"
argument-hint: "[ticket-id] [short-title]"
allowed-tools: Read, Write, Glob, Grep
model: inherit
---

Используй subagent `analyst`.

Ты запускаешь процесс работы над фичей с идентификатором `$1`.

Шаги:
1. Обнови `docs/.active_ticket` значением `$1`.
2. Если файла `docs/prd/$1.prd.md` нет - создай его из шаблона `@docs/prd.template.md`.
3. Перенеси `$ARGUMENTS` в раздел "Контекст / идея".
4. Заведи разделы: цели, user stories, сценарии, метрики, ограничения, риски, открытые вопросы.
5. Заполни то, что можно вывести из контекста репозитория.
6. Если данных мало - сформулируй вопросы к команде, проставь `Status: DRAFT`.
7. Если PRD выглядит цельным и без блокирующих вопросов - проставь `Status: PRD_READY`.

# $TICKET: $TITLE

Status: DRAFT

## Контекст / идея

...

## Цели

...

## User stories

...

## Основные сценарии

...

## Успех / метрики

...

## Ограничения и допущения

...

## Риски

...

## Открытые вопросы

...

Gate PRD_READY:

• PRD существует;

• заполнены ключевые разделы;

• нет блокирующих вопросов;

• Status: PRD_READY.

7.2. Шаг 2. Архитектура и ресерч

После закрытия всех открытых вопросов, можно либо самому на них ответить, либо вызвать команду ресерч:

/researcher T-104 (сюда можно добавить некий дополнительный пейлоад чтобы модель лучше понимала где и что надо искать)

Агент researcher:

• смотрит кодовую базу, конфиги, существующие эндпоинты;

• описывает связанные модули, сущности, риски;

• пишет docs/research/T-104.md.

---
name: researcher
description: "Исследует кодовую базу и окружающий контекст по тикету."
tools: Read, Glob, Grep
model: inherit
---

## Роль

Ты - ресерчер. Твоя задача - понять, как текущий код и инфраструктура
влияют на реализацию тикета, и собрать контекст в один документ.

## Вход

- docs/.active_ticket
- docs/prd/<ticket>.prd.md (если есть)
- структура src/, конфиги, docs/

## Выход

- docs/research/<ticket>.md:
  - связанные модули/сервисы,
  - текущие эндпоинты и контракты,
  - используемые паттерны,
  - ограничения и риски,
  - открытые технические вопросы.

---
description: "Собрать технический контекст и оформить research-документ по тикету"
argument-hint: "[ticket-id]"
allowed-tools: Read, Write, Glob, Grep
model: inherit
---

Используй subagent `researcher`.

1. Прочитай `docs/prd/$1.prd.md`, если файл существует.
2. Просканируй ключевые директории проекта (src, docs, конфиги) на предмет сущностей и модулей, связанных с тикетом.
3. Зафиксируй в `docs/research/$1.md`:
   - существующие эндпоинты и контракты,
   - слои и зависимости,
   - используемые паттерны,
   - ограничения и риски,
   - открытые технические вопросы.
4. Не меняй код, только собирай информацию.

После закрытия всех открытых вопросов по фиче и понимания куда мы можем встроиться необходимо подготовить архитектуру и план:

/plan T-104

Агент planner:

• читает PRD и ресерч;

• проектирует решение;

• создает docs/plan/T-104.md (компоненты, интерфейсы, потоки данных, NFR, риски);

• при необходимости – docs/adr/T-104.md.

---
name: planner
description: "Проектирует архитектуру решения и план реализации по тикету."
tools: Read, Glob, Grep, Write
model: inherit
---

## Роль

Ты - архитектор/планировщик. На основе PRD и ресерча ты
предлагаешь архитектуру и план изменений.

## Вход

- docs/.active_ticket
- docs/prd/<ticket>.prd.md
- docs/research/<ticket>.md (если есть)
- conventions.md (архитектурные правила)

## Выход

- docs/plan/<ticket>.md:
  - компоненты и модули,
  - целевые интерфейсы и контракты,
  - потоки данных,
  - NFR,
  - риски и альтернативы.
- опционально docs/adr/<ticket>.md, если есть значимые архитектурные развилки.

Требования:

- Соблюдай слои и запреты из conventions.md.
- Явно описывай принятые trade-off'ы.

---
description: "Сформировать архитектуру и план реализации по тикету"
argument-hint: "[ticket-id]"
allowed-tools: Read, Write, Glob, Grep
model: inherit
---

Используй subagent `planner`.

1. Прочитай:
   - `docs/prd/$1.prd.md`,
   - `docs/research/$1.md` (если есть),
   - `conventions.md`.
2. Создай или обнови `docs/plan/$1.md` со структурой:
   - Components
   - API contract
   - Data flows
   - NFR
   - Risks
   - Open questions (если есть).
3. Если есть архитектурные развилки - создай `docs/adr/$1.md` с вариантами и принятым решением.
4. Если план согласован - установи в `docs/plan/$1.md` строку `Status: PLAN_APPROVED`.

Gate PLAN_APPROVED:

• есть план (и при необходимости ADR);

• описаны компоненты, контракты, NFR;

• статус: Status: PLAN_APPROVED.

7.3. Шаг 3. Tasklist

Теперь когда у нас есть план необходимо превратить его в набор маленьких задач с понятными критериями готовности.

/tasks T-104

Команда /tasks использует агента task-planner и создает docs/tasklist/T-104.md.

---
name: task-planner
description: "Разбивает архитектурный план на мелкие задачи с понятными критериями готовности."
tools: Read, Write, Glob, Grep
model: inherit
---

## Роль

Ты - планировщик задач. На основе PRD и плана по тикету ты формируешь
docs/tasklist/<ticket>.md с небольшими, проверяемыми задачами.

## Вход

- docs/.active_ticket
- docs/prd/<ticket>.prd.md
- docs/plan/<ticket>.md

## Выход

- docs/tasklist/<ticket>.md:
  - список задач с чекбоксами,
  - необязательные подзадачи,
  - acceptance-критерии для каждой задачи,
  - статус файла (DRAFT, TASKLIST_READY).

Правила:

- Задачи должны быть максимально независимыми.
- Acceptance-критерий должен быть проверяемым (не "улучшить", а "есть тест X, проходит сценарий Y").

---
description: "Разбить план по тикету на список небольших задач (tasklist)"
argument-hint: "[ticket-id]"
allowed-tools: Read, Write, Glob, Grep
model: inherit
---

Используй subagent `task-planner`.

1. Прочитай:
   - `docs/prd/$1.prd.md`,
   - `docs/plan/$1.md`.
2. Сформируй `docs/tasklist/$1.md`:
   - заголовок и краткий контекст,
   - список задач с `- [ ]`,
   - для каждой задачи - 1-2 acceptance-критерия.
3. Если tasklist выглядит цельным и покрывает план - установи `Status: TASKLIST_READY`.

Пример самого tasklist:

# T-104: GET /invoices/{id}

Status: TASKLIST_READY

Контекст: PRD §3.2; план docs/plan/T-104.md

- [ ] OpenAPI: docs/api/T-104.yaml
  - Описание эндпоинта, коды ошибок, примеры.
- [ ] Controller: InvoiceController.getById
  - Обработка ошибок, маппинг DTO.
- [ ] Service: InvoiceService.findByIdWithPermissions
  - Проверка прав + доступ к репозиторию.
- [ ] IT-тесты
  - Позитивные и негативные сценарии.

Gate TASKLIST_READY:

• задачи достаточно мелкие;

• у каждой есть acceptance-критерии;

• Status: TASKLIST_READY.

7.4. Шаг 4. Итеративная реализация

Теперь можно приступать к самой реализации, малыми шагами, а не “сделай всё сразу”.

/implement T-104

Агент implementer:

1. Находит первую задачу с - [ ] в docs/tasklist/T-104.md.

2. Формулирует план изменений (файлы, сущности, тесты).

3. Ждет вашего явного подтверждения. (опционально, можно полностью автоматизировать)

4. После “ОК”:

   1. вносит минимально необходимые изменения в код;

   2. добавляет/обновляет тесты (здесь можно поменять пункты местами и пойти по TDD, вначале тесты, потом реализация);

   3. обновляет docs/tasklist/T-104.md (- [x] у выполненного пункта);

   4. показывает diff и кратко объясняет, что сделано.

5. Останавливается. К следующей задаче не переходит без команды.

---
name: implementer
description: "Реализует задачи из tasklist небольшими, согласованными шагами."
tools: Read, Write, Glob, Grep, Bash
model: inherit
---

## Роль

Ты - разработчик по тикету. Работаешь маленькими шагами по tasklist.

## Вход

- docs/.active_ticket
- docs/tasklist/<ticket>.md
- conventions.md
- кодовая база

## Выход

- Изменения в коде согласно очередной задаче.
- Обновленный docs/tasklist/<ticket>.md (чекбокс задачи отмечен как выполненный).

Правила:

- Перед изменениями всегда формируй план (что меняем, какие тесты).
- Без явного подтверждения пользователя не вноси правки.
- Соблюдай conventions.md и существующую архитектуру.
- Всегда добавляй или обновляй тесты для реализуемой задачи.
- После изменений показывай diff и краткое описание того, что сделал.

---
description: "Реализовать следующую задачу из tasklist по согласованному плану"
argument-hint: "[ticket-id]"
allowed-tools: Read, Write, Glob, Grep, Bash
model: inherit
---

Используй subagent `implementer`.

1. Прочитай `docs/tasklist/$1.md` и найди первую задачу с `- [ ]`.
2. Сформулируй план изменений:
   - какие файлы будут затронуты,
   - какие сущности/методы добавятся или изменятся,
   - какие тесты нужно добавить/обновить.
3. Остановись и спроси явное подтверждение пользователя.
4. После подтверждения:
   - внеси минимально необходимые изменения в код,
   - добавь/обнови тесты,
   - пометь выполненные пункты в `docs/tasklist/$1.md` как `- [x]`.
5. Покажи diff и кратко опиши, что было сделано и почему.
6. Не переходи к следующей задаче, пока пользователь явно не попросит продолжить.

Gate IMPLEMENT_STEP_OK:

• по текущей задаче:

  • код написан;

  • тесты обновлены;

  • локальные проверки зелёные;

  • tasklist обновлен.

7.5. Шаг 5. Ревью

Ревью можно делать как после каждой итерации имплементации, так и одним большим прогоном в конце.

/review T-104

Агент reviewer:

• смотрит PRD, план, tasklist и diff по тикету;

• проверяет соответствие конвенциям и ADR;

• подсвечивает потенциальные баги и странные решения;

• формирует замечания (blocking / important / etc);

• может добавить follow-up задачи в docs/tasklist/T-104.md.

---
name: reviewer
description: "Проводит code review изменений по тикету с учетом PRD, плана и конвенций."
tools: Read, Glob, Grep
model: inherit
---

## Роль

Ты - ревьюер по тикету. Твоя задача - проверить изменения на соответствие
PRD, плану, conventions.md и здравому смыслу.

## Вход

- docs/prd/<ticket>.prd.md
- docs/plan/<ticket>.md
- docs/tasklist/<ticket>.md
- conventions.md
- diff по изменениям, относящимся к тикету

## Выход

- Список замечаний:
  - blocking,
  - important,
  - etc.
- Предложения по улучшению.

Правила:

- Не придирайся к стилю, если он не противоречит conventions.md.
- Сосредоточься на архитектуре, инвариантах, безопасности и читаемости.

---
description: "Сделать review изменений по тикету"
argument-hint: "[ticket-id]"
allowed-tools: Read, Glob, Grep
model: inherit
---

Используй subagent `reviewer`.

1. Прочитай:
   - `docs/prd/$1.prd.md`,
   - `docs/plan/$1.md`,
   - `docs/tasklist/$1.md`,
   - `conventions.md`.
2. Проанализируй diff по изменениям, связанным с тикетом `$1`.
3. Сформируй review:
   - blocking-замечания (что нужно исправить до мержа),
   - important (желательно поправить),
   - etc (косметика).
4. Если видишь незакрытые сценарии или долги - предложи добавить задачи в `docs/tasklist/$1.md` (но сам файл не правь без отдельной команды).

Gate REVIEW_OK:

• CI зелёный;

• acceptance-критерии задач выполнены;

• нет blocking-замечаний.

7.6. Шаг 6. Финальное QA

Когда набор задач по фиче/релизу закрыт, нужен отдельный QA-взгляд.

/qa T-104

Агент qa:

• собирает список сценариев;

• делит их на автотесты / ручные проверки;

• оформляет отчет в reports/qa/<id>.md;

• дает рекомендацию: выпускать / с оговорками / не выпускать.

---
name: qa
description: "Формирует QA-план и отчет по тикету или релизу."
tools: Read, Glob, Grep, Write
model: inherit
---

## Роль

Ты - QA-инженер. Твоя задача - на основе артефактов тикета или релиза
сформировать сценарии тестирования и зафиксировать результат.

## Вход

- docs/releases/<release>.md (для релиза)
- docs/prd/<ticket>.prd.md
- docs/plan/<ticket>.md
- docs/tasklist/<ticket>.md
- reports/qa/* (предыдущие отчеты, если есть)

## Выход

- reports/qa/<ticket-or-release>.md:
  - позитивные сценарии,
  - негативные и edge-case'ы,
  - что покрыто автотестами,
  - что нужно проверить вручную,
  - вывод по готовности (выпускать / с оговорками / не выпускать).

---
description: "Подготовить QA-план и отчет по тикету или релизу"
argument-hint: "[ticket]"
allowed-tools: Read, Write, Glob, Grep
model: inherit
---

Используй subagent `qa`.

1. Если идентификатор начинается с `R-` - считаем, что это релиз:
   - прочитай `docs/releases/$1.md` и вытащи список тикетов.
2. Для тикета или каждого тикета релиза прочитай:
   - `docs/prd/<ticket>.prd.md`,
   - `docs/plan/<ticket>.md`,
   - `docs/tasklist/<ticket>.md`.
3. Сформируй `reports/qa/$1.md`:
   - позитивные сценарии,
   - негативные и edge-case'ы,
   - разделение на автотесты и ручные проверки,
   - зону риска,
   - финальный вердикт (выпускать / с оговорками / не выпускать).

Gate RELEASE_READY:

• по задачам релиза выполнены PRD_READY, PLAN_APPROVED, TASKLIST_READY, REVIEW_OK;

• QA-чек-лист отработан;

• критических багов нет или они явно приняты.

7.7. Шаг 7. Документация

Финальный шаг – синхронизация кода и знаний. На данном этапе после всех реализаций чтобы не плодить множество файлов мы можем сделать сумаризацию по всем текущим артефактам:

/docs-update T-104

Агент tech-writer:

• читает PRD, план, ресерч, tasklist, QA-отчеты, ключевые PR;

• помогает обновить или создать сумаризированые документы:

  • <ticket>-summary.md;

  • CHANGELOG.md.

---
name: tech-writer
description: "Обновляет архитектурную и эксплуатационную документацию по результатам работы над тикетом."
tools: Read, Write, Glob, Grep
model: inherit
---

## Роль

Ты - техписатель команды.

## Вход

- docs/prd/<ticket>.prd.md
- docs/plan/<ticket>.md
- docs/tasklist/<ticket>.md
- reports/qa/<ticket>.md (если есть)
- ключевые изменения в коде (через Read/Glob/Grep)
- текущие CHANGELOG.md

## Выход

- Обновленные:
  - <ticket>-summary.md
  - CHANGELOG.md.

Правила:

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

---
description: "Обновить документацию по результатам работы над тикетом"
argument-hint: "[ticket-id]"
allowed-tools: Read, Write, Glob, Grep
model: inherit
---

Используй subagent `tech-writer`.

1. Прочитай артефакты по тикету `$1`:
   - `docs/prd/$1.prd.md`,
   - `docs/plan/$1.md`,
   - `docs/tasklist/$1.md`,
   - `reports/qa/$1.md` (если есть).
2. На основе этих артефактов и diff'a в коде:
   - создай <ticket>-summary.md (краткое сделанных работ и принятых решений по тикету),
   - добавь запись в `CHANGELOG.md` (краткое описание изменений).
3. Покажи diff по документации пользователю.

Gate DOCS_UPDATED:

• документация соответствует коду;

• по ней можно онбордить нового человека и разбираться в инцидентах.

8. Валидатор и оркестратор

Опциональный этап.

8.1. Валидатор

Чтобы не гадать “а что у нас по гейтам?”, заводим отдельную команду и агента валидатор, которых можно вызвать на любом шаге флоу и собрать галлюцинации или неточности при работе любого из шагов.

/validate T-104

Команда:

• ищет связанные артефакты (PRD, план, tasklist, QA);

• оценивает гейты: PRD_READY, PLAN_APPROVED, TASKLIST_READY, IMPLEMENT_STEP_OK, REVIEW_OK, RELEASE_READY, DOCS_UPDATED;

• возвращает сводку: что OK, что missing, что сыро.

---
description: "Проверить, какие quality-gates пройдены по тикету или релизу"
argument-hint: "[ticket-or-release-id]"
allowed-tools: Read, Glob, Grep
model: inherit
---

Используй subagent `validator`.

1. Если `$1` начинается с `R-` - считаем, что это релиз:
   - прочитай `docs/releases/$1.md` и вытащи связанные тикеты.
2. Для тикета или каждого тикета релиза найди артефакты:
   - PRD: `docs/prd/<ticket>.prd.md`,
   - план: `docs/plan/<ticket>.md`,
   - tasklist: `docs/tasklist/<ticket>.md`,
   - QA: `reports/qa/<ticket>.*` (если есть).
3. По этим файлам оцени гейты:
   - PRD_READY,
   - PLAN_APPROVED,
   - TASKLIST_READY,
   - IMPLEMENT_STEP_OK (по текущим задачам),
   - REVIEW_OK,
   - RELEASE_READY (для релиза),
   - DOCS_UPDATED.
4. Верни сводку в текстовом виде:
   - статус каждого гейта,
   - что нужно доделать, если гейт не пройден.
5. Ничего не меняй в файлах - только анализируй.

---
name: validator
description: "Проверяет, выполнены ли условия для перехода к следующему этапу по тикету или релизу."
tools: Read, Glob, Grep
model: inherit
---

## Роль

Ты - валидатор процесса.

## Вход

- docs/prd/*.prd.md
- docs/plan/*.md
- docs/tasklist/*.md
- docs/releases/*.md
- reports/qa/*.md
- docs/process-status.md (для AGREEMENTS_ON)

## Выход

- Краткий отчет о том, какие quality-gates пройдены и что мешает пройти остальные.

Правила:

- Не изменяй артефакты, только читай.
- Будь консервативен: если не уверен, что гейт пройден, помечай его как требующий внимания.

8.2. Оркестратор

После того как отдельные команды и агенты будут “обкатаны”, следующий логичный шаг это создать одну команду что правит всеми, которая знает про весь pipeline и может относительно самостоятельно пройти весь флоу.

/feature-development T-104 "GET /invoices/{id} в billing-api"

Оркестратор:

• вызывает /validate T-104;

• показывает, какие гейты пройдены;

• предлагает следующие шаги:

  • нет PRD -> /idea, /review-prd;

  • нет плана -> /researcher, /plan;

  • нет tasklist -> /tasks;

  • реализация в процессе -> /implement, /review;

  • нет QA -> /qa;

  • нет обновленных док -> подключить tech-writer.

Фактически, если хочется “кнопку сделать хорошо”, вы можете максимально автоматизировать и запускать процесс одной командой. Дальше оркестратор будет вести вас по шагам, не давая перескакивать важные этапы.

---
description: "End-to-end AI-driven feature workflow: PRD -> план -> задачи -> реализация -> ревью -> QA -> docs"
argument-hint: "[ticket-id] [short-title]"
allowed-tools: Read, Glob, SlashCommand
model: inherit
---

Ты - оркестратор фичи `$1` ("$ARGUMENTS").

1. Вызови `/validate $1` и кратко опиши статус гейтов.
2. Если нет PRD_READY - предложи запустить `/idea $1` и `/review-prd $1`.
3. Если нет PLAN_APPROVED - предложи `/researcher $1` и `/plan $1`.
4. Если нет TASKLIST_READY - предложи `/tasks $1`.
5. Если реализация не завершена - напомни про `/implement $1` и `/review $1`.
6. Если релиз еще не RELEASE_READY - напомни про `/qa $1` или `/qa <release-id>`.
7. Если DOCS_UPDATED не достигнут - предложи запустить `/docs-update $1`.

Ничего не изменяй в коде и файлах - только описывай состояние и next steps.

9. Hooks и headless: жесткий уровень и CI

Этот уровень опционален: он нужен, когда вы хотите, чтобы LLM не уходила от заранее заготовленного flow и не обходила этапы “просто потому что так быстрее”. Hooks и headless-режим позволяют превратить ваш AIDD-процесс в часть инфраструктуры, а не только в набор договоренностей.

9.1. Hooks в .claude/settings.json

Если хочется физически запретить обход этапов, используем hooks.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ""$CLAUDE_PROJECT_DIR"/.claude/hooks/gate-workflow.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ""$CLAUDE_PROJECT_DIR"/.claude/hooks/after-edit.sh"
          }
        ]
      }
    ]
  }
}

gate-workflow.sh проверяет, что для активного тикета выполнены PRD_READY, PLAN_APPROVED, TASKLIST_READY. Если нет – блокирует любой Edit/Write.

#!/usr/bin/env bash
set -euo pipefail

TICKET=$(cat docs/.active_ticket 2>/dev/null || true)

if [ -z "$TICKET" ]; then
  echo "Workflow gate failed: нет активного тикета (docs/.active_ticket)." >&2
  exit 2
fi

PRD_STATUS=$(grep -m1 '^Status:' "docs/prd/$TICKET.prd.md" 2>/dev/null || true)
PLAN_STATUS=$(grep -m1 '^Status:' "docs/plan/$TICKET.md" 2>/dev/null || true)
TASK_STATUS=$(grep -m1 '^Status:' "docs/tasklist/$TICKET.md" 2>/dev/null || true)

if [[ "$PRD_STATUS" != *"PRD_READY"* ]] || 
   [[ "$PLAN_STATUS" != *"PLAN_APPROVED"* ]] || 
   [[ "$TASK_STATUS" != *"TASKLIST_READY"* ]] ; then
  echo "Workflow gate failed: PRD_READY/PLAN_APPROVED/TASKLIST_READY не выполнены для $TICKET." >&2
  echo "Сначала пройди /idea, /plan и /tasks." >&2
  exit 2
fi

exit 0

Код возврата 2 воспринимается Claude как блокирующий: IDE покажет ошибку, и правки просто не будут применены, пока гейты не пройдены.

9.2. Headless и CI

Claude Code умеет работать в headless-режиме через CLI (claude -p, --permission-mode plan).

Что можно делать:

• по cron или в CI прогонять /validate по всем тикетам релиза;

• автоматически собирать сводки по гейтам;

• готовить PRD/планы перед ревью;

• сделать полную автоматизацию процесса.

#!/usr/bin/env bash
set -euo pipefail

if [ $# -lt 1 ]; then
  echo "Usage: $0 TICKET [TITLE]" >&2
  exit 1
fi

TICKET="$1"
TITLE="${2:-}"

claude --permission-mode plan -p "
Ты запущен в headless-режиме в проекте с AIDD-процессом.

Цель: проверить, на каком шаге pipeline находится тикет $TICKET ($TITLE)
и что мешает довести его до RELEASE_READY и DOCS_UPDATED.

1. Вызови /validate $TICKET.
2. На основе результатов опиши:
   - какие гейты уже пройдены;
   - какие артефакты нужно доработать;
   - какие команды я должен запустить в IDE
     (например, /idea, /plan, /tasks, /implement, /qa).
3. Не вноси правок в код, работай только с анализом.
"

Такой скрипт можно дергать из CI, из релизных пайплайнов или локально.

10. Как внедрить у себя: чек-лист уровней

Чтобы съесть слона по частям давайте опишем чек лист для внедрения.

10.1. Уровень 1: Minimal AIDD

Цель – перестать вайб-кодить и ввести базовый AIDD без сложной автоматизации, чтобы не ломать текущий процесс, а аккуратно обогатить его.

Используйте чек-лист:

• [ ] Сформулировать первые Agreements. Создайте conventions.md и CLAUDE.md в одном репозитории. Запишите туда ваш кодстайл, базовые архитектурные решения, требования к тестам и ожидания от AI-ассистента.

• [ ] Добавить простой workflow. В workflow.md опишите цепочку хотя бы на уровне: idea -> plan -> tasks -> implement -> review -> QA -> docs. Это не финальная истина, а стартовая версия, которую проще улучшать, чем придумывать с нуля.

• [ ] Оформить одну фичу как набор артефактов. Для одного реального тикета заведите:

  • docs/prd/<ticket>.prd.md,

  • docs/tasklist/<ticket>.md. Даже без .claude/, просто руками.

• [ ] Подключить LLM как помощника по артефактам, а не “одного мозга”. Попросите модель:

  • дописать PRD по вашим заметкам,

  • предложить tasklist по наброскам плана,

  • нагенерить тест-кейсы по PRD.

• [ ] Реализовать одну фичу через Minimal AIDD. Пройти путь: PRD -> план (даже в свободной форме) -> tasklist -> реализация маленькими шагами -> ревью -> QA (хотя бы чек-листом) -> обновление docs.

• [ ] После цикла – ретроспектива. Посмотреть, что реально помогло, где LLM выручила, а где мешала. На основе этого подкрутить conventions.md и CLAUDE.md.

Когда такой цикл перестанет ощущаться “поверх” процесса и станет “как мы обычно делаем фичи”, можно идти дальше.

10.2. Уровень 2: Full AIDD без жестких гейтов

Цель – построить AIDD как полноценный SDLC и избавиться от части рутины.

• [ ] Завести .claude/agents. Добавить analyst, researcher, planner, task-planner, implementer, reviewer, qa, validator, tech-writer.

• [ ] Описать команды workflow. /idea, /researcher, /plan, /review-prd, /tasks, /implement, /review, /qa, /validate, /feature-development, /docs-update.

• [ ] Стандартизировать артефакты тикетов. Для всех новых фич – шаблонный набор файлов в docs/ и reports/. Опционально:

• [ ] Использовать /validate и оркестратор. Проверять гейты и состояние тикета не вручную, а через AI-валидатор и /feature-development.

На этом уровне процесс уже живет в репозитории как в инструмент, а не только в головах вайб кодеров.

10.3. Уровень 3: Строгий AIDD (когда процесс обкатан)

Цель – чтобы процесс соблюдался и не зависел от хорошего настроения LLM.

• [ ] Подключить hooks в .claude/settings.json. Блокировать изменения кода, если не выполнены базовые гейты. Автоматически запускать линтеры/тесты после правок.

• [ ] Довести оркестратор до “одной команды”. Настроить /feature-development так, чтобы разработчику достаточно было его вызвать и следовать шагам.

• [ ] Добавить headless-скрипты в CI. Проверки гейтов перед релизом, ночные отчеты по состоянию тикетов, подсказки, где процесс “застрял”.

На этом уровне AIDD становится частью инфраструктуры – такой же, как CI, миграции и мониторинг.

11. Итоги и идеи для экспериментов

Если относиться к LLM как к одному большому “мозгу”, получается вайб-коддинг: быстро, местами эффективно, но плохо управляемо в реальном продукте.

Если относиться к LLM как к команде ролей с договорами и гейтами, можно сохранить скорость и не потерять качество.

В статье мы прошли:

• от боли вайб-коддинга до идеи AIDD – AI как команда ролей;

• от минимального набора файлов (conventions.md, CLAUDE.md, PRD, tasklist) до Full AIDD;

• от абстрактных ролей до конкретных агентов и команд в Claude Code;

• от “LLM пишет код” до процесса: PRD -> план -> задачи -> реализация -> ревью -> QA -> доки;

• от договоренностей “на словах” до quality-гейтов, валидатора и hooks.

Пару мыслей напоследок:

• Онбордите AI-команду. Вносите практики в conventions.md, CLAUDE.md, workflow.md, .claude/agents/*, .claude/commands/*.

• Планируйте и специфицируйте. PRD, архитектура, ADR, ресерч кодовой базы – это контекст, в котором LLM начинает работать “по-взрослому”.

• Дробите работу на задачи. Ведите docs/tasklist/<ticket>.md как источник истины по прогрессу.

• Стройте итеративный цикл с AI-разработчиком. План -> согласование -> код -> diff -> остановка -> ревью/тесты.

• Встраивайте ревью, QA и доку в каждую итерацию. Не только unit-тесты, но и финальный QA- и DOCS-слой.

• Пусть LLM помогает фиксировать историю проекта. Описывать архитектуру, принимать и документировать решения, обновлять онбординг.

• Автоматизируйте, когда процесс “приживется”. Оркестратор, hooks, headless и CI – следующий шаг, а не обязательное требование с первого дня.

Что можно сделать, чтобы поэкспериментировать

Если хочется не просто почитать, а попробовать:

1. Возьмите один живой сервис и один не слишком критичный тикет.

2. Добавьте в репо conventions.md и CLAUDE.md в том виде, в каком вы видите свою команду сейчас.

3. Оформите для этой фичи PRD и tasklist в docs/.

4. Попросите LLM не писать код сразу, а пройти с вами путь:

   1. доформулировать PRD,

   2. предложить архитектуру,

   3. разбить работу на задачи,

   4. реализовать 1-2 задачи маленькими шагами.

5. Посмотрите, как изменится скорость и качество, и что вам мешает:

   1. не хватает конвенций,

   2. неудобный шаблон PRD,

   3. слишком крупные задачи и т.п.

6. После первой итерации уже можно думать про .claude/agents, /idea, /tasks, /implement и остальные элементы Full AIDD.

Дальше уже ваша команда решит, на каком уровне AIDD остановиться:
останетесь на Minimal, встроите Full AIDD в ваш процесс разработки с Claude Code или дойдете до строгого варианта с жесткими гейтами и CI. Главное – перестать воспринимать LLM как “один большой мозг” и начать относиться к ней как к части инженерного процесса.