Учебный гайд: Прикладная часть 0. Лаборатория AgentClinic-production

Урок 3 из 5 в модуле «Прикладная часть 0. Лаборатория AgentClinic-production»

Вы просматриваете урок без входа. Войдите, чтобы сохранять прогресс и проходить тесты.

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

Уровень сложности: Средний

Расчётное время изучения: 4-6 часов (теория + практика первого прохода)

Предварительные требования: Завершённый первый том AgentClinic (маршруты, SQLite, спецификации фич, проверки и ревью)

Базовое владение TypeScript и Python

Понимание концепций CI/CD и production-эксплуатации на уровне чтения

Умение работать с командной строкой и Git

Знакомство с концепциями алертинга, метрик и инцидент-менеджмента

Цели обучения: Объяснить различие между учебной production-моделью и реальной инфраструктурой, корректно интерпретируя роли Kubernetes, Grafana, PagerDuty как сценарные обозначения

Классифицировать три типа командных блоков ([runnable], [project script], [conceptual interface]) и применять правило запуска только [runnable]-команд при формировании зачётного пакета

Сформировать сквозной зачётный кейс high_memory_usage в appointments-api, выбрав основной инцидент и отобрав принципы из дополнительных кейсов для переноса в capstone/

Создать структуру capstone/ и заполнить первые артефакты (genealogy.md, спецификационную пару, constitution.md) по минимальному маршруту глав 1–3

Выполнить smoke-прогон bash book2/examples/smoke_all.sh и верифицировать работоспособность учебных имитаторов перед прохождением глав 4–11

Обзор: Прикладная часть 0 — методическая вводная лаборатория второго тома AgentClinic. Она не вводит новую технику, а устанавливает карту чтения: как превратить набор продвинутых глав в единый учебный production-контур вокруг знакомого проекта AgentClinic. Ключевой инсайт: второй том использует тот же стек (TypeScript, Hono, SQLite), но добавляет второй слой — маленькие Python-скрипты в book2/examples/ как учебные имитаторы production-механизмов. Эти скрипты не заменяют продуктовый стек; они дают возможность запустить минимальный пример за секунды без поднятия инфраструктуры. Часть 0 вводит правило «один проект, один основной контур, один растущий пакет доказательств», определяет сквозной кейс high_memory_usage, структуру capstone/ и минимальный маршрут для ограниченного времени. Успешное прохождение этой части измеряется контрольным фактом: выбран основной incident-case, создан пустой capstone/, runnable-примеры проверены или отложены с явной причиной.

Ключевые концепции: Agentclinic-production: Учебная production-модель вокруг знакомого проекта AgentClinic. Не требует реального Kubernetes, Grafana, PagerDuty или GitOps — эти термины обозначают роли в сценариях: откуда пришёл сигнал, какое действие опасно, где нужен откат, какой артефакт доказывает решение. Модель позволяет изучить production-практики без затрат на инфраструктуру.

High memory usage: Основной зачётный кейс для сквозного прохождения. Инцидент в сервисе appointments-api, удобный для доведения до полного пакета доказательств: нормализация вебхука, readiness-шлюз, пробный прогон, итоговый пакет. Другие кейсы (autoscale_200pct, cdn_error_budget_burn, node_not_ready и др.) служат лабораторными окнами для отдельных механизмов, но их принципы переносятся в основной кейс, а не смешиваются как равноправные.

Capstone/: Итоговый пакет доказательств по одному инциденту. Структура повторяет логику первого тома: намерение и границы → план и факты → ревью и итог. Каждая глава открывает конкретный файл. Ключевое правило: один инцидент в пакете, решение понятно без истории чата.

Три типа командных блоков: [runnable] — запускайте как написано, примеры в book2/examples/; [project script] — контракт будущего скрипта в вашем проекте, не обязан существовать в репозитории; [conceptual interface] — форма будущей интеграции, не запускается при учебном прохождении. Зачётный пакет ссылается только на запущенные факты или ручные артефакты, читаемые без контекста чата.

Учебные имитаторы (python stdlib): Второй слой кода второго тома — маленькие скрипты на Python стандартной библиотеки. Не смена стека продукта, а самый дёшевый способ запустить пример без сборки: stress-mutator, дуэль, Spec CI, бюджет токенов, readiness-калькулятор. В реальном проекте такие проверки стали бы pre-commit, GitHub Actions, MCP-инструментом или сервисом на продуктовом стеке.

