Тема: Прикладная часть 2. Диагностика дефектов спецификации
Уровень сложности: Средний
Расчётное время изучения: 3-5 часов
Предварительные требования: Знакомство с концепцией отрицательных требований (Часть 7 первого тома)
Понимание антипаттернов SDD (Часть 20 первого тома)
Базовые навыки работы с YAML и JSON Schema
Общее понимание жизненного цикла разработки ПО и концепции мутационного тестирования
Цели обучения: Уметь намеренно вносить ровно один контролируемый дефект в спецификацию для проверки системы (мутационное тестирование).
Идентифицировать и классифицировать основные типы дефектов: циклы, конфликты приоритетов и скрытый выход за границы.
Распознавать симптомы застревания ИИ-агента или системы, используя метрики ask_storm, stage_regress и phase_context_loss.
Формализовать исправления конфликтов с помощью правил-исключений (override) и валидировать их через JSON Schema.
Выполнять обратный прогон полного SDD-контура (Specify → Plan → Tasks → Implement) для подтверждения устранения дефекта.
Обзор: Данная тема посвящена инженерной технике работы со спецификациями, известной как «контролируемо дефектная спецификация» (или мутационное тестирование требований). Суть метода заключается в намеренном внесении одного строго определенного дефекта в спецификацию, чтобы проверить, как система (или ИИ-агент, такой как Qwen Code) справится с его диагностикой. Основная цель — научиться управляемо вызывать сбой, читать его следы и исправлять первопричину в требованиях так, чтобы конфликт не повторялся. Подход требует строгой дисциплины: одна мутация, один ожидаемый симптом застревания и один четкий критерий восстановления, зафиксированный в формате Given/When/Then и JSON Schema.
Ключевые концепции: Контролируемо дефектная спецификация (poisoned spec): Намеренное внедрение заранее известного дефекта в требования (спецификацию) для проверки устойчивости системы, ИИ-агента или процесса триажа. Главное правило: вносится только один дефект за итерацию.
Классы дефектов (мутации): Основные типы инъекцируемых ошибок: 'cycle' (циклическая зависимость между состояниями), 'priority_conflict' (два правила с одинаковым приоритетом, ведущие к разным действиям) и 'hidden_out_of_scope' (действие, вынуждающее нарушить заданные ограничения).
Метрики застревания (диагностические признаки): Эвристики для локализации проблем поведения ИИ-агента: 'ask_storm' (повторные вопросы без новых данных), 'stage_regress' (откат к предыдущим стадиям без причины), 'phase_context_loss' (потеря контекста текущей фазы).
Формализация требований (yaml + json schema): Подход, при котором спорные требования записываются в исполняемом формате (YAML с приоритетами), а границы допустимого поведения строго описываются в JSON Schema, исключая неоднозначность естественного языка.
Обратный прогон sdd-контура: Проверка исправленной спецификации (fixed-spec) путем полного прохождения цикла Specify → Plan → Tasks → Implement. Считается успешным, если исходный конфликт больше не воспроизводится в задачах и реализации.
Практические упражнения: Название: Создание poisoned/fixed пары для инцидента
Проблема: Учебный кейс appointment_latency. Необходимо создать спецификацию, где требование 'эскалировать P0 за 30 секунд' конфликтует с 'любая эскалация требует ручного подтверждения'. Создайте файлы poisoned-spec.md и fixed-spec.md.
Решение: 1. В poisoned-spec.md создайте два правила с priority=100, которые блокируют друг друга при недоступности владельца. 2. Запишите ожидаемый симптом (например, stage_regress при попытке создать план). 3. В fixed-spec.md добавьте правило p0_time_critical_override с приоритетом выше, чем у ручного подтверждения, и укажите флаг human_audit_required=true для постфактум проверки.
Сложность: intermediate
Название: Фиксация строки восстановления в validation.md
Проблема: Требуется формализовать критерий успешного исправления конфликта приоритетов эскалации для записи в файл validation.md.
Решение: Добавьте в validation.md строку: priority_conflict=false && escalation_path_resolved=P0 && audit_required=true. Это обеспечит машинно-читаемую проверку того, что конфликт устранен, путь эскалации определен, и аудит сохранен.
Сложность: beginner
Название: Написание JSON Schema для правила-исключения
Проблема: Необходимо запретить ИИ-агенту возвращаться к скрытому согласованию для критичных инцидентов. Опишите JSON Schema, которая требует автоэскалацию для P0 при недоступном владельце.
Решение: Используйте конструкцию if/then. В блоке if укажите условия: severity=P0 и owner_unresponsive=true. В блоке then укажите обязательные поля: auto_escalation_channel=critical_phone, human_audit_required=true и reason_code=time_critical_override.
Сложность: advanced
Кейсы: Название: Диагностика роста задержки appointments-api
Сценарий: Резкий рост latency (задержки) маршрута appointments-api в production окружении. Система триажа инцидентов должна автоматически обработать P0 инцидент, однако спецификация содержит противоречивые требования, вызванные стресс-нагрузкой.
Задача: В спецификации одновременно существуют два правила с одинаковым максимальным приоритетом: 'эскалировать P0 за 30 секунд' и 'ждать ручного подтверждения перед любой эскалацией'. Если ответственный недоступен, ИИ-агент (Qwen Code) попадает в бесконечный цикл (ESCALATE_EVENT → WAIT_APPROVAL → VALIDATE_ESCALATION), что приводит к метрике stage_regress и невозможности решить проблему.
Решение: Был применен метод контролируемо дефектной спецификации. Дефект 'priority_conflict' был формализован в YAML. Исправление заключалось во введении правила-исключения 'p0_time_critical_override', которое активируется при severity=P0 и owner_unresponsive=true. Ручная проверка была перенесена в постфактум аудит (human_audit_required=true). Для валидации была написана JSON Schema, жестко задающая допустимый коридор поведения.
Результат: При повторном прогоне контура Specify → Plan → Tasks → Implement цикл был разорван. Задержка больше не блокировалась ожиданием одобрения, а аудит-след сохранялся. Метрика stage_regress упала до 0, строка восстановления в validation.md успешно проходила проверку.
Извлечённые уроки: Дефекты спецификации должны быть явными (в коде и приоритетах), а не спрятанными в комментариях.
Устранение конфликта должно менять само исполняемое правило (requirement), а не только текстовое пояснение.
Любое исправление должно проверяться полным обратным прогоном всего цикла SDD.
Связанные концепции: Конфликт приоритетов
Метрики застревания (stage_regress)
JSON Schema валидация
Советы по изучению: Начинайте с минимального радиуса: внедряйте только один тип дефекта за один прогон. Внедрение нескольких дефектов (цикл + конфликт) сделает трассу неотличимой от хаоса.
Фиксируйте метрики 'ask_storm' и 'stage_regress' вручную в блокноте или validation.md на первых этапах, чтобы развить интуицию поведения ИИ-агента.
Всегда записывайте ожидаемый симптом до запуска анализа, а не подгоняйте результаты под факт.
Переводите спорные места из естественного языка в формат Given/When/Then — это мгновенно подсветит недостающие ветки логики.
При переносе решения в основной проект (capstone) берите с собой только класс дефекта, сам патч и строку восстановления, чтобы не засорять репозиторий.
Дополнительные ресурсы: Github spec kit quickstart: https://github.github.io/spec-kit/quickstart.html — описание фаз Specify → Plan → Tasks → Implement.
Локальный каталог примеров spec ci: examples/spec-ci/README.md — запускаемые аналоги базовых шлюзов спецификации.
Часть 7. отрицательные требования: Базовые концепции ограничений поведения системы из первого тома материалов.
Часть 20. антипаттерны sdd: Каталог классических ошибок спецификаций, на которых базируются инъекции дефектов.
Резюме: Использование контролируемо дефектной спецификации — это мощный метод защиты требований от неоднозначности. Техника позволяет превратить случайные провалы ИИ-агентов в управляемые лабораторные мутации. Успех диагностики строится на четырех китах: один дефект на итерацию, точное измерение симптомов застревания (через ask_storm и stage_regress), формальное разрешение конфликтов (JSON Schema + override) и обязательный обратный прогон полного SDD-контура.