# Прикладная часть 0. Лаборатория AgentClinic-production

**Статус: Стандарт для учебного маршрута.** Эта часть не вводит новую технику. Она объясняет, как читать второй том как одну лабораторную ветку после первого тома.

Первый том строит маленький AgentClinic: маршруты, SQLite, спецификации фич, проверки и ревью. Во втором томе тот же проект используется как учебная production-модель. Мы не требуем настоящий Kubernetes, Grafana, PagerDuty или GitOps. Эти слова обозначают роли в сценариях: откуда пришёл сигнал, какое действие может быть опасным, где нужен откат и какой артефакт доказывает решение.

Если читать главы как набор независимых продвинутых приёмов, том быстро станет тяжёлым. Читайте его иначе: один проект, один основной production-контур, один растущий пакет доказательств. Для зачёта по умолчанию используйте `high_memory_usage`; остальные инциденты нужны как маленькие лабораторные окна для отдельных механизмов.

Практическое правило первого прохода: `capstone/README.md` должен отвечать про один incident-case. Локальный пример другой главы может использовать другой инцидент, но в зачётный пакет переносится только проверяемый принцип. Например, из `autoscale_200pct` переносится не второй кейс, а защитное правило (`guard`) «не расширять радиус последствий сверх квоты». Из `cdn_error_budget_burn` переносится не новый сервис, а anti-Goodhart-инвариант «MTTR нельзя улучшать ценой silent P0».

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

Часть 0 — методическая, без учебного кейса. Здесь нет шагов и контрольного факта; задача — задать карту тома и согласовать стек исполнения. Со следующей главы стандартный блок «Перед чтением» возвращается и работает как контракт между главой и зачётом.

## Цель

Перед главой 1 нужно понять четыре вещи:

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

## Сквозной кейс

Базовый сценарий называется AgentClinic-production. Это тот же AgentClinic, но теперь вокруг него есть эксплуатационный контур. Основной зачётный кейс — `high_memory_usage` в `appointments-api`: его удобно довести до нормализации вебхука, readiness-шлюза, пробного прогона и итогового пакета доказательств. Дополнительные кейсы показывают отдельные механизмы, но не обязаны смешиваться в одном `capstone/`.

- сервис `appointments-api`;
- алерты `high_memory_usage`, `autoscale_200pct`, `appointment_latency` / `appointment_latency_spike`, `node_not_ready`, `cdn_error_budget_burn`;
- спецификации, которые должны переживать `/clear`, смену модели и ревью другим человеком;
- запрет на опасные действия без доказательств: расширение радиуса последствий, потеря аудита, скрытое закрытие P0, автоматический обход отката.

Учебная ветка не обязана содержать реальный production-код. Достаточно артефактов в `capstone/`, шаблонов из `examples/templates/` и runnable-примеров из `examples/`. Если глава использует не `high_memory_usage`, записывайте в `capstone/` только проверяемый вывод: какой дефект, контрпример, бюджетный риск или инвариант нужно перенести в основной кейс.

Короткая карта переноса:

| Локальный кейс главы | Что переносить в `high_memory_usage` |
|---|---|
| `node_not_ready` | провенанс требования и правило «не закрывать без доказательств восстановления» |
| `appointment_latency` / `appointment_latency_spike` | один класс дефекта спецификации или результат stress-mutator (различие: `appointment_latency` — общий класс инцидента «задержка маршрута `/agents`», `appointment_latency_spike` — конкретный учебный payload в `examples/stress-mutator/base/base_spec.json` для глав 2 и 5) |
| `autoscale_200pct` | контрпример к расширению радиуса последствий или бюджетный риск |
| `cdn_error_budget_burn` | пару KPI + guard-метрика против Гудхарта |

## Стек исполнения

В первом томе AgentClinic — это приложение на TypeScript, Hono, серверном JSX, SQLite и Vitest. Этот стек никуда не девается: в учебной модели AgentClinic-production он остаётся стеком самого продукта.

Во втором томе появляется второй слой кода — небольшие runnable-скрипты в `book2/examples/`. Они написаны на Python stdlib и нужны только для того, чтобы один человек на своей машине мог запустить минимальный пример главы за пару секунд без поднятия инфраструктуры. Это не смена стека продукта и не намёк, что production AgentClinic переписан на Python. Это учебные имитаторы: stress-mutator, дуэль, Spec CI, бюджет токенов, readiness-калькулятор. В реальном проекте такие проверки чаще оформляются как pre-commit, GitHub Actions, MCP-инструмент или сервис на своём стеке — Python тут лишь самый дешёвый язык для запуска без сборки.

Правило простое: всё, что встречается в `book2/examples/`, можно запустить как `python3 ...` без зависимостей. Всё, что в главе обозначено как `[project script]` или `[conceptual interface]`, — это форма будущего скрипта или интеграции в вашем проекте, не привязанная к Python.

## Минимальный маршрут

Если у вас мало времени, проходите второй том так:

1. Прочитайте эту часть и README выбранного runnable-примера.
2. В главах 1–3 заполните три ручных артефакта: `genealogy.md`, poisoned/fixed-пару и `constitution.md`.
3. В главах 4–11 запускайте только `[runnable]`-команды из `examples/`; результаты других кейсов переносите в `capstone/` как принцип, а не как новый домен.
4. В главе 12 проверьте пакет по диагностическому чек-листу.
5. В главе 13 соберите маленький `capstone/` по одному инциденту.

Минимальный маршрут не требует писать внешние оркестраторы, MCP-серверы, Kubernetes-интеграции или настоящие CI-шлюзы. Эти элементы относятся к полному треку.