Перенос принципов vs. перенос кейсов: Из локального кейса главы в high_memory_usage переносится не сам кейс, а проверяемый принцип. Например: из autoscale_200pct — guard-правило «не расширять радиус последствий сверх квоты»; из cdn_error_budget_burn — anti-Goodhart-инвариант «MTTR нельзя улучшать ценой silent P0»; из node_not_ready — провенанс требования и правило «не закрывать без доказательств восстановления».

Genealogy.md: Артефакт главы 1. Происхождение требования и уровень уверенности. Минимальный вывод: одно требование с двумя источниками.

Poisoned-spec.md / fixed-spec.md: Артефакт главы 2. Пара спецификаций «с дефектом / исправленная», демонстрирующая один класс ошибки.

Constitution.md: Артефакт главы 3. Два неизменяемых правила и одно правило со сроком действия.

Validation.md: Артефакт глав 4 и 7. Команды, ручные факты и блокеры. Содержит happy path, negative path и контрпример.

Judgment.md: Артефакт главы 8. Вердикт по спорному изменению со ссылкой на доказательство.

Budget-note.md: Артефакт главы 9. Риск исчерпания бюджета моделей и порог переключения на дешёвый ярус.

Goodhart-note.md: Артефакт главы 10. Целевая метрика и парная защитная метрика против Гудхартова перекоса.

Readiness.md: Артефакт главы 11. Вердикт допуска к production и dry-run разрешённого действия.

Antipattern-audit.md: Артефакт главы 12. Три пункта blocker / owner / next_check.

Минимальный маршрут: Сокращённый путь для ограниченного времени: часть 0 + README runnable-примера → главы 1–3 (три ручных артефакта) → главы 4–11 (только [runnable]-команды, принципы других кейсов переносятся как строки) → глава 12 (диагностический чек-лист) → глава 13 (сборка capstone/ с пятью PASS-строками рубрики). Не требует внешних оркестраторов, MCP-серверов, Kubernetes-интеграций.

Полный трек: Расширенное прохождение с реальными интеграциями. Файлы вроде scorebook, metric_network, decision_hash, precedents.md и CI-отчётов добавляются только если реально созданы или есть runnable-аналог, подтверждающий принцип.

Практические упражнения: Название: Классификация командных блоков

Проблема: Вам предложены три фрагмента из разных глав второго тома:

Фрагмент A: python3 book2/examples/stress-mutator/run.py --spec capstone/fixed-spec.md Фрагмент B: [project script] deploy-gate --readiness capstone/readiness.md --dry-run Фрагмент C: [conceptual interface] Интеграция с PagerDuty Oncall API для автоматического назначения инженера

Определите тип каждого фрагмента. Укажите, какой из них можно запустить сейчас, какой — реализовать в своём проекте позже, какой — не запускать при учебном прохождении. Объясните, может ли зачётный пакет ссылаться на каждый из них.

Решение: 1. Фрагмент A — [runnable]. Можно запустить сейчас, если файл capstone/fixed-spec.md существует. Зачётный пакет может ссылаться на результат запуска как на проверяемый факт.

Фрагмент B — [project script]. Это контракт будущего скрипта в вашем проекте. Не обязан существовать в репозитории учебника. Зачётный пакет может ссылаться только если вы реализовали аналог и запустили, или если описали ручной артефакт, читаемый без контекста чата.
Фрагмент C — [conceptual interface]. Форма будущей интеграции, не запускается при учебном прохождении. В зачётный пакет не попадает как факт при первом проходе; если принцип важен, записывается одной строкой-инвариантом в соответствующий файл capstone/.

Сложность: beginner

Название: Формирование карты переноса для autoscale_200pct

Проблема: Вы проходите главу с локальным кейсом autoscale_200pct. По правилам части 0, вы не должны смешивать этот кейс с основным high_memory_usage в одном capstone/. Прочитав главу, вы видите: автомасштабирование удвоило ресурсы при алерте, но это расширило радиус последствий (затронуты соседние сервисы), превысив квоту. Какой принцип перенести в основной кейс high_memory_usage и в какой файл capstone/ его записать?

Решение: 1. Локальный кейс autoscale_200pct остаётся в главе как лабораторное окно.

