Тема: Приложение C. Чек-листы прикладного SDD
Уровень сложности: Средний
Расчётное время изучения: 4-6 часов
Предварительные требования: Изучение базовых чек-листов спецификации, реализации и слияния из первого тома SDD.
Понимание концепций CI/CD и автоматизации валидации.
Знакомство с базовой структурой артефактов: requirements.md, plan.md, validation.md, QWEN.md.
Опыт работы с Markdown и системами контроля версий.
Цели обучения: Научиться применять специализированные чек-листы на каждом этапе прикладного цикла SDD.
Освоить механизмы работы с унаследованными системами и разрешения спорных изменений через файловый арбитраж.
Понять принципы безопасной настройки авто-ремедиации и защиты от Закона Гудхарта при оптимизации метрик.
Разобраться в методологии 'ядовитой спецификации' для проверки устойчивости процессов валидации.
Успешно подготовить проектный пакет в каталоге capstone/ для прохождения итогового production-зачёта.
Обзор: Данный учебный гайд представляет собой детальное руководство по использованию Приложения C во время прикладного цикла Software Design Document (SDD). Материал надстраивается над базовыми концепциями первого тома и фокусируется на продвинутых сценариях: работе с legacy-системами, внедрении дельт-арбитража, защите метрик от манипуляций и подготовке к финальному аудиту. Гайд описывает строгие критерии для шлюзов спецификации (Spec CI), требования к доказательной базе и правила остановки автоматизации при обнаружении антипаттернов.
Ключевые концепции: Ядовитая спецификация (poisoned spec): Специально внедренный в систему ровно один дефект для проверки эффективности процессов контроля качества. Ожидаемый симптом сбоя должен быть описан заранее, а успешное исправление должно затрагивать артефакты (spec/plan/validation), а не только текстовые объяснения.
Файловый арбитраж (file arbitration): Метод разрешения споров в команде, при котором фокус смещается с текстовых дискуссий в чате на анализ различий (diff) в самих файлах. Требует жесткого распределения ролей (Координатор, Имплементор, Верификатор).
Закон гудхарта и anti-goodhart метрики: Принцип, согласно которому метрика перестает быть полезной, как только становится целью. Для защиты системы каждая целевая метрика должна иметь парную защитную (anti-Goodhart) метрику и 'правило красной кнопки'.
Авто-ремедиация (auto-remediation): Автоматизированный процесс восстановления системы после сбоя. Требует предварительного определения радиуса последствий, обязательного dry-run (пробного прогона) и жестких условий отката, зафиксированных до начала исполнения.
Шлюз спецификации (spec ci): Непрерывная интеграция для требований. Проверяет наличие стабильных REQ-* идентификаторов, связность плана с требованиями и валидность JSON-примеров. Ошибка в CI должна содержать исчерпывающую информацию: файл, строку, правило, причину и действие.
Артефакты генеалогии и трассировки (genealogy & evidence): Принцип, по которому каждое решение, метрика или запись в QWEN.md должны иметь автора, источник решения (хэш подсказки/политики), доказательство и уровень уверенности.
Практические упражнения: Название: Настройка шлюза спецификации (Spec CI)
Проблема: Вам предоставлен список разрозненных требований к API. Необходимо подготовить их к прохождению через Spec CI, обеспечив связность плана и валидации.
Решение: 1. Присвойте каждому требованию уникальный идентификатор в формате REQ-01, REQ-02 и т.д. 2. В plan.md создайте пункты плана, содержащие прямые ссылки на соответствующие REQ-* идентификаторы. 3. Опишите контракты в доменной модели. 4. Создайте JSON-примеры в validation.md и убедитесь, что они успешно валидируются JSON Schema. 5. Настройте вывод ошибок CI так, чтобы он содержал файл, строку и причину.
Сложность: intermediate
Название: Внедрение 'Ядовитой спецификации'
Проблема: Команда уверена, что их процесс валидации идеален. Ваша задача — доказать или опровергнуть это, внедрив ядовитую спецификацию в тестовый набор требований.
Решение: 1. Выберите один конкретный дефект (например, изменение типа данных в ответе API). 2. Внесите его в validation.md. 3. Зафиксируйте в отдельном документе ожидаемый симптом сбоя. 4. Запустите CI/валидацию. 5. Если сбой не обнаружен, обновите требования (requirements.md) так, чтобы этот тип ошибки стал невозможен (изменив схему или spec).
Сложность: advanced
Название: Разбор антипаттернов прикладного цикла
Проблема: Проект стабильно падает на продакшене из-за того, что команда постоянно ослабляет validation.md при падении CI и не имеет ограничений на mutable_rules. Проведите аудит по чек-листу.
Решение: 1. Введите жесткий запрет на редактирование validation.md при падении тестов (чинить нужно код). 2. Найдите все правила в mutable_rules без TTL или с TTL > 90 дней и удалите/обновите их. 3. Настройте правило красной кнопки (veto от Safety) в governance_protocol. 4. Убедитесь, что falling CI чинится кодом, а не валидацией.
Сложность: intermediate
Кейсы: Название: Кризис авто-ремедиации в платежном шлюзе
Сценарий: Команда внедрила скрипт авто-ремедиации для перезапуска зависших сервисов обработки платежей на основе метрик CPU. Автоматизация была призвана снизить MTTD (Mean Time To Detect) и MTTR (Mean Time To Resolve).
Задача: При очередном сбое скрипт начал перезапускать сервисы в бесконечном цикле, что привело к дублированию транзакций и блокировке базы данных. Радиус последствий не был определен заранее, и скрипт не имел стоп-условия для ручного ревью.
Решение: Команда экстренно остановила скрипт и применила чек-лист 'Перед авто-ремедиацией'. Были внедрены: пробный прогон (dry-run) в изолированной среде, жестко прописанное условие отката до исполнения, и порог ручного подтверждения при повторном провале. Для мониторинга была добавлена парная anti-Goodhart метрика (кол-во дубликатов транзакций), чтобы предотвратить слепую погоню за временем аптайма.
Результат: Инцидент был локализован. Авто-ремедиация теперь срабатывает корректно только на изолированном сбое, при расширении радиуса влияния система переходит в режим ожидания ручного подтверждения (manual_review_floor).
Извлечённые уроки: Никогда не внедряйте авто-ремедиацию без заранее записанного условия отката.
Радиус последствий должен быть строго документирован.
Агрессивная автоматизация без защиты (anti-Goodhart метрик) приводит к катастрофам.
Связанные концепции: Авто-ремедиация
Закон Гудхарта
Радиус последствий
Советы по изучению: Создайте физический или цифровой шаблон контрольного списка для каждого этапа (Spec CI, Авто-ремедиация и т.д.) и используйте его в своем текущем проекте.
Обратите особое внимание на различие между '[runnable]' и '[project script]' — это частая причина путаницы при реализации.
Используйте правило 'Трех отрицательных ответов': если на три пункта аудита антипаттернов дан отказ, немедленно остановите добавление новой автоматизации и исправьте текущий контур.
Всегда связывайте практические задачи с артефактами (requirements.md, validation.md, genealogy.md) — в прикладном SDD доказательная база важнее кода.
Дополнительные ресурсы: Часть 0 (production lab): Исходный текст для выбора учебного инцидента (incident-case) и понимания структуры capstone.
Часть 12 (аудит антипаттернов): Детальный разбор симптомов и причин сбоев в прикладном цикле, расширяющий быстрый чек-лист.
Папка examples/templates/: Содержит обязательные к изучению шаблоны: pr-template.md, retrospective.md, clear-prompt.md, replan-prompt.md.
Приложение c первого тома: Базовые чек-листы, которые являются фундаментом для текущего продвинутого руководства.
Резюме: Приложение C представляет собой строгий набор валидационных барьеров для продвинутого прикладного цикла SDD. Главное правило гайда — автоматизация и оптимизация недопустимы без жесткого контроля (Spec CI,anti-Goodhart метрики, dry-run). Успешное прохождение итогового production-зачёта требует безупречной трассировки (genealogy.md, evidence_ref), умения работать с инцидентами через диффы файлов и способность системы распознавать 'ядовитые спецификации'. Если базовые процессы дают сбой, разработка должна быть приостановлена до их исправления.