Материал: Прикладная часть 1. Восстановление спецификаций из legacy

Урок 1 из 5 в модуле «Прикладная часть 1. Восстановление спецификаций из legacy»

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

Источник

Прикладная часть 1. Восстановление спецификаций из legacy

Статус: Рекомендация. Сбор доказательств, нормализация временной шкалы и разделение требований и memory bank — устоявшиеся инженерные приёмы. Трёхсторонний файловый арбитраж в конце главы — фронтир.

Для учебного прохождения достаточно собрать один genealogy.md и отделить утверждённое требование от гипотезы. Файловый арбитраж, нормализаторы и replay исторических данных нужны только полному production-треку.

Эта глава продолжает часть 13 первого тома: там мы восстанавливали конституцию существующего проекта, здесь восстанавливаем одно production-требование из следов инцидента. Держите фокус узким: один claim, два источника, один открытый вопрос. Всё, что требует нормализаторов, исторического replay или файлового арбитража, относится к полному треку.

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

Опора из первого тома: часть 13 учит восстанавливать конституцию существующего проекта; здесь вы восстанавливаете одно production-требование.
Локальный учебный кейс: node_not_ready, потому что по нему легко показать провенанс и неопределённость.

След для capstone/: одна запись genealogy.md для основного high_memory_usage с двумя evidence_ref и одним открытым вопросом.
Главные термины первого прохода: evidence_ref и memory bank (граница между требованием и фоновым контекстом). Остальные термины главы — Verifier/Implementor/Safety, Координатор-протоколист, нормализатор, файловый арбитраж — справочные, разбираются подробно в части 8.
Что отложить: нормализаторы логов, исторический replay и файловый арбитраж.

В первом томе AgentClinic был учебным проектом на TypeScript, Hono, серверном JSX, SQLite и Vitest. Во втором томе мы используем учебную модель AgentClinic-production. Тот же проект мысленно развёрнут в Kubernetes. Grafana и PagerDuty шлют вебхуки (webhook) в его триаж-контур, а долго работающие реплики накопили операционную историю. Python во втором томе используется только для маленьких runnable-скриптов в examples/, а не как стек основного приложения.

Реальный кластер поднимать не нужно. Legacy-следы, с которыми работают главы 1–11, — это учебные пост-мортемы, дашборды и логи production-сценария. Конкретные инциденты дальше (node_not_ready, appointment_latency / appointment_latency_spike, autoscale_200pct, cdn_error_budget_burn, high_memory_usage) — события из этой модели, а не абстрактные сценарии.

Инженерное название этого приёма — восстановление спецификаций из наблюдаемых артефактов: логов, метрик, чатов, пост-мортемов и проверяемых следов решений. Если встречаете образную формулировку «Spec-некромантия», считайте её только коротким ярлыком для этой реконструкции, а не отдельной техникой.

Цель

После оттока команды SRE в проекте автоматического управления инцидентами остались фрагменты: 47 страниц неструктурированных логов, несколько Slack-тредов, скриншоты дашбордов и пост-мортемы без формального SDD. Цель главы — показать, как по таким следам восстановить инженерно пригодную спецификацию для триаж-пайплайна на основе Qwen Code. Альтернатива — набор правдоподобных догадок — нам не подходит.

После раздела вы сможете:

отделять требования от фоновой модели memory bank (полное определение — в «Ключевых идеях» ниже);
собирать доказательства в единую цепочку событий;
извлекать неявные правила и превращать их в проверяемые пользовательские истории;
закреплять происхождение каждого пункта так, чтобы спорные решения можно было аудировать и переобосновывать позже (рамка SDD «спецификация как исполняемый артефакт» из GitHub Spec Kit).

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

Учебный кейс

Production-инцидент node_not_ready: по логу метрик, эскалации в PagerDuty и одному пост-мортему нужно восстановить одно требование — когда событие NodeNotReady становится P1 и когда его нельзя закрывать автоматически.

Подготовка

book2/examples/templates/genealogy.md — шаблон провенанса.
Учебная выписка ниже — минимальный заменитель логов, пост-мортема и Slack-треда.
Один спорный факт: окно планового деплоя, canary namespace или ручная отмена эскалации.

Логичный вопрос: чем genealogy.md отличается от git log или git blame. Коротко: тем, что в git нет полей, которые здесь несущие. git log показывает, какой файл изменился и кто это сделал. genealogy.md показывает, откуда взялось само требование, насколько мы в нём уверены (uncertainty), какие источники его подтверждают (evidence_ref) и какие открытые вопросы остались без ответа. Коммит «added requirement» в git-истории не отличает «мы это твёрдо знаем из двух пост-мортемов» от «мы это предположили в чате». В genealogy.md эта разница обязательна.

