Thema: Прикладная часть 6. Отбор теневых спецификаций
Schwierigkeitsgrad: Mittel
Geschätzte Lernzeit: 4-6 часов (теория + практика)
Voraussetzungen: Часть 6 первого тома: понимание различия между пожеланиями и требованиями
Часть 19 первого тома: разделение памяти агента от спецификации
Базовое владение Python 3 и командной строкой
Понимание формата YAML/JSON для конфигурационных файлов
Опыт работы с системами инцидент-менеджмента (желательно)
Lernziele: Самостоятельно запустить полный цикл аукциона теневых спецификаций: от нормализации кандидата до формирования блока для QWEN.md
Рассчитать score кандидата по формуле с заданными весами и интерпретировать результат относительно порогов keep/reject
Оформить победителя аукциона как версионированный образец-подсказку с обязательными полями id, source_ref, ttl, score
Правильно оформить отклонённого кандидата в карантин с явной причиной и условием возврата, не допуская его исчезновения из истории
Провести чувствительный анализ весов формулы и зафиксировать, как изменение штрафа за ложную эскалацию влияет на решение аукциона
Übersicht: Эта глава учит превращать неформальные операционные наблюдения — тон общения, интуитивные предпосылки, «магические» решения опытных инженеров — в управляемый слой теневых спецификаций. Ключевой приём: выносить эвристики в отдельный слой, ограничивать их по бюджету few-shot слотов, измерять предсказательную ценность на исторических инцидентах и никогда не подменять ими формальную спецификацию. Вы прогоните учебный аукцион на реальных скриптах, увидите, почему одна эвристика попадает в QWEN.md, а другая уходит в карантин, и зафиксируете результат в capstone-проекте.
Schlüsselkonzepte: Теневые спецификации (shadow specs): Проверяемые эвристики из операционной практики, которые помогают на фазе triage, но не являются обязательными требованиями системы. Формат: контекст → признак → наблюдаемый эффект. Пример: «P0-инцидент с риском каскада → дежурный пишет короткими императивными сообщениями → через 5–10 минут возникает ручной обход или откат».
Образец-подсказка (few-shot): Короткий пример в подсказке, который показывает агенту желаемый формат ответа на похожих кейсах. В отличие от обычной памяти, имеет явный срок жизни (ttl) и проходит аукцион приёма.
Журнал оценок (scorebook): Журнал экономики теневых спецификаций: исходные данные (seed), формула оценки, пороги, бюджет (budget), версии кандидатов и протокол решения. Позволяет воспроизвести результат и оспорить его при изменении инфраструктуры.
Аукцион теневых спецификаций: Процесс ранжированного отбора под ограниченный контекстный бюджет (например, 2000 токенов или 8 слотов). Кандидаты сортируются по value_score, затем распределяются на три категории: keep (победитель, в QWEN.md), review (спорный, на ручную ревизию), quarantine (отбракован, в карантин).
Формула оценки: Воспроизводимая формула вместо экспертной оценки «кажется полезным». Учебный вариант: score = 0.5×mttr_gain + 0.3×early_signal + 0.2×coverage − 0.4×false_escalation. Сумма положительных весов равна 1, итоговый score лежит в [−0.4; 1].
Карантин (quarantine): Явное хранилище для отклонённых кандидатов с причиной отклонения, датой пересмотра и условием возврата. Защищает от исчезновения низкоценных кандидатов без следа и позволяет вернуть их при изменении инфраструктуры.
Anti-goodhart (анти-гудхарт): Защита от оптимизации показателя за счёт смысла. Воспроизводимый журнал оценок позволяет пересчитать результаты после изменения весов, проверить влияние конкретных инцидентов и отделить реальное улучшение от ловушки Гудхарта.
Дрейф данных (drift): Рассинхронизация временных шкал и идентификаторов в источниках инцидентов. Требует дедупликации, нормализации временных меток и привязки к единому идентификатору инцидента перед оценкой.
Übungsaufgaben: Name: Запуск учебного аукциона: от score до решения
Problem: В каталоге book2/examples/shadow-auction запустите полный пайплайн: расчёт scorebook, принятие решения аукциона и генерацию блока для QWEN.md. Убедитесь, что результаты воспроизводимы и совпадают с эталонами.
Lösung: Шаг 1: cd book2/examples/shadow-auction. Шаг 2: python3 scripts/score.py --candidates candidates/candidates.yaml --incidents data/incidents.jsonl --weights 0.5,0.3,0.2,0.4 --out out/scorebook.json. Проверьте diff -u outputs/scorebook.example.json out/scorebook.json — ожидается 0 строк. Шаг 3: python3 scripts/decide.py --scorebook out/scorebook.json --budget-tokens 2000 --keep-threshold 0.70 --reject-threshold 0.40 --out-auction out/auction.json --out-quarantine out/quarantine.json. Проверьте совпадение с outputs/auction.example.json и outputs/quarantine.example.json. Шаг 4: python3 scripts/write_qwen_block.py --auction out/auction.json --target-anchor 'QWEN.md#incident-triage-shadow' --today 2026-05-17 --out out/qwen_block.md. Сверьте с outputs/qwen_block.example.md. Шаг 5: проверьте, что в quarantine есть запись с явным reason и return_condition.
Komplexität: intermediate
Name: Чувствительный анализ весов: удвоение штрафа за ложную эскалацию
Problem: Измените вес штрафа за ложную эскалацию с 0.4 на 0.8, пересчитайте scorebook и зафиксируйте, какой кандидат изменил статус. Объясните, какой компонент формулы стал доминирующим.
Lösung: Шаг 1: Запустите score.py с --weights 0.5,0.3,0.2,0.8. Шаг 2: Сравните out/scorebook.json с оригиналом. Найдите кандидата, у которого score пересёк порог (например, shadow.alert.red_color_urgency с −0.3081 мог уйти ещё ниже, или кандидат с граничным score упал ниже reject_threshold). Шаг 3: Запишите в capstone/README.md: «При удвоенном штрафе за ложную эскалацию кандидат <id> перешёл из <статус1> в <статус2>. Компонент false_escalation стал доминирующим: при false_escalation=1 он вычитает 0.8, что эквивалентно потере 1.6 идеальных снижений MTTR (0.8/0.5=1.6)». Шаг 4: Объясните, почему это калибровка под более высокую цену ошибки в вашей команде.
Komplexität: intermediate
Name: Нормализация наблюдения в формат теневой спецификации
Problem: Дано неформальное наблюдение от дежурного: «Когда в Slack пишут ASAP, я сразу понимаю, что это серьёзно, и поднимаю severity». Превратите это в структурированную теневую спецификацию, затем проанализируйте риски и подготовьте аргументы для аукциона.
Lösung: Шаг 1: Нормализация. Контекст: «инцидент любого уровня в чате команды». Признак: «сообщение содержит слово ASAP». Эффект: «дежурный повышает severity вручную». Шаг 2: Добавьте поля: evidence (интервью дежурного от 2026-05-10), scope (только Slack-канал #incidents), risk (ложные эскалации: ASAP используется и для рутинных запросов), source_ref (интервью, 3 инцидента). Шаг 3: Подготовьте аргументы для аукциона: mttr_gain — неизмерим, т.к. нет данных о сокращении времени; early_signal — слабый, ASAP часто появляется после уже известной проблемы; coverage — высокий, но это минус (слишком широко); false_escalation — высокий риск. Прогноз: score будет низким, кандидат уйдёт в review или quarantine. Шаг 4: Оформите как shadow.slack.asap_urgency со статусом review и примечанием «требует 50+ инцидентов для калибровки».
Komplexität: intermediate
Name: Оформление победителя и отклонённого кандидата в capstone
Problem: Перенесите результаты учебного аукциона в capstone/README.md в секцию Shadow notes. Победитель не должен стать требованием в requirements.md.
Lösung: Минимальный фрагмент для capstone/README.md:
shadow_notes:
keep:
id: shadow.p0.voice_handoff.v1
score: 0.727
ttl: "14d"
reason: "early signal for manual handoff"
source_ref:
- postmortem: "appointments-api-2026-02-11"
- incident: "INC-1842"
reject:
id: shadow.alert.red_color_urgency
reason: "false escalation risk"
score: -0.3081
return_condition: "изменение политики визуализации оповещений"Проверьте: победитель имеет узкое условие применимости (только P0 с риском каскада), отклонённый не исчез а получил причину и условие возврата, ни один из них не добавлен в requirements.md.
Komplexität: beginner
Fallstudien: Name: Голосовой handoff против цвета дашборда: учебный аукцион в действии
Szenario: Команда SRE appointments-api накопила два операционных наблюдения за полгода инцидентов. Первое: при P0-инцидентах с риском каскада опытный дежурный вместо длинного сообщения в чат сразу инициировал голосовую передачу (voice handoff) между дежурным и владельцем сервиса. Второе: дежурный утверждал, что красный цвет в дашборде Grafana — надёжный сигнал срочности, и предлагал автоматически повышать severity при его появлении.
Aufgabe: Оба наблюдения звучали убедительно на словах, но имели противоположные последствия. Voice handoff требовал места в контекстном бюджете QWEN.md, но его ценность не была измерена. Правило про красный цвет рисковало породить лавину ложных P1, т.к. красный использовался для визуального акцента без привязки к радиусу последствий. Команда не могла отличить полезную эвристику от операционного фольклора.
Lösung: Оба наблюдения были нормализованы в формат контекст → признак → эффект и прогнаны через аукцион на 20 исторических инцидентах из data/incidents.jsonl. Формула score = 0.5×mttr_gain + 0.3×early_signal + 0.2×coverage − 0.4×false_escalation дала voice handoff score 0.727 (высокий mttr_gain 0.7541, идеальный early_signal 1.0, узкое покрытие 0.25, ноль ложных эскалаций). Красный цвет получил −0.3081: слабый mttr_gain и заметная доля ложных эскалаций. Voice handoff стал победителем с узким условием применимости в QWEN.md. Красный цвет ушёл в карантин с причиной high_false_escalation и условием возврата при изменении политики визуализации.
Ergebnis: Voice handoff как версионированный образец-подсказка с ttl 14 дней и source_ref на постмортем appointments-api-2026-02-11. Красный цвет не исчез из истории — его можно вернуть на аукцион при новых данных. Команда получила воспроизводимый процесс отбора вместо спора авторитетов. Доверие к автоматическим рекомендациям повысилось, т.к. каждая эвристика имела измеримое обоснование.
Gewonnene Erkenntnisse: Яркая история («красный = срочность») не заменяет журнал оценок — интуиция часто ошибается при масштабировании
Узкое покрытие (coverage) — не всегда минус: voice handoff применялся редко, но с высокой точностью, что компенсировало узость
Условие возврата в карантине защищает от окончательного удаления: инфраструктура меняется, и вчерашний отказ может стать завтрашним сигналом
Победитель не должен становиться требованием — он остаётся теневой подсказкой с явным сроком пересмотра
Verwandte Konzepte: Теневые спецификации (shadow specs)
Журнал оценок (scorebook)
Аукцион теневых спецификаций
Anti-Goodhart (анти-Гудхарт)
Карантин (quarantine)
Name: Запах гари в дата-центре: когда редкий сигнал оправдывает место в бюджете
Szenario: Операторы физического дата-центра заметили: в редких случаях запах перегрева или гари предшествует срабатыванию мониторинга питания на 30–120 секунд. Это наблюдение пришло от инженера с 10-летним стажем и первоначально воспринималось как «магия», не поддающаяся формализации.
Aufgabe: Сигнал физического запаха имеет крайне низкое покрытие (только onsite-инциденты в конкретных дата-центрах), нулевую применимость к облачным инцидентам и риск ложных срабатываний от несистемных источников (уборка, соседнее оборудование). При попытке включить его как универсальное правило он стал бы токсичным шумом. При отбрасывании — команда теряла бы редкий, но ценный ранний сигнал с высокими последствиями пропуска.
Lösung: Наблюдение нормализовано как shadow.dc.burn_smell_power_risk с жёсткими ограничителями: контекст «инцидент с физическим доступом в дата-центре класса T3+», признак «оператор на месте фиксирует запах перегрева до алерта PDU», эффект «возможное предшествование отказа питания на 30–120 секунд». Формула дала высокий early_signal (1.0), низкий coverage (0.1), нулевую false_escalation при обязательном подтверждении оператором. Решение аукциона: включить как редкий образец-подсказку с тремя ограничителями — жёсткий контекст, явное примечание о риске, требование подтвердить через канал оператора на месте.
Ergebnis: Сигнал занял 1 слот в бюджете из 8, но в двух исторических кейсах дал критическое преимущество для graceful shutdown. Для облачных инцидентов правило не применяется — нет шума. При миграции части инфраструктуры в облако кандидат автоматически ушёл в review по условию контекста, не требуя ручного удаления.
Gewonnene Erkenntnisse: Редкий сигнал с высокой ценой пропуска может выиграть аукцион несмотря на низкое покрытие
Жёсткий контекст — защита от токсичного шума: правило применяется только где имеет смысл
Требование подтверждения через независимый канал (оператор на месте) снижает false_escalation без потери early_signal
Автоматический review при изменении контекста (миграция в облако) защищает от устаревания эвристики
Verwandte Konzepte: Теневые спецификации (shadow specs)
Аукцион теневых спецификаций
Образец-подсказка (few-shot)
Дрейф данных (drift)
Lerntipps: Проходите материал последовательно: сначала минимальный учебный сценарий (шаги 1–5), затем теория ключевых идей, затем практика с изменением весов. Попытка сразу калибровать веса на 50+ инцидентах отвлечёт от понимания механизма
Держите рядом два окна терминала: одно с выполнением скриптов, другое с просмотром генерируемых JSON/YAML. Визуальное сравнение scorebook.example.json и вашего out/scorebook.json ускоряет понимание формулы
Используйте diff -u для всех эталонных проверок. Если расхождение есть — не игнорируйте, а найдите, какой компонент формулы дал другой результат. Это лучший способ понять чувствительность весов
Создайте личный «зоопарк» операционного фольклора: записывайте яркие фразы дежурных («ASAP = P1», «красный = срочность», «тихий канал = всё сломалось») и практикуйте их нормализацию в контекст → признак → эффект. Это развивает интуицию отличия эвристики от шума
Для визуального стиля: нарисуйте на бумаге блок-схему из mermaid-диаграммы главы. Физическое прослеживание пути от интервью до QWEN.md помогает запомнить архитектуру процесса
При изучении карантина задайте себе вопрос: «Почему отклонённый кандидат не должен исчезать?» Ответ — для оспаривания решений и возврата при изменении инфраструктуры — ключевое отличие зрелого процесса от «чёрного ящика»
Практикуйте объяснение Anti-Goodhart на бытовом примере: «Если оптимизировать только скорость доставки пиццы, курьеры будут нарушать ПДД». Это помогает запомнить, зачем нужен воспроизводимый журнал вместо голой метрики
Для аудиального стиля: проговаривайте формулу оценки вслух с акцентом на штраф: «ноль пять эм-тэ-тэ-ар, ноль три ранний сигнал, ноль два покрытие, минус ноль четыре ложная эскалация». Ритм помогает запомнить пропорции
Zusätzliche Ressourcen: Book2/examples/shadow-auction/readme.md: Запускаемый учебный аукцион со скриптами score.py, decide.py, write_qwen_block.py и эталонными выходами
Book2/examples/shadow-auction/outputs/: Эталонные файлы scorebook.example.json, auction.example.json, quarantine.example.json, qwen_block.example.md для сверки
Book2/appendix-d-threshold-calibration.md#d2-отбор-теневых-спецификаций-глава-6: Полный трек калибровки порогов, весов и сигналов для пересмотра на 50+ инцидентах
Book2/part-06-constitution.md (том 1): Опора: различие пожеланий и требований, откуда берутся «не дотянувшие» наблюдения
Book2/part-19-agent-memory-sqlite.md (том 1): Опора: разделение памяти агента от спецификации, предшественник few-shot с ttl
Github spec kit — .specify/memory/constitution.md: Пример защитного слоя от дрейфа для SDD-контура
Постмортем appointments-api-2026-02-11: Учебный source_ref для победителя shadow.p0.voice_handoff (внутри data/incidents.jsonl)
Zusammenfassung: Главное открытие этой части: неформальные операционные наблюдения можно и нужно управлять, но нельзя подменять ими формальную спецификацию. Теневые спецификации — это проверяемый слой между операционным фольклором и требованиями: каждый кандидат проходит нормализацию в формат контекст → признак → эффект, оценку на исторических инцидентах по воспроизводимой формуле, аукцион за ограниченный контекстный бюджет и либо становится версионированным образцом-подсказкой с ttl в QWEN.md, либо уходит в карантин с явной причиной. Журнал оценок защищает от ловушки Гудхарта и позволяет оспорить решение. Победитель не становится требованием — он остаётся теневой подсказкой со сроком пересмотра. Это дисциплина измеримого отбора вместо доверия ярким историям.