Прикладная часть 11. Интеграция с реальным API: от спецификации до деплоя

Статус: Рекомендация. SDD-разделение фаз Specify/Plan/Tasks/Implement/Validate и 25-балльная модель готовности (readiness) — рекомендуемая рамка. Она не требует настоящего Kubernetes, GitOps или внешнего executor на учебном проходе.

Фронтир. Полностью автоматизированная авто-ремедиация без ручного подтверждения (human-review) на критическом пути остаётся фронтиром: даже команды с большим SDD-опытом удерживают человека в контуре. Из встроенных команд Qwen Code здесь только /plan; остальные шаги — пользовательские команды или прямые qwen -p через проектные скрипты.

Для учебного прохождения достаточно локального конвейера examples/real-api/: нормализовать вебхуки, пройти шлюз готовности и заблокировать запрещённое действие. GitOps, Kubernetes API и полная авто-ремедиация относятся к полному production-треку.

> [runnable] — запускаемый аналог конвейера «вебхук → нормализация → шлюз готовности → пробный прогон» лежит в [examples/real-api/](examples/real-api/README.md). Скрипты работают на stdlib без внешних зависимостей; они не заменяют production-инфраструктуру, но позволяют локально прогнать шлюз и увидеть, какие условия блокируют действие.

Сценарий high_memory_usage — это пик чтений по тому же SQLite, который мы строили в части 12 первого тома, и тот же приём идемпотентной миграции. Только теперь он рассматривается со стороны эксплуатации. Цикл Specify → Plan → Tasks → Implement, отработанный в части 7, части 8 и части 9 первого тома, здесь не отменяется и не подменяется. Он оборачивается production-шлюзом и завершается командным ревью пакета доказательств в духе части 16.

Перед чтением

• Опора из первого тома: части 7–9 задают цикл спецификация-план-проверка, часть 16 — командное ревью.
• Локальный учебный кейс: high_memory_usage, канонический кейс всего первого прохода.

• След для capstone/: readiness-вердикт, два блокирующих условия и dry-run разрешённого действия.
• Главные термины первого прохода: readiness и dry-run. 25-балльная рубрика, audit_trace, GitOps, executor — справочные.
• Что отложить: GitOps, Kubernetes API, полный executor и авто-ремедиацию без ручного подтверждения.

Цель

В учебном минимуме эта глава проверяет короткую цепочку вебхук -> нормализация -> readiness -> dry-run для high_memory_usage. Полный production-трек расширяет её до GitOps-деплоя, отката (rollback) изменений и оценки готовности перед ограниченной авто-ремедиацией. Каждое действие должно быть связано с артефактами specify/plan/tasks/implement/validate, а не теряться в ручных командах.

Практический результат первого прохода — не production-оркестратор, а доказательство, что разрешённое действие проходит readiness, а запрещённое блокируется до изменения системы.

readiness (готовность) здесь — это формальная оценка конвейера по 25-балльной шкале с порогом 23/25. Авто-ремедиация в этой главе означает ограниченный плейбук с заранее согласованными действиями (pre-approved actions), условиями отката и ручным подтверждением человеком (human-review). Это не право агента произвольно менять production.

Из встроенных команд Qwen Code в этом конвейере только /plan. Остальные шаги — /sdd:specify, /sdd:tasks, /sdd:validate — оформите как пользовательские команды в .qwen/commands/sdd/ или замените обычными подсказками через qwen -p и проектные скрипты.

Минимальный учебный сценарий

Учебный кейс

Production-инцидент high_memory_usage для appointments-api — производный от MVP-фазы и SQLite-миграций из book/part-12-mvp.md. Конвейер: вебхук Grafana+PagerDuty → normalize_webhook.py → шлюз готовности по 25-балльной модели → пробный прогон против списка заранее согласованных действий. Цель — пройти полный путь от сырой полезной нагрузки до контролируемого restart_pod и убедиться, что блокирующие условия (аудит, stateful) ловят сбой именно там, где должны.

Подготовка