Минимальная учебная выписка:

grafana:NR-2026-05-17-01  cluster=prod-k8s node=worker-07 event=NodeNotReady count=3 window=10m
pagerduty:NR-2026-05-17-01 escalation=created owner=platform_oncall severity=P1
postmortem:node-not-ready-2026-05  note="auto-resolve was rejected until two stable OK windows"
open_questions:
  - "canary namespace исключает P1 или только снижает уверенность?"

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

Шаги

Скопируйте шаблон genealogy.md в рабочий каталог. Ожидание: появился файл с разделами для источника, статуса, уверенности и открытых вопросов.
Запишите одно утверждение-кандидат: например, >=3 NodeNotReady за 10 минут создают P1.
Добавьте минимум две пометки-доказательства (evidence_ref) и один недостающий контекст. Ожидание: утверждение нельзя прочитать как «просто мнение автора».
Отделите требование от memory bank: топология кластера и имена дежурных не должны становиться контрактом.
Перепишите утверждение в Given/When/Then и рядом укажите, какое поле будущей JSON Schema проверит порог, severity и условие закрытия.
Поставьте статус approved, needs_clarity или rejected. Ожидание: спорный факт не маскируется под утверждённое требование.

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

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

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

Перенесите в capstone/genealogy.md только одну защищённую запись: утверждение, два evidence_ref, уровень уверенности и открытый вопрос. Не переносите всю временную шкалу, выписки логов и Slack-цитаты, если они не стали доказательством конкретного требования.

Минимальный фрагмент для high_memory_usage:

- claim: "При memory_percent >= 90% за 10m для appointments-api создаётся P1."
  status: needs_clarity
  evidence_ref: ["grafana:HM-2026-05-17-01", "postmortem:api-memory-2026-05"]
  uncertainty: medium
  open_questions:
    - "Подтверждён ли запрет auto-resolve без двух стабильных окон?"

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

В учебном пакете сохраняйте только заполненный genealogy.md или его фрагмент. Черновые выписки логов и временные таблицы не нужны в репозитории, если они не стали проверяемым доказательством.

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

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

Если этот термин кажется новым, посмотрите на него через первый том. То, что там жило в tech-stack.md (на чём пишем) и в QWEN.md (постоянный контекст агента), во втором томе называется одним общим словом memory bank. Это тот же фоновый слой, только теперь он явно отделён от требований, потому что в production-сценариях разница «контракт vs контекст» становится критичной.

Требование, в отличие от memory bank, описывает поведение фичи. Что считается триггером. Когда создаётся инцидент. Какой SLA применяется. Кто получает эскалацию. При каких условиях событие закрывается.

memory bank хранит другое: топологию кластера, список команд, исторические договорённости, ограничения API, привычные каналы связи и операционную лексику. Почему это важно разделять. Если смешать уровни, в SDD легко появится ложное правило вроде «canary всегда неэскалируемый». На самом деле это может быть только контекст тестового namespace, а не универсальное поведение продукта.

Вводите разделение уже на этапе инвентаризации артефактов. В SDD относите утверждения, которые можно проверить наблюдаемым сценарием: >=3 NodeNotReady за 10 минут создают P1, NOC получает уведомление через 15 минут, закрытие требует 2 последовательных OK.

В memory bank отправляйте всё, что помогает интерпретировать факты, но контрактом не является:

кто дежурил в ночь инцидента;
почему в Slack использовали старое имя сервиса;
какие команды имеют доступ к Grafana.

Такой фильтр снижает риск, что Qwen Code примет инфраструктурный фон за бизнес-правило и начнёт проектировать поведение на основании случайной детали.

Вторая идея — собрать и нормализовать доказательства в единую временную цепочку событий. Источники у каждого свой профиль:

логи дают наблюдаемые состояния и порядок наступления событий;
Slack показывает намерения операторов и ручные обходы;
пост-мортем фиксирует причины и последствия;
метрики позволяют оценить масштаб деградации.

Перед анализом приведите источники к общему времени (UTC). Уберите дубли, выделите коды событий и свяжите записи единым идентификатором инцидента, кластера, узла (node) или развёртывания (deployment). Без этого восстановление SDD превращается в спор о воспоминаниях, а не в реконструкцию поведения системы.

Нормализованная цепочка строится как последовательность ts → source → event_code → actor → affected_scope → evidence_ref, где последнее поле — это пометка-доказательство (evidence_ref), ссылка на конкретное место в исходном артефакте. В кейсе node_not_ready каркас может показать, что три события NodeNotReady за 10 минут почти всегда предшествовали созданию P1. Затем через 15 минут шла эскалация в NOC. Закрытие происходило только после пары устойчивых OK.

