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

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

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

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

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

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

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

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

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

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

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

В Qwen Code:

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

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

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

Реализация:

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

Проверка:

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

Слияние:

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

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

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

/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.

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

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

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

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

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

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

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

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

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

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:

Действуй как новый агент без предыдущего контекста.

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

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

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

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