• book2/examples/real-api/fixtures/webhook_grafana.json, webhook_pagerduty.json — сырые полезные нагрузки с одинаковым incident_key.
• book2/examples/real-api/fixtures/incident_event.expected.json — эталон нормализованного события.
• book2/examples/real-api/fixtures/readiness_pass.json (24/25), readiness_block_audit.json (22/25 + аудит ниже 1.0), readiness_block_stateful.json (24/25, но stateful без резервной копии).
• book2/examples/real-api/specs/high_memory_usage/specify.md — заранее согласованные restart_pod и scale_up_replicas_one.
• book2/examples/real-api/scripts/normalize_webhook.py, check_readiness.py, dry_run.py.

Шаги

1. cd book2/examples/real-api. Ожидание: вы в каталоге примера, дополнительных зависимостей нет.
2. python3 scripts/normalize_webhook.py --grafana fixtures/webhook_grafana.json --pagerduty fixtures/webhook_pagerduty.json --expected fixtures/incident_event.expected.json. *Ожидание: код возврата 0, нормализованный incident_event совпал с эталоном.*
3. python3 scripts/check_readiness.py --readiness fixtures/readiness_pass.json. *Ожидание: код возврата 0, PASS incident=HM-2026-05-17-01 score=24/25.*

1. python3 scripts/check_readiness.py --readiness fixtures/readiness_block_audit.json. *Ожидание: код возврата 1, причина — audit_trace_coverage=0.7 < 1.0, плюс падение по сумме баллов (22/25).*
2. python3 scripts/check_readiness.py --readiness fixtures/readiness_block_stateful.json. *Ожидание: код возврата 1, причина — stateful workload без подтверждённой резервной копии, при том что сумма 24/25.*

Плохо: запустить dry_run.py до шлюза готовности — действие формально разрешено спецификацией, но audit_trace_coverage или backup_verified могут отсутствовать. Хорошо: сначала шлюз готовности, пробный прогон только при коде возврата 0 от шлюза — последовательность гарантирует, что радиус последствий известен до проверки списка действий.

1. python3 scripts/dry_run.py --spec specs/high_memory_usage/specify.md --action restart_pod. *Ожидание: код возврата 0, PASS: action=restart_pod разрешён (2 actions в spec).*
2. python3 scripts/dry_run.py --spec specs/high_memory_usage/specify.md --action delete_namespace. *Ожидание: код возврата 1, BLOCK: action="delete_namespace" не найден среди pre-approved.*

1. Для учебного минимума на этом остановитесь: runnable-цепочка показала нормализацию, PASS для разрешённого пути и BLOCK для audit/stateful/delete-namespace.

Если у вас установлен Qwen Code и нужно объяснение для ревью, выполните отдельный необязательный шаг:

qwen -p "Прочитай @fixtures/readiness_block_audit.json и @specs/high_memory_usage/specify.md. Что нужно дополнить, чтобы readiness достиг 23/25 и audit_trace_coverage=1.0? Файлы не меняй." --approval-mode plan

Этот запрос не входит в runnable-минимум. Его вывод можно приложить к ревью, но readiness-допуск должен опираться на check_readiness.py и dry_run.py.

Контрольный факт

Шаги 3, 6 — PASS. Шаги 4, 5, 7 — BLOCK с конкретной причиной в stderr. Если шаг 5 проходит при stateful=true, backup_verified=false, шлюз готовности сломан: жёсткий блок для stateful обойти нельзя.

Как это попадает в capstone/

Перенесите в capstone/readiness.md итог readiness, два блокирующих условия и результат dry_run.py для разрешённого действия. В capstone/validation.md укажите команды, которые реально запускались. GitOps, Kubernetes API и полный executor не входят в учебный минимум, если они не были реализованы.

Читать этот фрагмент так: одна положительная фикстура показывает допустимый путь, два blockers фиксируют конкретные причины отказа, dry_run — пограничный случай разрешённого и заблокированного действия. Если хоть одной строки нет, пакет readiness неполный.

