Прикладная часть 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/ только проверяемый вывод: какой дефект, контрпример, бюджетный риск или инвариант нужно перенести в основной кейс.

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

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

В первом томе 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.

1. В главах 4–11 запускайте только [runnable]-команды из examples/; результаты других кейсов переносите в capstone/ как принцип, а не как новый домен.
2. В главе 12 проверьте пакет по диагностическому чек-листу.
3. В главе 13 соберите маленький capstone/ по одному инциденту.

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

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

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

| 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 book2/examples/smoke_all.sh

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

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

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

mkdir -p capstone

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

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-аналог подтверждает тот же принцип.

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

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

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

После этой главы выбран один основной 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/ должен быть понятен без истории чата?