# Прикладной том. Production SDD для Qwen Code CLI

Этот каталог — второй, прикладной том учебника. Первый том в `book/` учит базовому циклу SDD на AgentClinic: конституция, спецификация фичи, план, проверяемые факты, реализация, ревью и перепланирование. Второй том переносит тот же цикл в production-сценарии: legacy-следы, валидаторы, многоагентные проверки, Spec CI, метрики, бюджеты моделей и ограниченную авто-ремедиацию.

Версия: v1.0 — проверено 2026-05-20. Историю изменений см. в [CHANGELOG.md](CHANGELOG.md).

Материал не рассчитан на первое знакомство с SDD. Перед чтением нужно понимать `requirements.md`, `plan.md`, `validation.md`, `QWEN.md`, границы фичи, отрицательные требования и проверку фактами. Если эти слова ещё не стали рабочими, сначала пройдите первый том.

Главное правило второго тома: первый проход должен оставить один маленький проверяемый след, а не познакомить со всей production-терминологией. В каждой главе сначала закрывайте учебный минимум: один артефакт, одна команда или один блокер для `capstone/`. Основной зачётный кейс — `high_memory_usage`; правила переноса локальных кейсов в основной описаны в [части 0](part-00-production-lab.md).

## Быстрый старт

1. Откройте [часть 0](part-00-production-lab.md) и возьмите основной кейс `high_memory_usage`.
2. Создайте пустой `capstone/`.
3. В главах 1–3 заполните `genealogy.md`, poisoned/fixed-пару и `constitution.md`.
4. В главах 4–11 выполняйте только раздел «Минимальный учебный сценарий» и runnable-команды из [`examples/`](examples/); если глава использует другой кейс (`autoscale_200pct`, `node_not_ready`, `appointment_latency` / `appointment_latency_spike`, `cdn_error_budget_burn`), запишите одну строку переноса — какой принцип этого кейса защищает основной `high_memory_usage`.
5. В главе 12 проверьте пакет по антипаттернам.
6. В главе 13 соберите итоговый `capstone/README.md` и проверьте, что его можно понять без истории чата.

Минимальная проверка примеров, включая ожидаемые блокировки:

```bash
bash book2/examples/smoke_all.sh
```

## Как читать главы

Главы 1–12 должны читаться в одном ритме. В начале главы сначала найдите короткий блок «Перед чтением»: он отвечает, что именно глава берёт из первого тома, какой локальный кейс запускает, что переносится в `capstone/` и что относится к полному треку.

Дальше держите пять вопросов:

1. **Опора из первого тома.** Какая идея AgentClinic расширяется.
2. **Минимальный учебный сценарий.** Что сделать руками или запустить локально.
3. **Контрольный факт.** Что доказывает, что глава отработана.
4. **Как это попадает в `capstone/`.** Какая строка или файл остаётся после главы.
5. **Полный трек.** Что понадобится только при внедрении в настоящий production-репозиторий.

Если глава кажется плотной, не читайте её линейно. Сначала выполните минимальный сценарий, затем вернитесь к «Ключевым идеям», и только после этого смотрите калибровки, `[project script]` и `[conceptual interface]`. Термин, который не помогает заполнить текущий файл `capstone/`, можно пропустить до второго прохода.

Редакторское правило второго тома: на первом проходе новая глава должна добавлять не больше одного нового обязательного термина к вашему рабочему словарю. Если встречается ещё пять названий, но они не нужны для текущего файла `capstone/`, считайте их справочными и возвращайтесь к ним после минимального сценария.

Практический тест для главы: после минимального сценария читатель должен уметь записать одну строку в один файл `capstone/`. Если для этого нужно понять два новых механизма сразу, один из них относится ко второму проходу или полному треку.

## Пометки статуса и команд

В главах используются те же уровни уверенности, что в первом томе:

