Выбор формы артефактов
Критерий
Начинайте с редактируемого Markdown и проверки агентом. Агентское ревью подходит для смысла, полноты, альтернатив и архитектурных компромиссов. Добавляйте скрипт для конкретного повторяемого условия или высокой цены ошибки. Строгий формат нужен прежде всего машинному потребителю; наличие удобного JSON-парсера само по себе не является основанием.
Каждая автоматизация должна отвечать на вопросы: кто потребляет поля, как часто проверяются, чем опасна ошибка и дешевле ли её поддержка, чем ручное/агентское ревью. Если ответы неясны, оставьте обычный документ.
Пересмотр всех прежних generated-артефактов
| Прежний артефакт | Решение | Основание |
|---|---|---|
| generated/questions.md | Источник docs/questions.md | Реестр редактируется; генерация не вычисляла новых фактов |
| generated/decisions.md | Источник docs/decisions.md | Причины/альтернативы удобнее писать непосредственно |
| generated/stretch-matrix.md | Источник impact/stretch-matrix.md | Это авторские знания о влиянии изменения |
| generated/architecture/index.md | Источник architecture/README.md | Маршрут чтения и вопросы представлений — авторское описание |
| generated/architecture/context.md | Источник architecture/context.md | Граница системы проверяется смысловым ревью |
| generated/architecture/structure.md | Источник architecture/structure.md | Объяснение состава; определения принадлежат каталогу |
| generated/architecture/runtime.md | Источник architecture/runtime.md | Последовательности и отказы требуют проектного рассуждения |
| generated/architecture/data.md | Источник architecture/data.md | Объясняет границу данных; владельцы определены один раз в каталоге |
| generated/architecture/deployment.md | Источник architecture/deployment.md | Размещение/границы отказа — проектные факты и ограничения |
| generated/architecture/quality.md | Источник architecture/quality.md | Обоснование механизма и достаточность доказательств оценивает агент |
| generated/coverage.md | Оставлен как вычисляемый отчёт | Сводит многие-ко-многим REQ/aspect/CHECK/CASE; помогает находить пробелы |
| generated/traceability.md | Оставлен как необязательный вычисляемый индекс | Навигация по родителям; без ручного дублирования связей |
| generated/coverage.json | Удалён; JSON по запросу | Дублировал тот же расчёт без отдельного потребителя |
Оставшиеся два отчёта не являются обязательными исходниками и по умолчанию не коммитятся. CI может создавать их без действий автора. Основная работа идёт в канонических документах.
Другие артефакты
| Артефакт | Форма и проверки |
|---|---|
| Допущения | docs/assumptions.md; агент оценивает основание, скрипт — блокировки |
| Применимость | docs/applicability.md; агент оценивает обоснование, скрипт — непроверенные области |
| Разбор изменения | impact/reviews/*.md; выводы свободны, известные обязательные позиции проверяются |
| Технологический стек | architecture/technology-stack.md; авторский Markdown архитектора. Проверяются источники, обязательность, версии и совместимость; инвентаризация конкретной поставки может иметь машинный формат |
| Архитектурный каталог | architecture/catalog.md; обычные определения и таблицы. Точечный контроль выбран только для значимых запретов/ссылок |
| Архитектурные runtime/deployment/quality/viewpoints JSON | Удалены; отдельная машинная модель для каждого представления не нужна |
| Контракты JSON Schema | Сохранены: ими валидируются реальные машинные входы |
| Данные тестов JSON | Сохранены: fixtures, формат входа и эталоны потребляют программы |
| Сценарии приёмки Markdown и CHECK-метаданные JSON | Markdown — исходный выбор для читаемого сценария. Собственный JSON-профиль сохранён для регулярного расчёта покрытия в reqtool; он не является исполняемым тестом. Методическая основа и выбор формата: GUIDE.md, раздел «Подход к сценариям приёмки» |
| Метаданные REQ внутри Markdown | Сохранены для автоматизируемой части. Они не заменяют нормативный текст |
| Настройка профиля и CI | Сохранён машинный формат: это конфигурация программы |
Работа агента
Сначала определить потребность, риски и согласованную гарантию. Затем отредактировать исходный документ, проверить затронутые требования/сценарии/данные и связать решение с основанием. При архитектурном изменении проверить, как оно влияет на контракты, состояние, отказные ветки, доступ к данным и размещение.
Ревью должно оставить конкретный вывод и ссылки на основания. Скрипты дополняют это проверкой выбранных инвариантов. Отсутствие ошибки линтера не заменяет рассуждение, а свободный Markdown не означает отсутствие ответственности за проверку.