Тема: Прикладная часть 7. Specification CI: спецификация как исполняемый артефакт
Уровень сложности: Средний
Расчётное время изучения: 3-4 часа
Предварительные требования: Понимание принципов работы CI/CD (например, GitHub Actions)
Опыт работы с Markdown и JSON
Базовые знания Python для модификации скриптов проверки
Знакомство с концепциями требований (requirements) и планов (plans) в разработке
Цели обучения: Настроить конвейер CI для автоматической валидации спецификаций (requirements.md, plan.md).
Реализовать проверку покрытия (Coverage Check) для связи требований (REQ-*) с задачами плана.
Создать валидацию JSON Schema для фикстур, извлеченных из validation.md, включая проверку отрицательных тестов.
Формировать понятные диагностические сообщения об ошибках CI, указывающие на файл, строку и действие для исправления.
Применять Spec CI для валидации атомарных планов агентных систем (AoT-шлюз).
Обзор: Этот учебный гайд посвящен превращению статической документации (спецификаций) в исполняемые артефакты, проверяемые в рамках CI/CD. Мы рассмотрим, как с помощью GitHub Actions и скриптов Python автоматизировать проверку качества спецификаций. Основная идея заключается в создании 'шлюза спецификации' (Spec Gate), который блокирует слияние (Merge) Pull Request при наличии нарушений: непокрытых требований, выхода за границы домена (Scope) или ошибок в JSON-фикстурах. Подход основан на принципе: спецификация полезна только тогда, когда её можно отклонить автоматически.
Ключевые концепции: Шлюз спецификации (spec gate): Обязательный этап в CI, который проверяет спецификацию так же строго, как обычные тесты проверяют код. Он блокирует слияние PR при обнаружении семантических или структурных ошибок в документации.
Проверка покрытия (coverage check): Процесс валидации графа связей между requirements.md и plan.md. Каждое требование (REQ-) должно иметь реализующую задачу в плане (implements: [REQ-]), а каждая задача должна быть связана с требованием (отсутствие 'rogue tasks').
Проверка области охвата (scope check): Валидация того, что действия в plan.md соответствуют разрешенным операциям доменной модели (например, incident-response.yaml). Блокирует 'посторонние' сценарии, такие как несанкционированное автоматическое закрытие инцидента.
Проверка схемы (schema check): Извлечение JSON-примеров (фикстур) из validation.md и их проверка на соответствие JSON Schema. Включает проверку как позитивных (должны проходить), так и негативных (должны предсказуемо падать) сценариев.
Aot-шлюз (atom of thought gate): Специфичная проверка для планов, генерируемых AI-агентами. План представляется в виде графа атомарных действий, который валидируется на предмет неизвестных инструментов, циклов зависимостей и выхода за рамки домена до начала исполнения.
Практические упражнения: Название: Локальная проверка покрытия требований
Проблема: У вас есть файлы requirements.md и plan.md. Требуется убедиться, что все требования из requirements.md имеют соответствующие задачи в plan.md, и что нет 'осиротевших' (rogue) задач. Запустите локальный прогон скрипта проверки покрытия.
Решение: 1. Перейдите в каталог примера: cd book2/examples/spec-ci. 2. Запустите скрипт: python3 scripts/check_coverage.py --requirements requirements.md --plan plan.md. 3. Убедитесь, что скрипт вернул код 0 (успех) и вывел сообщение об успешном покрытии всех REQ-* идентификаторов.
Сложность: beginner
Название: Валидация JSON Schema и отрицательные тесты
Проблема: Необходимо проверить JSON-фикстуры инцидентов против схемы incident_payload.schema.json. Одна из фикстур преднамеренно неверная (отсутствует incident_id). Нужно убедиться, что скрипт правильно её отклоняет.
Решение: 1. Находясь в book2/examples/spec-ci, выполните: python3 scripts/validate_schema.py --schema schemas/incident_payload.schema.json --fixtures fixtures. 2. Проверьте вывод: валидная фикстура должна пройти, а для невалидной должно быть выведено сообщение об ошибке (например, 'missing required property incident_id'). 3. Убедитесь, что процесс завершился корректно, сигнализируя о найденном расхождении.
Сложность: intermediate
Название: Форматирование диагностического сообщения CI
Проблема: Скрипт check_scope.py обнаружил, что в plan.md используется действие 'force_resolve', не разрешенное доменной моделью. Сформируйте JSON-объект ошибки, который соответствует требованиям хорошей диагностики: понятная причина, ссылка на файл, идентификатор правила и действие для исправления.
Решение: JSON-ответ должен выглядеть примерно так: { "status": "failed", "check": "scope", "file": "plan.md", "line": 48, "rule": "IR-SCOPE-007", "reason": "Autonomous force resolve is outside the incident-response domain model", "action": "Replace with POST /incidents/{id}/ack or add an approved requirement and domain rule" }
Сложность: intermediate
Название: Валидация агентного плана (AoT)
Проблема: Агент сгенерировал план в формате JSON, содержащий массив atoms. Создайте правило (или концепцию скрипта) для отклонения плана, если атом ссылается на несуществующий инструмент 'delete_database'.
Решение: Скрипт должен считывать поле 'name' каждого атома и сравнивать его со списком разрешенных инструментов (whitelist) из доменной модели. Если 'delete_database' отсутствует в whitelist, скрипт должен вернуть ошибку.fail и JSON-диагностику вида: {'reason': 'Unknown tool', 'action': 'Remove atom or update domain model'}.
Сложность: advanced
Кейсы: Название: Блокировка несанкционированного закрытия инцидента
Сценарий: Команда разрабатывает автоматизацию инцидентного менеджмента. Разработчик создает Pull Request, добавляя новый шаг в plan.md для автоматического разрешения инцидента (force-resolve) без подтверждения дежурного инженера, чтобы 'ускорить' процесс.
Задача: Текстовое ревью может пропустить это изменение, если оно формально привязано к требованию. Однако такое действие нарушает бизнес-логику и безопасность процесса (может скрыть критический сбой).
Решение: Внедрен шлюз спецификации Spec CI с проверкой области охвата (Scope Check). Скрипт check_scope.py сопоставил действие 'force_resolve' с доменной моделью incident-response.yaml и обнаружил, что данная операция не разрешена для автономных систем.
Результат: GitHub Actions заблокировал слияние PR. Разработчик получил автоматический комментарий с указанием файла (plan.md), строки и правила, запрещающего автономное закрытие. Опасная логика не попала в production.
Извлечённые уроки: Проверка текста требования недостаточна; необходимо проверять семантику действий.
Автоматизация ревью спецификаций снижает нагрузку на команду и предотвращает 'человеческий фактор'.
Шлюз должен проверять не только наличие ссылки (coverage), но и содержание (scope).
Связанные концепции: Scope Check
Domain Model
Pull Request Protection
Название: Интеграция с Grafana: защита контракта полезной нагрузки
Сценарий: Проект интегрируется с системой мониторинга (например, Grafana) через вебхуки. В validation.md хранятся примеры JSON-полезной нагрузки (payload), которые используются для тестирования интеграции.
Задача: При обновлении контракта API Grafana изменила формат поля 'source' или удалила 'incident_id'. Разработчик обновил код, но забыл обновить документацию и тестовые примеры. Это могло привести к 'тихой' регрессии, когда алерт приходит, но не обрабатывается.
Решение: Использование проверки Schema Check. Скрипт extract_fixtures.py извлек JSON-блоки из validation.md, а validate_schema.py проверил их против актуальной схемы incident_payload.schema.json.
Результат: CI упал на этапе Spec Gate. Команда увидела ошибку: 'validation.md:72 missing required property incident_id'. Документация и фикстуры были обновлены до слияния кода, что предотвратило сбой интеграции в production.
Извлечённые уроки: Спецификация должна быть 'исполняемой' — проверяемой автоматически при каждом изменении.
Негативные примеры (контрпримеры) так же важны, как и позитивные, для проверки строгости схемы.
Интеграционные контракты не должны быть 'договоренностью', они должны валидироваться машиной.
Связанные концепции: JSON Schema Validation
Fixtures
Negative Testing
Советы по изучению: Начинайте с локального запуска: Прежде чем настраивать сложный GitHub Actions workflow, убедитесь, что скрипты check_coverage.py и validate_schema.py работают корректно в вашей локальной среде (cd book2/examples/spec-ci).
Фокус на диагностике: Уделите особое внимание формату вывода ошибок. Главная ценность Spec CI — не в том, чтобы 'указать на ошибку', а в том, чтобы подсказать, как её исправить (файл, строка, правило, действие).
Используйте отрицательные фикстуры: Практикуйтесь в создании схем, которые строго отклоняют неверные данные. Если неверная полезная нагрузка проходит схему, значит схема слишком мягкая.
Свяжите слои документации: Помните, что требования, план и валидация — это связанные слои. Изменение в requirements.md должно вызывать проверку того, покрыто ли оно в plan.md.
Дополнительные ресурсы: Github spec kit: Репозиторий GitHub, демонстрирующий подход SDD (Specification-Driven Development), где требования и планы становятся проверяемыми слоями.
Json schema documentation: Официальная документация JSON Schema, необходимая для понимания того, как строить строгие контракты для валидации фикстур.
Course materials part 9 & 16: Исходные части курса (Feature Validation и Team Code Review), описывающие ручные процессы, которые автоматизируются в данной главе.
Резюме: Спецификация CI (Spec CI) превращает документацию в исполняемый артефакт, который проверяется так же строго, как код. Внедрение автоматического шлюза (Spec Gate) в CI/CD блокирует слияние изменений при отсутствии связей между требованиями и планом, при выходе за рамки доменной модели или при несоответствии JSON-полезной нагрузки схеме. Это смещает фокус с субъективного ревью текста на машинную валидацию структуры и семантики, обеспечивая воспроизводимость и безопасность инцидентного конвейера.