Проверка маршрута простая: после каждой главы в `capstone/` должен появиться один новый проверяемый вывод. Не полный production-процесс, а маленькая запись, которую можно показать другому человеку.

> **Как читать таблицу.** Колонка «вывод» намеренно описана своими словами, без терминов глав 4–13. Если в правой колонке встретится слово, которого ещё нет в коротком словаре ниже, оно вводится в той главе, в которой нужно. Не пытайтесь выучить словарь тома по этой таблице.

| После главы | Минимальный вывод |
|---|---|
| 1 | одно требование с двумя источниками в `genealogy.md` |
| 2 | пара спецификаций «с дефектом / исправленная», на которой видно один класс ошибки |
| 3 | `constitution.md` с двумя неизменяемыми правилами и одним правилом со сроком действия |
| 4 | минимальный контрпример к одному правилу или формулировка следующего ограничителя |
| 5 | результат smoke-прогона стресс-мутатора или краткий отчёт о том, какие мутации валидатор поймал |
| 6 | один принятый и один отклонённый теневой кандидат (правила, которые могли бы войти в спецификацию) |
| 7 | строка Spec CI: что покрыто, что блокируется |
| 8 | один файл с вердиктом по спорному изменению и ссылкой на доказательство |
| 9 | риск исчерпания бюджета моделей и порог, по которому переключаемся на дешёвый ярус |
| 10 | целевая метрика и парная защитная метрика против её Гудхартова перекоса |
| 11 | вердикт допуска к production и dry-run разрешённого действия |
| 12 | три пункта `blocker / owner / next_check` |
| 13 | собранный `capstone/` по одному инциденту с пятью PASS-строками рубрики |

Если в главе встретились дополнительные термины, но этого вывода нет, сначала закройте вывод. Термины можно дочитать позже.

Для ориентира держите рядом заполненный пример [`examples/templates/capstone-dossier.md`](examples/templates/capstone-dossier.md). Это не шаблон для копирования бездумно, а минимальная форма ответа на вопрос: «какой след должен остаться после первого прохода?»

Минимальный словарь для первого прохода короткий:

- `capstone/` — итоговый пакет доказательств по одному инциденту;
- `genealogy.md` — происхождение требования и уровень уверенности;
- `validation.md` — команды, ручные факты и блокеры;
- `judgment.md` — вердикт по спорному изменению;
- `readiness.md` — почему действие допускается, блокируется или уходит в полуручной режим.

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

## Что реально запускать

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

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

Правило простое: зачётный пакет может ссылаться только на факты, которые вы действительно запускали, или на ручные артефакты, которые можно прочитать без истории чата.

## Первый smoke-прогон

Перед чтением глав 4–11 полезно убедиться, что локальные примеры работают:

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

Скрипт запускает smoke-прогон на временной копии `book2/examples`, поэтому не оставляет `out/` и `__pycache__` в рабочем дереве. Если времени мало, откройте [examples/README.md](examples/README.md) и выберите только блок той главы, которую проходите сейчас.

## Рабочий каталог для зачёта

Создайте каталог будущего пакета:

```bash
mkdir -p capstone
```

Пока оставьте его пустым. В главах 1–12 вы будете постепенно понимать, какие файлы туда попадут. Не смешивайте несколько инцидентов в одном пакете доказательств: один файл может ссылаться на runnable-аналог из другого кейса, но решение должно объяснять один основной инцидент.

```text
capstone/
  README.md
  genealogy.md
  poisoned-spec.md
  fixed-spec.md
  constitution.md
  validation.md
  judgment.md
  budget-note.md
  goodhart-note.md
  readiness.md
  antipattern-audit.md
```

Эта структура повторяет первый том: сначала намерение и границы, затем план и факты, затем ревью и итоговый пакет. Отличие второго тома только в том, что факты относятся не к одной фиче, а к production-допуску опасного действия.

При первом проходе не добавляйте в `capstone/` файлы из полного трека только потому, что они названы в главе. `scorebook`, `metric_network`, `decision_hash`, `precedents.md` и CI-отчёты нужны, когда вы реально их создали или можете объяснить, какой runnable-аналог подтверждает тот же принцип.

Чтобы было проще ориентироваться, какая глава открывает какой файл:

| Файл `capstone/` | Открывает |
|---|---|
| `genealogy.md` | глава 1 |
| `poisoned-spec.md` / `fixed-spec.md` | глава 2 |
| `constitution.md` | глава 3 |
| `validation.md` (happy + negative + контрпример) | главы 4 и 7 |
| `judgment.md` | глава 8 |
| `budget-note.md` | глава 9 |
| `goodhart-note.md` | глава 10 |
| `readiness.md` | глава 11 |
| `antipattern-audit.md` | глава 12 |
| `README.md` (итоговая сборка) | глава 13 |

Если по дороге в главе появляется четвёртый или пятый файл, не входящий в этот список, — это полный трек. Запишите принцип одной строкой и идите дальше.

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

После этой главы выбран один основной incident-case, создан пустой `capstone/`, а runnable-примеры проверены командой `bash book2/examples/smoke_all.sh` или отложены с явной причиной. Если вы не можете назвать основной кейс и первый файл, который попадёт в `capstone/`, к главе 1 переходить рано.

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

1. Почему AgentClinic-production — учебная модель, а не требование поднять настоящую инфраструктуру?
2. Чем `[runnable]` отличается от `[project script]`?
3. Почему в итоговом `capstone/` нельзя смешивать `high_memory_usage` и `autoscale_200pct` как два равноправных кейса?
4. Почему итоговый `capstone/` должен быть понятен без истории чата?