- **Стандарт** — зафиксированное поведение инструмента или общепринятая практика.
- **Рекомендация** — практика, которая работает в большинстве случаев, но допускает адаптацию.
- **Фронтир** — подход применяют, но форма зависит от команды, моделей и инфраструктуры.

Командные блоки делятся на три типа:

- **[runnable]** — работает локально в [`book2/examples/`](examples/) без внешних зависимостей.
- **[project script]** — интерфейс скрипта, который нужно реализовать в своём проекте.
- **[conceptual interface]** — форма будущего оркестратора, policy gate, MCP-слоя или CI-интеграции.

Для учебного прохождения нужны только `[runnable]`-блоки и ручные артефакты. Всё остальное относится к полному треку.

## Сквозной маршрут

| Главы | Что сделать на первом проходе | Что отложить |
|---|---|---|
| 0 | понять AgentClinic-production, выбрать `high_memory_usage`, создать пустой `capstone/` | адаптацию под свой production-домен |
| 1–3 | восстановить одно требование, показать один дефект, оформить `constitution.md` | автоматические нормализаторы доказательств и референдумы правил |
| 4–5 | получить контрпример и smoke-результат стресс-мутатора | постоянную дуэль и фабрику мутаций в CI |
| 6–7 | принять/отклонить теневой кандидат, запустить Spec CI | полноценный scorebook, scope-gate и PR-отчёты |
| 8–9 | собрать `judgment.md`, проиграть отказ дешёвого яруса | отдельный бюджетный сервис и арбитражный оркестратор |
| 10–11 | проверить guard-метрики, readiness и dry-run для `high_memory_usage` | GitOps-деплой и автоматическую ремедиацию без ручного подтверждения |
| 12 | записать три риска `blocker / owner / next_check` | превращение каждого антипаттерна в CI-политику |
| 13 | собрать итоговый пакет доказательств | production-ready внедрение всего процесса |

## Обязательные артефакты первого прохода

Следите только за этими файлами. Остальные термины можно дочитать после того, как основной пакет уже читается как один кейс.

- `genealogy.md` — откуда взялось требование.
- `poisoned-spec.md` / `fixed-spec.md` — какой дефект найден и чем исправлен.
- `constitution.md` — какие действия агенту запрещены или разрешены с ограничениями.
- `validation.md` — какие факты реально проверены.
- `judgment.md` — какой вердикт вынесен и на каком доказательстве.
- `budget-note.md` — что происходит при отказе дешёвого яруса.
- `goodhart-note.md` — какая метрика может начать врать и какая guard-метрика её ограничивает.
- `readiness.md` — почему контур допускается, блокируется или уходит в полуручной режим.
- `antipattern-audit.md` — три риска в форме `blocker / owner / next_check` после прохода главы 12.
- `capstone/README.md` — итоговая сборка пакета по одному кейсу.

Глава 6 добавляет короткий блок `Shadow notes` в `capstone/README.md` (или, если используете `QWEN.md` в учебном репозитории, — туда). Это не отдельный файл основного списка.

Остальные имена (`scorebook`, `metric_network`, `decision_hash`, `precedents.md`) относятся к полному треку, если прямо не помогают заполнить один из файлов выше.

Каждая глава должна дать минимальный итоговый фрагмент для одного из этих файлов. Если после главы у вас есть только общее понимание, но нет строки, команды или блокера для `capstone/`, глава ещё не закрыта на учебном уровне.

Сквозная карта «какая глава пишет какой файл `capstone/`»:

| Файл `capstone/` | Глава, которая его открывает | Главы, которые его дополняют |
|---|---|---|
| `genealogy.md` | 1 | 13 (итоговая сборка) |
| `poisoned-spec.md` / `fixed-spec.md` | 2 | 13 |
| `constitution.md` | 3 | 12 (антипаттерны mutable-правил), 13 |
| `validation.md` — happy/negative + контрпример | 4 | 5 (мутанты), 7 (Spec CI), 13 |
| `validation.md` — мутационный иммунитет | 5 | 13 |
| блок `Shadow notes` в `capstone/README.md` | 6 | 13 |
| `validation.md` — строка Spec CI | 7 | 13 |
| `judgment.md` | 8 | 12 (антипаттерны арбитража), 13 |
| `budget-note.md` | 9 | 13 |
| `goodhart-note.md` | 10 | 13 |
| `readiness.md` | 11 | 13 |
| `antipattern-audit.md` | 12 | 13 |
| `capstone/README.md` — сборка | 13 | — |

Перед самостоятельным зачётом откройте [`examples/templates/capstone-dossier.md`](examples/templates/capstone-dossier.md). Это заполненный эталон минимального пакета по `high_memory_usage`: он показывает, насколько коротким может быть хороший первый проход.

## Карта глав

| Глава | Опора из первого тома | Минимальный выход |
|---|---|---|
| 0. Лаборатория AgentClinic-production | итоговая структура проекта и практический зачёт | выбранный кейс, пустой `capstone/`, команда smoke |
| 1. Восстановление спецификаций из legacy | поддержка существующего проекта | одна запись в `genealogy.md` |
| 2. Диагностика дефектов спецификации | отрицательные требования и факты | poisoned/fixed-пара |
| 3. Конституция проекта | `mission.md`, `tech-stack.md`, `roadmap.md`, `QWEN.md` | два immutable-правила и одно mutable-правило |
| 4. LLM-дуэль | отдельная проверочная сессия | один контрпример или `next_guard` |
| 5. Мутационное тестирование спецификаций | negative path и контрпримеры | результат stress-mutator |
| 6. Отбор теневых спецификаций | память проекта и few-shot | один принятый и один отклонённый кандидат |
| 7. Specification CI | связь `requirements.md → plan.md → validation.md` | строка Spec CI с PASS/BLOCK |
| 8. Файловый арбитраж | независимое ревью | `judgment.md` с `evidence_ref` |
| 9. Ярусные бюджеты | выбор модели под риск задачи | бюджетный риск и `token_health` |
| 10. Защита метрик от Гудхарта | факты вместо убедительной прозы | KPI и guard-метрика |
| 11. Production API | границы фичи, откат, ручная проверка | readiness и dry-run |
| 12. Антипаттерны production SDD | антипаттерны SDD | три диагностических риска |
| 13. Практический зачёт | полный SDD-цикл | итоговый пакет `capstone/` |

Полная доменная карта AgentClinic находится в [приложении A](appendix-a-bridges-to-book.md). Совместимость команд Qwen Code описана в [приложении B](appendix-b-qwen-code-compatibility.md). Чек-листы собраны в [приложении C](appendix-c-checklists.md).

## Почему кейс меняется от главы к главе

Основной зачётный кейс — `high_memory_usage`. Но главы 1–10 берут разные инциденты, потому что не каждый из них одинаково хорошо показывает изучаемый механизм: где-то проще конфликт приоритетов виден на другом домене, где-то нужна история мутаций, которой в `high_memory_usage` нет. Один кейс на весь том превратил бы каждый шаблон в формальность.

Правило переноса простое: после главы запишите одну строку — какой принцип этого кейса защищает ваш `high_memory_usage`.