readiness:
  pass_fixture: "readiness_pass.json -> 24/25"
  blockers:
    - "audit_trace_coverage=0.7 blocks auto mode"
    - "stateful=true without backup_verified blocks action"
  dry_run: "restart_pod PASS; delete_namespace BLOCK"

Ревьюируемый след

Скрипты пишут в stdout/stderr и не создают out/. Зафиксируйте прогон читаемым артефактом: коротким capstone/readiness.md или отчётом CI, если он есть в вашем проекте. Минимальное содержание — те же четыре строки YAML из блока выше (pass_fixture, два blockers, dry_run); полный отчёт по 25 баллам нужен только в полном треке.

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

Ключевые идеи

Стартовая точка трассировки — audit_trace (живой лог Qwen Code), в котором входящий вебхук и различия (diff) спецификаций фиксируются как один причинно-следственный след. Для инцидента HM-2026-05-17-01 первая запись связывает incident_event.json, пользовательскую команду /sdd:specify и созданный файл specs/high_memory_usage/specify.md. Если один из элементов отсутствует, конвейер уже потерял доказуемость. Минимальный фрагмент журнала: webhook_received -> incident_event_normalized -> /sdd:specify -> spec_diff_created; каждое следующее различие ссылается на тот же incident_id. /sdd:specify — проектное расширение; оформите его как пользовательскую команду в .qwen/commands/sdd/specify.md или замените прямым qwen -p.

Нормализуйте оповещения Grafana и PagerDuty в единый incident-event. Иначе разные источники будут диктовать разные версии одной аварии. Grafana даёт метрики и окно наблюдения, например memory_percent=93 за 10m. PagerDuty добавляет приоритет, сервисную привязку и статус эскалации. Нормализатор сводит их к полям service, namespace, pod, severity, window_minutes, metric_context, source_refs. После этого шаг specify описывает только WHY и WHAT: почему нужно вмешаться и какой результат считается успешным. Он не выбирает библиотеку, SDK или конкретную ручку API.

Что это значит на практике. Сравним два варианта specify для одного инцидента:

Плохо:

> Specify для high_memory_usage: Перезапустить под через kubectl delete pod ...

Проблема: specify сразу выбирает команду реализации и блокирует Plan.

Хорошо:

> Specify для high_memory_usage: Удержать memory_percent < 80% в течение 5 минут после действия. Pre-approved actions: restart_pod, scale_up_replicas_one. Аудит-трейс обязателен.

SDD-разделение фаз защищает конвейер от преждевременной реализации. Каждая фаза отвечает за своё:

• Specify фиксирует пользовательскую историю, критерии успеха, функциональные и нефункциональные ограничения;
• Plan выбирает стратегию;
• Tasks превращает её в исполнимые шаги;
• Implement применяет изменения через контролируемый механизм.

Такая структура соответствует практической рамке фаз Specify → Plan → Tasks → Implement из GitHub Spec Kit (см. также GitHub Spec Kit Quickstart). В production это важно потому, что модель не получает права «сразу лечить» инцидент, пока не доказаны причина, границы вмешательства и способ проверки результата.

Не расширяйте ядро главы до всего production-оркестратора. В первом проходе здесь проверяется только цепочка вебхук -> нормализация -> readiness -> dry-run. Остальные механизмы из предыдущих глав выступают как контрольные точки:

• Верификатор из частей 4 и 8 нужен, если dry-run вызывает спорный контрпример.
• Ярусные бюджеты из части 9 нужны, если frontier-reviewer начинает обслуживать не только high-risk ветки.
• Anti-Goodhart из части 10 нужен, если memory падает ценой 5xx, latency или ручного аудита.

Если эти механизмы ещё не собраны, не пытайтесь моделировать их внутри главы 11. Запишите их как блокеры или ссылки на соответствующие главы, а минимальный прогон завершите readiness-вердиктом и dry-run результата.