Проверяемый принцип для переноса: guard-правило «не расширять радиус последствий сверх квоты».
Это правило относится к контрпримеру или ограничителю, поэтому записывается в validation.md (главы 4 и 7) как negative path или в constitution.md (глава 3) как правило со сроком действия, если оно регулярно проверяется.
Формулировка в capstone/: один конкретный пункт, например: «Guard: при алерте high_memory_usage масштабирование ограничено квотой X; контрпример из autoscale_200pct показывает, что превышение квоты приводит к каскадному отказу».
Ссылка на локальный runnable-пример допустима, но решение в README.md объясняет high_memory_usage.

Сложность: intermediate

Название: Smoke-прогон и диагностика отказа

Проблема: Вы выполняете bash book2/examples/smoke_all.sh перед главой 5. Скрипт падает на блоке stress-mutator с ошибкой ModuleNotFoundError: No module named 'json'. Используя знания из части 0, определите вероятную причину и действия. Можно ли продолжить учебный маршрут без исправления?

Решение: 1. json — часть Python stdlib, ошибка ModuleNotFoundError на нём невозможна в нормальной установке. Вероятная причина: скрипт запущен в изолированной среде (custom Python build, контейнер без stdlib, или переопределён PYTHONPATH).

Проверка: python3 -c "import json; print(json.__file__)" — если падает, среда сломана.
Согласно части 0, все book2/examples/ используют Python stdlib и должны запускаться без зависимостей. Если json недоступен, это нарушение контракта среды, не учебного материала.
Действия: проверить which python3, использовать системный Python 3.8+, убрать виртуальное окружение с кастомной конфигурацией.
Можно ли продолжить без исправления: нет, smoke-прогон — контрольный факт перед главами 4–11. Однако можно выбрать минимальный вариант: открыть examples/README.md, запустить только блок текущей главы вручную, отложить остальное с явной причиной «окружение нестандартное, проверено вручную для главы 5».

Сложность: intermediate

Название: Проектирование структуры capstone/ после главы 3

Проблема: Вы прошли главы 1–3 по минимальному маршруту. У вас есть: genealogy.md с требованием «readiness-шлюз должен проверять memory_before_allow» (источники: инцидент high_memory_usage и SRE-руководство команды), пара poisoned-spec.md/fixed-spec.md показывающая дефект «алерт не различает memory leak и legitimate spike», и constitution.md с двумя неизменяемыми правилами («никакие действия без dry-run» и «все P0 требуют аудита») и одним правилом со сроком «readiness-проверка действительна 24 часа». Проверьте, соответствует ли это минимальному выводу части 0. Чего не хватает для перехода к главе 4?

Решение: 1. Проверка по таблице минимальных выводов:

После главы 1: одно требование с двумя источниками в genealogy.md — ✅ (требование + инцидент + SLE-руководство).
После главы 2: пара спецификаций с видимым классом ошибки — ✅ (poisoned/fixed показывают дефект классификации алерта).
После главы 3: constitution.md с двумя неизменяемыми и одним со сроком — ✅.

Для перехода к главе 4 нужен минимальный контрпример к одному правилу или формулировка следующего ограничителя. Это вывод главы 4, не главы 3 — поэтому к переходу к главе 4 готовы.
Однако полезно предварительно выбрать, какое правило из constitution.md получит контрпример в главе 4. Рекомендация: правило «readiness-проверка 24 часа» — легко построить контрпример с алертом, пришедшим через 25 часов после проверки.
Проверка структуры capstone/: файлы не смешивают инциденты, каждый читаем без истории чата — ✅.
Не хватает только запуска smoke_all.sh или его осознанной отсрочки с причиной.

Сложность: intermediate

Название: Различение минимального маршрута и полного трека

Проблема: В главе 7 вы встречаете термины scorebook, Spec CI pipeline, decision_hash. Согласно части 0, как определить, нужны ли эти термины для зачётного пакета? Ваш текущий минимальный вывод — строка Spec CI: что покрыто, что блокируется. Сформулируйте, что записать в capstone/, если scorebook и decision_hash не созданы вами, но концептуально описаны в главе.

Решение: 1. Правило части 0: если термин не влияет на текущий вывод главы, не останавливайтесь на нём при первом чтении.

Минимальный вывод главы 7: строка Spec CI — что покрыто, что блокируется. Это идёт в validation.md.
scorebook и decision_hash — элементы полного трека. Они нужны, только если вы реально создали их или можете объяснить runnable-аналог, подтверждающий тот же принцип.
Действие: записать в validation.md одной строкой принцип, который scorebook и decision_hash защищают, без упоминания самих терминов. Например: «Покрытие: спецификация проходит 5/5 проверок Spec CI. Блокер: если mutator находит необработанный payload, merge запрещён. Проверяемый факт: запуск python3 examples/spec-ci/run.py на fixed-spec.md даёт PASS».
Если позже в полном треке реализуете scorebook — добавите файл. При первом проходе это избыточно.

