Прикладной том. Production SDD для Qwen Code CLI
Этот каталог — второй, прикладной том учебника. Первый том в book/ учит базовому циклу SDD на AgentClinic: конституция, спецификация фичи, план, проверяемые факты, реализация, ревью и перепланирование. Второй том переносит тот же цикл в production-сценарии: legacy-следы, валидаторы, многоагентные проверки, Spec CI, метрики, бюджеты моделей и ограниченную авто-ремедиацию.
Версия: v1.0 — проверено 2026-05-20. Историю изменений см. в CHANGELOG.md.
Материал не рассчитан на первое знакомство с SDD. Перед чтением нужно понимать requirements.md, plan.md, validation.md, QWEN.md, границы фичи, отрицательные требования и проверку фактами. Если эти слова ещё не стали рабочими, сначала пройдите первый том.
Главное правило второго тома: первый проход должен оставить один маленький проверяемый след, а не познакомить со всей production-терминологией. В каждой главе сначала закрывайте учебный минимум: один артефакт, одна команда или один блокер для capstone/. Основной зачётный кейс — high_memory_usage; правила переноса локальных кейсов в основной описаны в части 0.
Быстрый старт
- Откройте часть 0 и возьмите основной кейс
high_memory_usage. - Создайте пустой
capstone/. - В главах 1–3 заполните
genealogy.md, poisoned/fixed-пару иconstitution.md. - В главах 4–11 выполняйте только раздел «Минимальный учебный сценарий» и runnable-команды из [
examples/](examples/); если глава использует другой кейс (autoscale_200pct,node_not_ready,appointment_latency/appointment_latency_spike,cdn_error_budget_burn), запишите одну строку переноса — какой принцип этого кейса защищает основнойhigh_memory_usage. - В главе 12 проверьте пакет по антипаттернам.
- В главе 13 соберите итоговый
capstone/README.mdи проверьте, что его можно понять без истории чата.
Минимальная проверка примеров, включая ожидаемые блокировки:
bash book2/examples/smoke_all.shКак читать главы
Главы 1–12 должны читаться в одном ритме. В начале главы сначала найдите короткий блок «Перед чтением»: он отвечает, что именно глава берёт из первого тома, какой локальный кейс запускает, что переносится в capstone/ и что относится к полному треку.
Дальше держите пять вопросов:
- Опора из первого тома. Какая идея AgentClinic расширяется.
- Минимальный учебный сценарий. Что сделать руками или запустить локально.
- Контрольный факт. Что доказывает, что глава отработана.
- **Как это попадает в
capstone/.** Какая строка или файл остаётся после главы. - Полный трек. Что понадобится только при внедрении в настоящий 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. Совместимость команд Qwen Code описана в приложении B. Чек-листы собраны в приложении C.
Почему кейс меняется от главы к главе
Основной зачётный кейс — 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/ |
Если кейс главы не переносится одной строкой — глава прочитана, но не закрыта.
Части
- Лаборатория AgentClinic-production
- Восстановление спецификаций из legacy
- Диагностика дефектов спецификации
- Конституция проекта: первый референдум правил
- LLM-дуэль: Верификатор против Имплементора в формальных утверждениях
- Мутационное тестирование спецификаций
- Отбор теневых спецификаций
- Specification CI: спецификация как исполняемый артефакт
- Файловый арбитраж спорного изменения: роли, вердикты и прецеденты
- Маршрутизация моделей и бюджет токенов
- Защита метрик от Гудхарта: сторожевые метрики и аварийный режим
- Интеграция с реальным API: от спецификации до деплоя
- Антипаттерны production SDD: диагностическая карта прикладного цикла
- Практический зачёт: собрать production SDD-контур
Сопроводительные документы
- Глоссарий прикладного тома — определения терминов второго тома.
- Журнал изменений прикладного тома — история редакций текста.
- Заметка для преподавателя — форматы воркшопов и типичные ошибки.
- Мосты к первому тому — предпосылки и доменная карта AgentClinic.
- Совместимость с Qwen Code — встроенные команды, пользовательские команды и проектные скрипты.
- Чек-листы прикладного SDD — проверки для Spec CI, арбитража, метрик и production-готовности.
- Калибровка порогов — таблицы «Низкий / По умолчанию / Высокий», упражнения по сдвигу порогов и сигналы пересмотра для глав 5, 6, 9, 10, 11. На первом проходе не нужно.
- Runnable-примеры — локальные smoke-прогоны и шаблоны.
Что считать успехом
К концу прикладного тома должен получиться не набор красивых правил, а воспроизводимый контур:
- спорные требования имеют провенанс и уровень неопределённости;
- опасные автоматизации ограничены конституцией, ограждениями (guardrails) и условиями отката;
validation.mdпроверяет happy path, negative path, контрпримеры, дрейф и ловушки Гудхарта;- CI или его runnable-аналог блокирует непокрытые требования и слабые контракты полезной нагрузки;
- решения агентов оставляют доказательства, пригодные для ревью другим человеком или другой моделью;
- итоговый
capstone/показывает один путь от legacy-следа до production-ready решения с явными блокерами и планом исправлений.