| Глава | Кейс главы | Что переносится в `high_memory_usage` |
|---|---|---|
| 1 | `node_not_ready` | техника восстановления требования из пост-мортема и провенанс |
| 2 | `appointment_latency` | один контролируемый конфликт приоритетов и обратный прогон |
| 3 | `node_not_ready` | immutable-принцип и одно mutable-правило с `ttl` и `rollback_condition` |
| 4 | `autoscale_200pct` | минимальный контрпример и `next_guard` для нарушенного Then |
| 5 | `payment_latency_spike` | smoke-результат мутатора и вектор иммунитета валидатора |
| 6 | `shadow.p0.voice_handoff` | один принятый и один отклонённый теневой кандидат |
| 7 | `incident payload` | строка Spec CI с PASS на покрытии и BLOCK на схеме |
| 8 | `autoscale_200pct` | `judgment.md` с `verdict`, `evidence_ref` и роль Safety |
| 9 | `autoscale_200pct` | бюджетный риск, `token_health` и сценарий отказа дешёвого яруса |
| 10 | `cdn_error_budget_burn` | парная anti-Goodhart-метрика к KPI ремедиации |
| 11 | `high_memory_usage` | readiness 23/25 и dry-run для основного кейса |
| 12 | любой пакет глав 8–11 | три строки `blocker / owner / next_check` |
| 13 | `high_memory_usage` | сборка всех артефактов в единый `capstone/` |

Если кейс главы не переносится одной строкой — глава прочитана, но не закрыта.

## Части

0. [Лаборатория AgentClinic-production](part-00-production-lab.md)
1. [Восстановление спецификаций из legacy](part-01-spec-archaeology.md)
2. [Диагностика дефектов спецификации](part-02-poisoned-specs.md)
3. [Конституция проекта: первый референдум правил](part-03-project-constitution.md)
4. [LLM-дуэль: Верификатор против Имплементора в формальных утверждениях](part-04-llm-duel.md)
5. [Мутационное тестирование спецификаций](part-05-stress-specs.md)
6. [Отбор теневых спецификаций](part-06-shadow-specs.md)
7. [Specification CI: спецификация как исполняемый артефакт](part-07-specification-ci.md)
8. [Файловый арбитраж спорного изменения: роли, вердикты и прецеденты](part-08-multiagent-tribunal.md)
9. [Маршрутизация моделей и бюджет токенов](part-09-tier-budgeting.md)
10. [Защита метрик от Гудхарта: сторожевые метрики и аварийный режим](part-10-goodhart-metrics.md)
11. [Интеграция с реальным API: от спецификации до деплоя](part-11-real-api-deployment.md)
12. [Антипаттерны production SDD: диагностическая карта прикладного цикла](part-12-production-antipatterns.md)
13. [Практический зачёт: собрать production SDD-контур](part-13-capstone.md)

## Сопроводительные документы

- [Глоссарий прикладного тома](GLOSSARY.md) — определения терминов второго тома.
- [Журнал изменений прикладного тома](CHANGELOG.md) — история редакций текста.
- [Заметка для преподавателя](INSTRUCTOR.md) — форматы воркшопов и типичные ошибки.
- [Мосты к первому тому](appendix-a-bridges-to-book.md) — предпосылки и доменная карта AgentClinic.
- [Совместимость с Qwen Code](appendix-b-qwen-code-compatibility.md) — встроенные команды, пользовательские команды и проектные скрипты.
- [Чек-листы прикладного SDD](appendix-c-checklists.md) — проверки для Spec CI, арбитража, метрик и production-готовности.
- [Калибровка порогов](appendix-d-threshold-calibration.md) — таблицы «Низкий / По умолчанию / Высокий», упражнения по сдвигу порогов и сигналы пересмотра для глав 5, 6, 9, 10, 11. На первом проходе не нужно.
- [Runnable-примеры](examples/README.md) — локальные smoke-прогоны и шаблоны.

## Что считать успехом

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

- спорные требования имеют провенанс и уровень неопределённости;
- опасные автоматизации ограничены конституцией, ограждениями (guardrails) и условиями отката;
- `validation.md` проверяет happy path, negative path, контрпримеры, дрейф и ловушки Гудхарта;
- CI или его runnable-аналог блокирует непокрытые требования и слабые контракты полезной нагрузки;
- решения агентов оставляют доказательства, пригодные для ревью другим человеком или другой моделью;
- итоговый `capstone/` показывает один путь от legacy-следа до production-ready решения с явными блокерами и планом исправлений.