Сложность: advanced

Кейсы: Название: Миграция учебной модели в реальную SRE-практику: от AgentClinic-production до production-ready пайплайна

Сценарий: Команда из 8 человек завершила первый и второй томы AgentClinic по минимальному маршруту. Их capstone/ содержал полный пакет по high_memory_usage: genealogy.md с двумя источниками, спецификационную пару с дефектом классификации алерта, constitution.md с guard-правилами, validation.md с результатами stress-mutator и Spec CI, readiness.md с dry-run вердиктом. Команда получила задачу внедрить аналогичный процесс для реального сервиса записи к врачу в клинической сети.

Задача: Три ключевых проблемы при трансляции учебной модели: (1) реальный сервис использовал Go и PostgreSQL, не TypeScript/SQLite — возник соблазн отбросить учебный стек как нерелевантный; (2) инфраструктура требовала настоящий PagerDuty, DataDog и GitHub Actions, а не Python-имитаторы; (3) менеджмент требовал «полный трек» сразу, включая scorebook и metric_network, что увеличило срок с 2 недель до 3 месяцев и привело к параличу проекта.

Решение: Команда применила принципы части 0: (1) разделила продуктовый стек (Go/PostgreSQL) от слоя проверок — Python-имитаторы заменили на GitHub Actions и pre-commit хуки на Go, но структура артефактов (genealogy.md, constitution.md и др.) осталась; (2) термины PagerDuty/DataDog использовали как сценарные роли, реализуя интеграцию постепенно: сначала webhook-имитатор в Slack, затем настоящий PagerDuty; (3) настояла на минимальном маршруте: первые 2 недели дали работающий пайплайн с 5 файлами в capstone/, полный трек добавлялся итерациями по принципу «один новый проверяемый вывод за спринт».

Результат: Минимальный пайплайн заработал за 10 дней. Первый реальный инцидент (memory pressure на сервисе записи) был обработан по capstone/ за 45 минут вместо прежних 4 часов. Guard-правило «не расширять радиус последствий» предотвратило каскадное отключение платёжного шлюза. Полный трек (scorebook, decision_hash) внедрялся за 6 месяцев итеративно, без паралича. Учебные Python-скрипты остались как прототипы для локальной отладки новых guard-правил.

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

Минимальный маршрут — не упрощение для слабых, а стратегия быстрой валидации перед масштабированием

Сценарные роли (PagerDuty, Kubernetes) позволяют проектировать процесс до готовности инфраструктуры

Полный трек без работающего минимального маршрута — риск архитектурного паралича

Python-имитаторы учебника имеют долгую жизнь как инструменты прототипирования guard-правил

Связанные концепции: AgentClinic-production

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

Три типа командных блоков

Перенос принципов vs. перенос кейсов

capstone/

Название: Ошибка смешения кейсов: когда autoscale_200pct поглотил high_memory_usage

Сценарий: Инженер проходил второй том и решил «сделать всё правильно» — включить в capstone/ оба инцидента как равноправные кейсы. README.md описывал high_memory_usage, но файлы validation.md и readiness.md содержали решения для autoscale_200pct, а budget-note.md — для cdn_error_budget_burn.

Задача: При ревью другим инженером пакет оказался нечитаемым: guard-правила из autoscale_200pct противоречили readiness-шлюзу для high_memory_usage, judgment.md ссылался на спорное изменение без контекста, а README.md не объяснял, почему в пакете три инцидента. Ревьюер потратил 2 часа на выяснение контекста и отклонил пакет.

Решение: Переработка по правилам части 0: выбран один основной кейс high_memory_usage; принципы из других кейсов выделены как однострочные инварианты в соответствующих файлах. Например, вместо раздела про autoscale_200pct — строка в validation.md: «Guard-правило: масштабирование ограничено квотой (контрпример из autoscale_200pct)».

Результат: Переработанный пакет прошёл ревью за 15 минут. Инженер освоил ключевой навык части 0: отделение принципа от кейса. В последующих проектах он применял это для консолидации post-mortem из десятков инцидентов в единый набор guard-правил.

Извлечённые уроки: Смешение кейсов в одном capstone/ создаёт нечитаемость и противоречия

