Инструменты и агентское ревью

Разделение ответственности

Агент читает исходные Markdown-файлы и оценивает смысл, полноту, противоречия, архитектурные компромиссы и достаточность проверок. Скрипт проверяет конкретные повторяемые условия. Зелёный lint не заменяет ревью и испытания продукта. Основания выбора формата: ARTIFACTS.md; контрольные поля: FORMAT.md.

Оба каталога самостоятельны. Python 3.11+, зависимости закреплены в requirements-tools.txt. Основной инструмент scripts/reqtool.py использует scripts/markdown_records.py для небольшого набора полей Markdown, scripts/architecture_profile.py для выбранных важных ограничений и scripts/doclinks.py для локальных ссылок. Это точечное чтение полей, а не универсальный парсер/валидатор всего Markdown.

Команды

python scripts/reqtool.py lint
python scripts/reqtool.py lint --ready
python scripts/reqtool.py lint --release
python scripts/reqtool.py lint --json
python scripts/reqtool.py generate
python scripts/reqtool.py generate --check
python scripts/reqtool.py coverage --json
python -m unittest discover -s scripts/tests -v

Lint проверяет декларации и известные связи. --ready дополнительно проверяет согласованность активных REQ, детализацию HLR, объявленные аспекты покрытия, блокирующие вопросы/допущения, рассмотрение областей и незакрытый разбор изменения. --release дополнительно проверяет открытые release-вопросы. Пустой шаблон проходит базовый lint и ожидаемо отклоняется --ready.

Exit 0 — перечисленные условия выполнены; 1 — нарушение; 3 — отсутствует обязательная Python-зависимость. Ни один из этих статусов не подтверждает приёмку продукта.

Что имеет смысл автоматизировать

Решения, пояснения, описание архитектурных взаимодействий и размещения пишутся свободно. Их достаточность, альтернативы, отказы и соответствие исходным гарантиям проверяет агент. Размещение не валидируется как полная инфраструктурная модель, диаграммы не сверяются автоматически с каталогом. Проверки кода, SQL-grants, отказов и нагрузки требуют реализации и результатов конкретной версии.

Отчёты

Generate создаёт только generated/coverage.md и generated/traceability.md. Они вычисляются из уже имеющихся источников и могут использоваться при ревью или как CI artifacts. Generated/ по умолчанию исключён из Git; отдельное обновление отчётов не является обязательным шагом автора. Если проект решит хранить снимки отчётов в Git, --check может контролировать их актуальность.

Generated/coverage.json удалён: coverage --json выдаёт такой же расчёт для программы по запросу. Questions/decisions/stretch-matrix и архитектура никогда не перегенерируются этой командой.

Протяжка

python scripts/reqtool.py impact --changed REQ-RTE-003
python scripts/reqtool.py impact --changed REQ-RTE-003 --review impact/reviews/change.md

Инструмент выводит Markdown-план и может создать новый .md файл с pending-позициями. Существующий файл не перезаписывает. Замените REVIEW-NEW на стабильный ID, разберите позиции и добавьте основания. После добавления зависимостей пересмотрите старые разборы. Автоматический список содержит прямые известные связи; непрямое и предметное влияние анализирует агент по impact/stretch-matrix.md.

CI и OpenSpec

Подготовленный .gitlab-ci.yml запускает lint --ready, формирует два отчёта для artifacts и проверяет инструменты. В шаблоне до заполнения --ready ожидаемо отклоняется. Для небольшого проекта можно выбрать более узкие проверки; ослабление конкретной гарантии требует объяснения в профиле/ревью.

OpenSpec CLI проверяется отдельно; использован 1.14.1:

npx --yes --package @fission-ai/openspec@1.14.1 openspec validate --all --strict --no-interactive
npx --yes --package @fission-ai/openspec@1.14.1 openspec validate --archived --strict --no-interactive

CLI и профиль не заменяют исполнение тестов продукта. Reqtool не применяет deltas, не проверяет всю семантику Markdown, не исполняет продуктовые сценарии и не извлекает все последствия Git diff. Архив и результирующий основной снимок проверяются отдельно.

Специализированные проверки

В заполненном примере scripts/check_analytics_oracles.py пересчитывает эталоны показателей по входным данным. Это повторяемая проверка формул, а не запрос работающего сервиса. Другие предметные линтеры вводите для устойчивого правила с понятной ценой ошибки; у проверки должен быть конкретный вывод и способ исправления. Исключения должны быть локальными и обоснованными.

Каталог верхнеуровневых требований

reqtool читает Markdown в docs/requirements/ рекурсивно. Поддерживает несколько HLR в файле, вложенные области и прежний docs/requirements.md. Assets/attachments и скрытые каталоги исключены; дубли ID между пакетами или прежним файлом отклоняются. Изменение файла пакета включает все содержащиеся HLR в анализ влияния. Значимые внешние источники в sources участвуют в обратных зависимостях; иллюстрация не считается нормативным источником автоматически.

Заготовки feature1/feature2 проходят структурный lint, но --ready отклоняет их draft-статус и отсутствие детализации. Проверка структуры не оценивает смысл изображения/PDF: назначение, версия, роль и согласованность материалов проверяются агентом.

Проверка технологического стека

Технологический стек редактируется в Markdown и проверяется архитектором/агентом: происхождение условий, обязательность, полнота, версии и совместимость. Профиль проверяет только связи архитектурного REQ, решения, CHECK и данных. Инспекцию реального состава поставки, инвентаризации среды и результатов совместимости выполняют в репозитории реализации; поставленный reqtool этого не делает. Для частой проверки допускается инструмент сравнения с зафиксированной версией базиса, без второй вручную поддерживаемой таблицы продуктов.

У сквозного REQ основным ответственным элементом может быть система или единица исполнения; у локального — модуль. Каталоговый контроль принимает эти типы и отклоняет назначение внешнего участника ответственным за внутреннее обязательство.

Рабочие решения проверяются отдельно от окончательных: поле «Рабочее решение» открытого вопроса ссылается на DEC со статусом working, а каждый рабочий DEC связан с открытым вопросом. Working не снимает «Блокирует» и «Этапы: release»; --ready и --release сохраняют проверки этих полей. Proposed/working в поле финального решения не закрывают вопрос. Правила и примеры оформления: шаблон вопроса и шаблон решения. Анализ влияния связывает изменение вопроса с его требованиями и текущим решением; изменение рабочего или финального решения — с соответствующим вопросом. Эти связи формируют позиции разбора влияния и не меняют статусы автоматически.