Для high_memory_usage начинайте план с минимального воздействия. Базовый /plan выбирает перезапуск конкретного pod-а с приоритетом радиуса последствий. Затем проверяет необходимость scale-up. И только после этого допускает расширение действия при сохранении пути отката.

Шаг tasks раскладывает это в операции: подтвердить stateless-характер workload-а, выполнить пробный прогон (dry-run) без реальных изменений, удалить только целевой pod, наблюдать RSS, CPU, 5xx; при отсутствии улучшения за заданное окно — активировать откат и создать human_review.

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

• memory удерживается ниже порога в двух последовательных окнах;
• 5xx не растёт;
• задержка (latency) не деградирует;
• откат описан и исполним.

После успешной проверки в GitOps попадают шесть базовых артефактов: спецификация, план, задачи, различия (diff), журнал решений и 25-балльный отчёт. Обновление Конституции добавляется при необходимости. Без этого инцидент может быть технически смягчён, но не считается управляемо закрытым.

Полный трек: 25-балльная модель готовности

При первом проходе достаточно понимать два факта: readiness_pass.json проходит, а audit/stateful-фикстуры блокируются. Полная рубрика ниже нужна, когда вы переносите этот шлюз в реальный production-процесс и должны объяснить, почему порог выбран именно так.

Модель оценивает пять категорий по шкале 0–5 и даёт итоговую сумму. Баллы выставляются по артефактам, а не по впечатлению. Если критерий нельзя подтвердить файлом, логом или схемой, ставится меньшая оценка. Ниже — рубрики по каждой категории.

Порог 23/25 — компромисс «строго, но не парализующе» для учебной модели AgentClinic-production: до двух «устранимых» претензий по «4» в разных категориях (4+4+5+5+5 = 23) либо одна «4» при остальных «5» (24/25). «3» или ниже хотя бы в одной категории сразу опускает сумму до 22 или меньше и снимает auto-допуск. Ниже 23: 20–22/25 переводит конвейер в полуручной режим с подтверждением человека после каждого implement-шага. Выше — порог 24/25 — сваливает auto в полуручной от любой мелкой претензии, и команда начинает игнорировать модель. Калибруйте под риск-профиль: платежи и здравоохранение — auto ≥24/25; внутренние инструменты допускают 21–22/25, но только как полуручной или canary, не как production-ready авто-ремедиацию.

Spec — полнота WHY/WHAT/constraints

| 0 | Спецификации нет |

Implementation — идемпотентность и контролируемые изменения

Verification — Given/When/Then, схемы, стресс, мониторинг

| 1 | Валидация сводится к проверке кода возврата (exit code) или одному скриншоту | | 0 | validation.md отсутствует или не запускается |

Process — трассировка «вебхук → CLI → различие → реплей»

Security — ограждения, аварийный стоп, откат, эскалация

| 2 | Есть только откат, без ограждений и без эскалации | | 1 | Заявлен «ручной откат», но не описан исполняемый путь | | 0 | Шлюз безопасности не определён, действия идут без ограничений |

Как считается и что блокирует слияние

Сумма баллов даёт итог от 0 до 25. Проходной порог для auto-допуска — 23/25: ниже этой границы конвейер не получает production-ready статус, даже если три категории на максимуме. Запрещён нулевой балл по Security при любой сумме. 0 в этой колонке означает отсутствие защитного контура и блокирует даже полуручной режим до появления минимального отката, ограждений и эскалации.

Блокирующие условия не зависят от суммы. Каждый из этих случаев блокирует слияние отдельно:

• проваленная validation (Verification ≤ 2);
• отсутствие отката (Security ≤ 2);
• неопределённый радиус последствий (Implementation ≤ 2 без явного поля).

При итоге 20–22 конвейер допускается только в полуручном режиме и только если нет блокирующих условий выше: остановка после каждого implement-шага, явное подтверждение человеком, обязательное обновление спецификации и повторная оценка до возврата в auto-контур.

Чек-лист перед production-переключением (cutover)

Используется при переносе шлюза в реальный процесс — каждый пункт привязан к рубрике, в которой возможно скрытое падение балла:

• [ ] Spec содержит WHY/WHAT/constraints и привязана к incident_id; у каждой задачи указан implements: на REQ-идентификатор.
• [ ] Пробный прогон логируется до реальных изменений; радиус последствий зафиксирован на уровне pod или deployment, не словами.
• [ ] JSON Schema валидирует incident_event и итоговый validation_report; Given/When/Then покрывают happy и negative path.
• [ ] Условие отката записано до исполнения и проверено на стенде; аварийный стоп доступен оператору без захода в кластер.
• [ ] След webhook → CLI → diff → commit → validate воспроизводится по incident_id; ручное подтверждение запускается автоматически при повторном провале или расширении радиуса последствий.

Пример заполненной рубрики для high_memory_usage

| Implementation | 4 | Задачи идемпотентны, пробный прогон есть, но ветка scale-up не имеет отдельного шага пробного прогона | | Verification | 5 | Given/When/Then, JSON Schema на incident_event и validation_report, стресс-спецификация на скрытую утечку, пост-метрики в двух окнах | | Process | 5 | incident_id=HM-2026-05-17-01 связывает вебхук, /sdd:specify, различие, commit и реплей | | Security | 4 | Ограждения на stateful workloads, откат и аварийный стоп есть, эскалация описана текстом без формального триггера | | Итог | 23/25 | Production-ready по порогу, но ветка scale-up остаётся полуручной до отдельного пробного прогона |

Полный трек: калибровка порогов

Таблица «Низкий / По умолчанию / Высокий» для порога readiness, упражнение с переопределением THRESHOLD и сигналы для пересмотра — в Приложении D, раздел D.5. На первом проходе минимум главы уже доказан, если readiness_pass.json проходит, audit/stateful-фикстуры блокируются, а delete_namespace не попадает в список заранее согласованных действий.

Примеры и применение

Практический входной лог для Qwen Code может начинаться так: POST /hooks/grafana сообщает memory_percent=93, pod=api-7b4, namespace=appointments-api, window=10m. Затем POST /hooks/pagerduty подтверждает severity=critical и связывает событие с сервисом appointments-api. Нормализатор создаёт incident_event с incident_id=HM-2026-05-17-01, удаляет чувствительные поля, прикладывает ссылки на источники и запускает пользовательскую команду /sdd:specify --event incident_event.json --preset high_memory_usage или эквивалентную подсказку qwen -p — оба варианта относятся к рекомендуемой рамке из шапки главы и реализуются проектными командами вокруг Qwen Code.

Первое различие (diff) в specify.md фиксирует три блока: WHAT (снизить RSS ниже 80% за 10 минут), WHY (предотвратить OOMKill и рост задержек), constraints (не трогать stateful workloads, не менять HPA, иметь откат через 6 минут без улучшения). На /plan система сравнивает две стратегии: (A) перезапуск целевого pod-а и наблюдение; (B) перезапуск плюс временный scale-up до четырёх реплик. Верификатор прогоняет Given/When/Then: given pod stateless и memory выше 90% в течение 10 минут; when выполняется перезапуск только целевого pod-а; then memory должна стать ниже 80%, а 5xx не должен превысить допустимый порог. Если стресс-спецификация показывает, что scale-up требует изменения политики раскатки или скрывает утечку памяти ростом числа реплик, вариант B остаётся резервной веткой с ручным подтверждением, а не автоматическим действием.

На шаге implement сначала выполняется пробный прогон. Затем commit проходит через GitOps и синхронизируется в ArgoCD только при зелёном статусе валидатора. Исполнитель не закрывает инцидент PagerDuty сразу после перезапуска. Он ждёт два окна мониторинга, сверяет validation.md, проверяет шлюз безопасности и добавляет в комментарий ссылки на spec, tasks, commit и результат валидации. Если через 6 минут memory не снижается или 5xx растёт, включается путь отката, создаётся human_review, а оценка готовности пересчитывается с учётом проваленного критерия verification.

Итог