Принцип «один инцидент — один пакет» не ограничивает обучение, а фокусирует его

Ревью «другим человеком» — критерий качества, а не формальность; пакет должен быть понятен без истории чата

Контрпример из другого кейса усиливает основной, если записан как инвариант, а не как отдельная история

Связанные концепции: high_memory_usage

Перенос принципов vs. перенос кейсов

capstone/

validation.md

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

Физически создайте mkdir -p capstone сразу после прочтения. Пустой каталог — якорь для принятия решений: «этот файл сюда или это полный трек?»

Распечатайте или держите открытой таблицу «После главы → Минимальный вывод». Используйте её как чек-лист: если после главы файл не соответствует описанию, переходите к следующей главе только после доработки.

Для визуального стиля: рисуйте на бумаге стрелки между файлами capstone/. genealogy.md → poisoned-spec.md/fixed-spec.md → constitution.md → ... Это помогает увидеть, что каждый файл — не изолированный документ, а звено цепи доказательств.

Аудиальным ученикам: прочитайте контрольные вопросы вслух и запишите ответы голосом перед проверкой. Если ответ занимает больше 30 секунд — вероятно, понимание недостаточно глубокое.

Кинестетикам: выполните smoke-прогон физически, не читая скрипт. Затем откройте smoke_all.sh в редакторе и проследите, какой блок к какой главе относится. Ручное сопоставление «код → глава → вывод» укрепляет структуру.

При работе с дополнительными кейсами (autoscale_200pct, cdn_error_budget_burn и др.) используйте технику «один принцип — одна строка». Откройте файл, куда идёт перенос, и запишите принцип до закрытия вкладки с главой. Иначе контекст уйдёт.

Проводите саморевью: закройте все материалы и попытайтесь объяснить «почему нельзя смешивать кейсы» своими словами 8-летнему ребёнку или коллеге из другой команды. Если требуется упомянуть Kubernetes или PagerDuty — вы ещё в ловушке «реальной инфраструктуры», выберитесь в «сценарные роли».

Для глав 4–11: запускайте runnable-примеры с флагом --help или изучайте argparse-секцию перед исполнением. Понимание параметров имитатора важнее быстрого результата — вы должны уметь объяснить, что именно проверяет скрипт, а не только что он выдал PASS.

Финальный тест перед главой 1: назовите основной кейс, покажите пустой capstone/, продемонстрируйте результат smoke_all.sh или его осознанную отсрочку. Если любой пункт невозможен — вернитесь к части 0.

Дополнительные ресурсы: Examples/templates/capstone-dossier.md: Минимальная форма ответа на вопрос «какой след должен остаться после первого прохода?». Не шаблон для бездумного копирования, а ориентир для самопроверки структуры пакета

Examples/readme.md: Описание всех runnable-примеров по блокам глав. Используйте для выборочного smoke-прогона, если полный smoke_all.sh занимает много времени

Book2/examples/smoke all.sh: Скрипт полного smoke-прогона. Запускается на временной копии, не оставляет артефактов в рабочем дереве

Первый том agentclinic (маршруты, sqlite, спецификации фич): Фундамент, на котором строится второй том. Убедитесь, что genealogy.md и спецификационные пары из первого тома понятны

Контрольные вопросы части 0 (внутри документа): Четыре вопроса для самопроверки перед переходом к главе 1. Используйте как flashcards

Словарь терминов глав 4–13: Не учите заранее по таблице части 0 — термины вводятся в своих главах. Но держите под рукой для быстрой проверки, когда встречается незнакомое слово

Резюме: Прикладная часть 0 — фундаментальная методическая лаборатория, определяющая, как читать второй том AgentClinic как единый production-контур, а не как набор изолированных продвинутых техник. Ключевые принципы: (1) учебная модель AgentClinic-production использует сценарные роли вместо реальной инфраструктуры; (2) Python-скрипты в book2/examples/ — имитаторы для локального запуска, не смена продуктового стека; (3) один сквозной кейс high_memory_usage, остальные — лабораторные окна для переноса принципов; (4) три типа командных блоков с чётким правилом зачётности; (5) структура capstone/ как растущий пакет доказательств, понятный без истории чата; (6) минимальный маршрут против полного трека — быстрая валидация перед масштабированием. Успешное прохождение измеряется контрольным фактом: выбран кейс, создан capstone/, runnable-примеры проверены. Всё последующее строится на этой базе.