# Часть 21. Заключение и рабочая система

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

Если оставить одну формулу, она такая:

```text
Спецификация хранит долговременное намерение.
Факты решают, можно ли сливать ветку.
Агент быстро исполняет.
Человек отвечает за суждение.
```

Или ещё короче:

```text
Спецификации направляют.
Факты допускают к слиянию.
```

## Итоговая структура репозитория

```text
agentclinic/
  AGENTS.md
  QWEN.md
  README.md
  CHANGELOG.md
  package.json
  tsconfig.json
  .qwen/
    settings.json
    hooks/
      pre_tool_guard.py
      log_tool_result.py
      inject_sdd_context.py
    memory/
      agent-memory.db
    skills/
      feature-spec/
        SKILL.md
      changelog/
        SKILL.md
  specs/
    mission.md
    tech-stack.md
    roadmap.md
    2026-05-01-hello-hono/
      requirements.md
      plan.md
      validation.md
    2026-05-02-agents-ailments/
      requirements.md
      plan.md
      validation.md
  src/
  tests/
.github/
  pull_request_template.md
```

## Операционный цикл

Перед каждой фичей:

```bash
git checkout main
git pull --ff-only
git status --short
npm test
npm run typecheck
```

В Qwen Code:

```text
/clear
Используй навык feature-spec, чтобы начать следующую фичу из дорожной карты.
Код не реализуй.
```

После спецификации:

```bash
git add specs/YYYY-MM-DD-feature-name
git commit -m "Add <feature> spec"
```

Реализация:

```text
/clear
Прочитай @QWEN.md, @specs/mission.md, @specs/tech-stack.md
и @specs/YYYY-MM-DD-feature-name/plan.md.
Реализуй только группу задач 1.
Остановись после отчёта об изменённых файлах и командах проверки.
```

Проверка:

```text
/clear
Сравни реализацию с @specs/YYYY-MM-DD-feature-name/validation.md.
Перечисли подтверждённые факты, проваленные факты, отсутствующие факты
и неоднозначные пункты проверки.
Файлы не изменяй.
```

Слияние:

```text
Используй навык changelog, чтобы обновить @CHANGELOG.md для этой ветки.
```

```bash
npm test
npm run typecheck
git checkout main
git merge <feature-branch>
git branch -d <feature-branch>
```

Перепланирование:

```text
/clear
Проверь @specs/mission.md, @specs/tech-stack.md, @specs/roadmap.md,
недавние спецификации фич и @CHANGELOG.md.
Что нужно обновить перед следующей фичей?
Файлы не изменяй, пока я не одобрю.
```

## Границы решений

Записывайте в `mission.md`:

- аудиторию;
- продуктовый смысл;
- тон;
- определение успеха.

Записывайте в `tech-stack.md`:

- язык;
- среду выполнения;
- фреймворк;
- базу данных;
- тестирование;
- ограничения развёртывания;
- запрещённые или отложенные технологии.

Записывайте в `roadmap.md`:

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

Записывайте в спецификацию фичи:

- границы и то, что в них не входит;
- решения именно этой фичи;
- группы задач;
- набор фактов в `validation.md`;
- команды проверки с ожидаемыми результатами;
- статусы фактов: черновик, обязательный, реализован, отложен;
- ручные проверки.

Записывайте в `QWEN.md` или `AGENTS.md`:

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

## Самые частые ошибки

1. Слишком большая первая фича. Начните с инфраструктурной заготовки, не с MVP.
2. Спецификация написана, но не используется в запросе на реализацию.
3. Проверка ограничена словами «выглядит нормально» вместо фактов.
4. Перепланирование пропускается, и спецификации устаревают.
5. Агенту дают старый контекст чата вместо файлов.
6. Навыки создаются слишком рано, до понимания процесса.
7. В `QWEN.md` кладут всё подряд, и агент перестаёт следовать главному.
8. MCP подключают без ясной задачи.

## Как внедрять в реальной команде

Начните не с процесса на 20 страниц, а с одного правила:

```text
Ни одной многофайловой фичи без requirements.md, plan.md и validation.md.
```

Затем добавьте:

- короткий `AGENTS.md`;
- `specs/mission.md`;
- `specs/tech-stack.md`;
- дорожную карту на ближайшие 3–5 фаз;
- один проектный навык для спецификации фичи;
- один навык для журнала изменений;
- обязательный список проверок в запросе на слияние.

Через 2–3 фичи проведите ретроспективу:

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

## Минимальный шаблон SDD

```text
specs/
  mission.md
  tech-stack.md
  roadmap.md
  YYYY-MM-DD-feature/
    requirements.md
    plan.md
    validation.md
```

Этого достаточно для начала. Не нужно ждать идеального фреймворка.

## Шкала зрелости SDD

Чтобы понимать, где вы находитесь и куда двигаться, удобно описать SDD-процесс в команде по короткой шкале от 0 до 4. Эта шкала не претендует на канон; она помогает заметить, какой шаг сейчас даст больше всего.

- **Уровень 0 — вайб-кодинг.** Один длинный чат с агентом. Решения остаются в истории сессии. Спецификаций нет, проверка — «посмотри, как работает».
- **Уровень 1 — спецификации появляются, но факультативно.** В крупных фичах команда пишет `requirements.md`, в мелких — нет. `validation.md` чаще похож на список пожеланий. `/clear` между ролями забывается.
- **Уровень 2 — SDD как стандарт по умолчанию.** Любая многофайловая фича начинается со спецификации. `validation.md` содержит исполняемые факты. `/clear` между ролями стал привычкой. Перепланирование проводится между фичами.
- **Уровень 3 — кодифицированный процесс.** Повторяемые запросы вынесены в навыки. Защитные хуки автоматически проверяют опасные операции. Ревью идёт по четырём слоям (часть 16). Антипаттерны (часть 20) распознаются и быстро исправляются.
- **Уровень 4 — обучаемый процесс.** Команда регулярно превращает наблюдения в новые правила (часть 10, шаг кодификации). Память агента подключена там, где она действительно полезна, и удаляется там, где избыточна. Заменяемость агента (часть 15) проверена практикой: команда меняла инструмент и не теряла процесс.

Большинство учебных команд находятся между уровнями 0 и 2. Цель учебника — довести вашу команду до уровня 2 на дидактическом проекте AgentClinic. Уровни 3 и 4 — это уже про конкретную команду, конкретный продукт и конкретный год. Они не должны быть самоцелью.

Признак, что вы перешли с уровня 1 на 2: новая фича в команде по умолчанию начинается со спецификации, а не с просьбы «напиши код».

Признак, что вы перешли с уровня 2 на 3: при появлении повторяющейся ошибки агента кто-то спокойно говорит «давайте добавим правило в `QWEN.md`», и это правило действительно появляется.

## Финальная практика

Возьмите свой реальный проект и добавьте только:

1. `AGENTS.md` или `QWEN.md`;
2. `specs/mission.md`;
3. `specs/tech-stack.md`;
4. `specs/roadmap.md`;
5. спецификацию одной маленькой фичи.

Попросите Qwen Code:

```text
Действуй как новый агент без предыдущего контекста.
Прочитай проектные SDD-артефакты.
Скажи, можешь ли безопасно реализовать следующую фичу.
Перед написанием кода перечисли недостающую информацию.
```

Если агент задаёт хорошие вопросы, вы на правильном пути.

## Контрольные вопросы

1. Какие файлы должны позволить новому агенту понять проект?
2. Что делать, если реализация прошла тесты, но не соответствует спецификации?
3. Какой самый маленький SDD-процесс вы можете внедрить завтра?