Готовность production-конвейера фиксируется 25-балльной моделью: пять категорий (Spec, Implementation, Verification, Process, Security) с равным весом в 5 баллов повторяют этапы SDD-цикла. Равный вес — это принцип: ни одна категория не компенсирует пробел в другой, поэтому порог 23 допускает не более двух частичных пробелов суммарно. Production-ready — не ниже 23/25 при отсутствии критических нарушений validation и шлюза безопасности. Падение ниже порога переводит авто-ремедиацию в полуручной режим до исправления спецификации, политики или пути исполнения. Полностью автоматизированная ремедиация остаётся фронтир-сценарием из шапки главы: допускайте её только после накопления реплей-доказательств и операторского пробного прогона. Такой контур превращает каждый будущий инцидент в проверяемое улучшение системы.

Артефакты и критерии готовности

| Локальный прогон readiness-шлюза | readiness_pass.json проходит; audit/stateful-фикстуры блокируются с конкретной причиной | | dry_run.py на разрешённом и запрещённом действии | restart_pod PASS, delete_namespace BLOCK | | Запись в capstone/readiness.md | score, блокирующие условия, одна реально запущенная команда |

Полный трек добавляет specs/high_memory_usage/specify.md, plan.md, tasks.md и validation.md, GitOps-различие или commit, связанный с incident_id, журнал решений webhook → CLI → diff → commit → validate и заполненную 25-балльную таблицу готовности с доказательствами. Считайте его готовым, если plan и tasks имеют радиус последствий, пробный прогон, условие отката и триггер ручного подтверждения; validation проверяет два окна метрик, 5xx, задержку и шлюз безопасности; пользовательские команды либо оформлены как проектные команды, либо заменены подсказками qwen -p или проектными скриптами; итог готовности не ниже 23/25 без блокирующих условий по откату, verification или радиусу последствий.

Практика

1. cd book2/examples/real-api && python3 scripts/normalize_webhook.py --grafana fixtures/webhook_grafana.json --pagerduty fixtures/webhook_pagerduty.json --expected fixtures/incident_event.expected.json — *ожидание: код 0, нормализованный incident_event совпадает с эталоном поле-в-поле.*
2. Прогоните четыре проверки по отдельности (каждая возвращает свой код, поэтому && между ними не подходит):

   python3 scripts/check_readiness.py --readiness fixtures/readiness_pass.json
   python3 scripts/check_readiness.py --readiness fixtures/readiness_block_audit.json
   python3 scripts/dry_run.py --spec specs/high_memory_usage/specify.md --action restart_pod
   python3 scripts/dry_run.py --spec specs/high_memory_usage/specify.md --action delete_namespace

*Ожидание: readiness_pass → код 0, PASS incident=HM-… score=24/25; readiness_block_audit → код 1, BLOCK … score=22/25 с причинами «score 22/25 ниже порога 23» и «audit_trace_coverage=0.7 < 1.0 — обязательно полное покрытие»; restart_pod PASS, delete_namespace BLOCK.*

1. Оцените свой кейс по 25-балльной модели и заполните таблицу ниже. Для каждой категории укажите балл, артефакт-доказательство и причину снижения, если балл меньше 5. Подсчитайте итог, проверьте блокирующие условия и сформулируйте, что нужно изменить, чтобы конвейер прошёл порог 23/25. *Ожидание: в каждой строке таблицы заполнены все три поля; «Артефакт-доказательство» указывает конкретный файл или прогон, не общую формулировку; итоговая клетка содержит число вида N/25 и список блокирующих условий, либо явное «нет блокеров».*

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

1. Почему specify не должен выбирать конкретную команду ремедиации?
2. Какие условия делают авто-ремедиацию недопустимой?
3. Что блокирует допуск, если readiness ниже 23/25?

1. Вебхук о high_memory_usage пришёл в нерабочее время, автоматическая ремедиация готова перезапустить pod. Модель готовности даёт 22/25 (минус 3 за неполный аудит). Что вы сделаете — перезапустить, ждать утра или вызвать дежурного?