Отдельно фиксируйте исключения: окно планового деплоя, canary namespace, временная потеря метрик или ручная отмена эскалации. Не удаляйте такие исключения как шум — именно они часто указывают на скрытые условия будущей спецификации.

> [conceptual interface] — эти команды показывают ожидаемый интерфейс локальных нормализаторов. Готовых timeline_builder.py и evidence_matrix.py в репозитории учебника нет; реализуйте их в своём проекте, если перейдёте от учебного минимума к полному треку.

rg -n "NotReady|NodeNotReady|ALERT|deploy" evidence/raw/* > evidence/index.txt
python3 tools/timeline_builder.py --input evidence/raw --out evidence/timeline.ndjson
python3 tools/evidence_matrix.py \
  --timeline evidence/timeline.ndjson \
  --slack evidence/slack_export.json \
  --metrics evidence/metrics.csv \
  --out evidence/matrix.csv

Контроль: каждая строка в evidence/timeline.ndjson содержит ts, source, event_code, cluster, namespace, actor и evidence_ref; пустые поля блокируют переход к выводу требований.

Дальше схема показывает, как из legacy получают восстановленный SDD. На правой стороне появляется блок «Арбитраж» с тремя ролями и координатором: это полный трек, который подробно разбирается в части 8. На первом проходе считайте блок «Арбитраж» одним шагом «спорные требования проверяет независимая роль» — детальный состав ролей здесь читать не нужно.

flowchart TD
  subgraph Вход["Вход: legacy"]
    L[Логи, пост-мортем, Slack, метрики]
  end
  subgraph Обработка["Обработка"]
    P[Парсинг и временная цепочка]
    R[Гипотезы требований и пользовательские истории]
  end
  subgraph Арбитраж["Арбитраж (полный трек, ч.8)"]
    TBR[Независимая роль проверяет спорные требования]
  end
  subgraph Результат["Результат"]
    S[Восстановленный SDD и genealogy.md]
  end
  L --> P --> R --> TBR --> S

Третья идея — извлекать неявные требования через Qwen Code, но оценивать каждое утверждение по источнику и контексту. Qwen Code здесь работает не как автор бизнес-логики, а как посредник для извлечения. Ему передают факты, ограничения среды и строгий формат ответа, где запрещены утверждения без ссылки на доказательство.

Хороший запрос просит не «придумать SDD», а сделать другое:

найти повторяющиеся правила в цепочке событий;
указать подтверждающие источники;
назвать контрпримеры;
присвоить уровень уверенности.

Так модель усиливает анализ, но не получает права превращать догадки в требования. Ожидайте от Qwen Code список утверждений-кандидатов (claims), а не финальную спецификацию.

Плохо:

> REQ-NR-01: при частых NodeNotReady на node создаётся P1.

Проблема: нет ни порога, ни окна, ни пометки-доказательства. Правило невозможно ни проверить, ни оспорить.

Хорошо:

> REQ-NR-01: при >=3 NodeNotReady за 10 минут на одном node и коррелированном росте 5xx создаётся P1. evidence: logs/node-2026-05-12.parquet#row_4123, slack/thread_11#msg_7, grafana/node_5xx#segment_11:00. confidence: medium. missing_context: planned deploy window.

Что это даёт на практике. Такая запись полезнее гладкого текста пользовательской истории: она сразу показывает, где требование устойчиво, а где требует проверки у владельца сервиса. Если правило подтверждено только одним пост-мортемом и не совпадает с метриками, оно остаётся гипотезой, даже если звучит убедительно.

> [project script] — qwen -p сам по себе runnable, но входной @evidence/matrix.csv нужно сначала собрать в вашем проекте. Формат итогового JSON стабилизируйте отдельным парсером-нормализатором.

qwen -p "Прочитай @evidence/matrix.csv. Найди повторяющиеся правила
инцидента node_not_ready. Верни claims с evidence, counterexample,
missing_context и confidence. Не утверждай факты без evidence." \

--approval-mode plan \
  --output-format json \
  > sdd/drafts/nr-claims.qwen.json

qwen -p "Прочитай @sdd/drafts/nr-claims.qwen.json и проведи cross-examine:
для каждого claim проверь source, counterexample и missing_context.
Пометь claim как approved, needs_clarity или rejected." \
  --approval-mode plan \
  --output-format json \
  > sdd/drafts/nr-claims-cross.qwen.json

Контроль: Qwen здесь работает в безголовом Plan Mode. Итоговый JSON Qwen Code —
отчёт с сообщениями сессии; если проекту нужен строгий claims.json,
добавьте отдельный парсер-нормализатор и проверяйте его тестами.

Четвёртая идея — кодировать требования одновременно в Given/When/Then и машинно-читаемый контракт, например JSON Schema. Given/When/Then удерживает требование на языке поведения: исходное состояние, событие, ожидаемый результат.

JSON Schema фиксирует обязательные поля, допустимые значения, числовые границы и структуру данных. Контракт можно валидировать в CI или локальном валидаторном пайплайне. Двойная запись устраняет разрыв между «понятно человеку» и «проверяемо машиной».

Для node_not_ready поведенческая история выглядит так:

Given кластер prod-k8s находится в активной смене и за 10 минут фиксируется >=3 NodeNotReady для одного узла;
When событие коррелировано с развёртыванием или ростом 5xx в связанных метриках;
Then создаётся инцидент severity=P1, первичная реакция ожидается за 8 минут, автоэскалация в NOC происходит через 15 минут, а закрытие разрешено только после 2 последовательных OK в течение 10 минут.

Оформите исключение для canary namespace как отдельное условие, а не как примечание в конце. Иначе валидатор не сможет отличить стандартный путь от ослабленного порога. Такой формат переводит разговор о «быстрой реакции» в конкретные числа, события и статусы.

Минимальная JSON Schema того же контракта (полная форма с triggers и регулярным выражением для auto_resolve_window — в полном треке):

{
  "$id": "urn:spec:node-not-ready:v1",
  "type": "object",
  "required": ["rule_id", "severity", "sla_minutes", "conditions"],
  "properties": {
    "rule_id":      {"type": "string"},
    "severity":     {"type": "string", "enum": ["P0", "P1", "P2", "P3"]},
    "sla_minutes":  {"type": "integer", "minimum": 1, "maximum": 120},
    "conditions": {

"type": "object",
      "required": ["event_code", "count", "window_minutes", "namespace_rule"],
      "properties": {
        "count":          {"type": "integer", "minimum": 3},
        "window_minutes": {"type": "integer", "minimum": 1},
        "namespace_rule": {"type": "string", "enum": ["standard", "canary"]}
      }
    }
  }
}

Пятая идея относится только к полному треку: спорные восстановленные требования можно отдавать в файловый арбитраж. Голосуют три роли — Верификатор, Имплементор, Safety; Координатор ведёт журнал, не голосуя. Верификатор проверяет непротиворечивость чисел и статусов, Имплементор — реализуемость в текущем триаж-пайплайне, Safety — границы безопасного действия и право veto при critical_risk. Подробно роли, вердикты и прецеденты разбираются в части 8; запускаемый учебный аналог — [examples/tribunal/](examples/tribunal/). Для учебного минимума этот шаг не нужен: достаточно genealogy.md с источниками, уровнем уверенности и открытым вопросом.

Шестая идея — вести genealogy.md, отдельный реестр происхождения каждого требования. Зачем он нужен. Восстановленный SDD быстро теряет ценность, если через месяц невозможно объяснить:

почему выбран порог 3 события за 10 минут;
кто подтвердил SLA 8 минут;
почему canary получил отдельный режим.

genealogy.md связывает утверждение с логами, Slack, метриками, пост-мортемом, решением файлового арбитража и текущим уровнем неопределённости. Так спецификация становится цепочкой доказательств, а не текстовым снимком коллективной памяти.

- req_id: NR-01
  statement: "При >=3 NodeNotReady за 10m для одного node и росте 5xx создаётся P1."
  source:
    - logs: evidence/normalized_node_logs.parquet#row_4123
    - slack: export/slack_thread_11.json#msg_7
    - metrics: grafana/node_5xx_timeseries.csv#segment_2026-05-12T11:00
  status: approved
  adjudicated_by: [Verifier, Implementor, Safety]
  uncertainty: low
  open_questions: []

Если пункт остаётся спорным, не маскируйте его под утверждённый контракт. Поставьте uncertainty: medium или uncertainty: high, укажите причину сомнения и добавьте план проверки:

запросите владельца сервиса;

прогоните replay по историческим данным;
сравните с соседним кластером;
соберите недостающую метрику.

Такой реестр провенанса особенно важен для будущей Конституции проекта. В неё должны переходить только правила с понятным происхождением, областью действия и механизмом пересмотра.

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

Учебная выписка из 4 строк в «Минимальном учебном сценарии» — это уже отфильтрованный итог нормализации. В исходном наборе встречается:

9 часов наблюдений;
11 релевантных Slack-сообщений;
47 страниц неочищенных логов;
1 248 событий NodeNotReady;
63 алерта;
8 ранее закрытых инцидентов.

После нормализации видно, что резкий рост NodeNotReady совпал с развёртыванием, часть событий ушла в canary-сегмент с другой логикой автоэскалации, и появляются две ветки поведения: стандартный P1 и canary-путь с ослабленными порогами.

> [conceptual interface] — псевдокод нормализатора. Runnable-примеры второго тома остаются на Python stdlib и лежат в book2/examples/.

read evidence/normalized_node_logs
sort events by ts
filter event_code == "NodeNotReady"
group by cluster,node in 10m windows
mark windows where count >= 3

link marked windows to alerts and Slack messages in [-15m,+5m]

Окно [-15m,+5m] нужно потому, что оператор мог обсудить проблему до формальной записи инцидента или уже после автоматического алерта. Если событие относится к canary namespace без деградации SLO — ставьте отдельную метку, а не удаляйте как шум. Если окно планового деплоя объясняет часть NodeNotReady, прямо укажите в требовании, блокирует ли это создание P1 или только снижает уверенность.

Восстановленный SDD становится рабочим артефактом только после реплея: прогоните исторические инциденты через новый JSON-контракт и проверьте, совпадают ли созданные severity, SLA и эскалации с подтверждёнными исходами. Несовпадения не всегда означают ошибку контракта — иногда они показывают, что старая практика была противоречивой или зависела от конкретного дежурного. Что менять в этом случае — спецификацию, memory bank или статус гипотезы в genealogy.md — решает файловый арбитраж из части 8.

Итог

Восстановление спецификаций из legacy восстанавливает SDD не из интуиции, а из проверяемой цепочки доказательств. Маршрут такой:

legacy-артефакты нормализуются во временную шкалу;

Qwen Code извлекает кандидатов-утверждений с уровнем уверенности;
требования отделяются от memory bank;
затем кодируются в Given/When/Then и JSON Schema;
для полного трека проходят файловый арбитраж Координатор/Имплементор/Верификатор;
получают провенанс в genealogy.md.

Такой процесс превращает хаос логов, чатов и пост-мортемов в контракт. Контракт можно валидировать, оспаривать, переигрывать на исторических данных и переносить в более строгую систему правил. В следующей главе мы намеренно отравим спецификации противоречиями и изучим, где Qwen Code начинает застревать.

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

Артефакт	Готов, когда
`genealogy.md` с одним требованием или гипотезой	требование отделено от `memory bank`, спорные факты помечены как гипотезы
Минимум два `evidence_ref` и один недостающий контекст	утверждение нельзя прочитать как «мнение автора», порог/SLA защищается ссылкой на источник либо явно помечен как пока неутверждаемый
Given/When/Then-формулировка	проверяемые поля связаны с тем, что покрывает JSON Schema

Полный трек добавляет evidence/timeline.ndjson, evidence/matrix.csv со ссылками на логи, Slack, метрики и пост-мортемы, sdd/drafts/nr-claims.qwen.json с утверждениями-кандидатами, contracts/node_not_ready.schema.json и запись файлового арбитража для требований, которые нельзя утвердить вручную. Считайте полный трек готовым, если Given/When/Then и JSON Schema описывают один и тот же контракт, нормализатор даёт воспроизводимую временную цепочку, а валидатор или файловый арбитраж выносит проверяемый verdict.

Практика

Скопируйте [examples/templates/genealogy.md](examples/templates/genealogy.md) в capstone/genealogy.md и заполните одну запись по основному кейсу high_memory_usage: утверждение, минимум два evidence_ref, уровень уверенности и один открытый вопрос. Учебную выписку из «Минимального учебного сценария» можно использовать как заменитель реальных логов.
Перепишите своё утверждение в Given/When/Then и рядом укажите, какие три поля JSON Schema проверяют порог, severity и условие закрытия. Поле, которое нельзя защитить ссылкой на источник, оставьте как uncertainty: medium, а не как утверждённый контракт.

Откройте [appendix-a-bridges-to-book.md](appendix-a-bridges-to-book.md) и отметьте, какая глава первого тома была опорой для вашего genealogy.md. Если опоры нет — это сигнал, что требование пока не привязано к учебной модели.

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

Почему доказательство важнее уверенной формулировки требования?
Чем memory bank отличается от SDD-контракта и почему опасно их смешивать?
Когда гипотезу нельзя переводить в approved-требование?
Вы восстановили правило по двум пост-мортемам, но владелец сервиса уволился полгода назад. Что вы сделаете с этим правилом до того, как добавите его в requirements.md?