Учебный гайд: Часть 9. Проверка фичи: от спецификаций к фактам

Урок 2 из 5 в модуле «Часть 9. Проверка фичи: от спецификаций к фактам»

Вы просматриваете урок без входа. Войдите, чтобы сохранять прогресс и проходить тесты.

Тема: Часть 9. Проверка фичи: от спецификаций к фактам

Уровень сложности: Средний

Расчётное время изучения: 4-6 часов (теория 2 часа, практика 2-4 часа)

Предварительные требования: Базовое понимание Git и работы с ветками

Опыт написания тестов (unit/integration)

Знакомство с TypeScript и базовыми командами npm

Понимание клиент-серверной архитектуры (HTTP, REST)

Опыт работы с markdown-документацией

Желательно: знакомство с материалами Частей 1-8 курса (SDD, specs, roadmap)

Цели обучения: Составлять validation.md с чёткими, проверяемыми фактами для любой фичи, отличая факты от пожеланий в прозе

Выбирать оптимальный уровень фактов (примеры, инварианты, свойства, контракты) на основе матрицы рисков по типу фичи

Применять жизненный цикл статусов фактов (черновик → обязательный → реализован → отложен) для контроля качества перед слиянием

Формировать пакет доказательств (evidence bundle) для ревью, включающий статусы фактов, следы команд и результаты ручных проверок

Использовать агенты (Qwen Code) для автоматической сверки кода с validation.md и выявления отклонений спецификации

Обзор: Эта часть курса посвящена критическому переходу от текстовых спецификаций к проверяемым фактам — механизму, который превращает намерения в доказательства готовности фичи к слиянию. Спецификации объясняют, что должно быть сделано, но сами по себе не гарантируют правильную реализацию. Факты — это исполняемые или однозначно проверяемые утверждения, которые машина или человек может подтвердить без повторной интерпретации. Материал охватывает четыре уровня фактов, матрицу рисков для выбора нужной плотности проверок, структуру файла validation.md, жизненный цикл фактов, интеграцию с CI/CD, ручные и автоматические проверки, а также формирование пакета доказательств для ревью. Особое внимание уделяется работе с агентами, пишущими код: поскольку модель может по-разному интерпретировать одну и ту же спецификацию, факты становятся единственным надёжным допуском к слиянию.

Ключевые концепции: Факт: Исполняемое или однозначно проверяемое утверждение, которое не требует интерпретации. Примеры: npm run typecheck завершается с кодом 0; GET / возвращает 200; ответ содержит <h1>AgentClinic</h1>. Противопоставляется пожеланиям в прозе типа «убедись, что страница выглядит хорошо».

Спецификация vs факт: Спецификация направляет разработку, объясняя намерение и границы. Факты допускают к слиянию, предоставляя объективные доказательства. Короткая формула: «Спецификации направляют. Факты допускают к слиянию.»

Четыре уровня фактов: Примеры (конкретные пары вход-выход: один curl, один тест), Инварианты (всегда истинные утверждения: повторный запуск миграции не меняет схему), Свойства (проверка класса случаев: любая оценка вне 1..5 отклоняется), Контракты (предусловие → действие → постусловие: если сессия не аутентифицирована, при GET /dashboard ответ перенаправляет на /login).

Матрица рисков: Инструмент выбора минимально достаточного уровня фактов по типу фичи. Визуальные изменения требуют ручных фактов; миграции данных — инвариантов и свойств; авторизация — свойств и контрактов; платежи — примеров и контрактов. Цель матрицы — выявить пропущенные проверки, а не создать бюрократию.

Validation.md: Центральный артефакт проверки фичи. Содержит набор фактов с командой/проверкой, ожиданием, ответственным (автоматическая/ручная проверка) и статусом. Не контрольный список, а набор фактов для допуска к слиянию.

Жизненный цикл факта: Черновик (предложен, не закреплён) → Обязательный (принят как критерий фичи) → Реализован (есть тест, команда или подтверждение) → Отложен (осознанно перенесён в будущую фазу с объяснением). Помогает не смешивать намерение и доказательство.

Ручной факт: Проверка, выполняемая человеком, но конкретная и однозначная. Слабый пример: «Проверь интерфейс». Сильный: «При ширине 375px страница /feedback показывает поле имени, поле сообщения, кнопку отправки без горизонтальной прокрутки и наложений». Ручные факты обязательны для UI, полезны для тона и доступности.

Пакет доказательств (evidence bundle): Компактный артефакт для ревьюера при слиянии: ссылка на спецификацию, список фактов со статусами, следы запуска команд (коды выхода, вывод), результаты ручных проверок, решения, принятые по ходу реализации, ссылки на коммиты. Ревьюер не должен заново запускать всё — он должен понять, что проверял автор, и при сомнениях точечно перепроверить.

Проверка с участием человека: Агент находит механические несоответствия; человек оценивает продуктовые и архитектурные аспекты: соответствие миссии, разрастание границ, неоговоренные зависимости, понятность структуры для новых разработчиков, наличие фактов для рискованного поведения, решения, оставшиеся только в чате.

Синхронное обновление спецификации, плана и фактов: Когда реализация показывает необходимость новой структуры (например, разделение на Layout/Header/Main/Footer), нужно одновременно обновить plan.md и validation.md, чтобы будущие сессии агента не вернулись к старой интерпретации.

Практические упражнения: Название: Преобразование пожеланий в факты

Проблема: Дана проверка в прозе: «Убедись, что форма обратной связи работает корректно и выглядит нормально на телефоне». Преобразуйте это в 3-4 конкретных факта для validation.md, включая автоматические и ручные проверки. Укажите уровень каждого факта (пример, инвариант, свойство, контракт или ручной факт).

Решение: 1. F1 — Пример: curl -X POST http://localhost:3000/feedback -d '{"name":"Test","message":""}' возвращает 400 Bad Request. Уровень: пример + контракт (пустое сообщение → отклонение).

F2 — Свойство: Любой POST /feedback с оценкой вне диапазона 1..5 возвращает 400, независимо от остальных полей. Уровень: свойство.
F3 — Инвариант: После успешного POST /feedback с валидными данными количество записей в таблице feedback увеличивается ровно на 1, а ответ перенаправляет на /feedback. Уровень: инвариант + контракт.
F4 — Ручной факт: При ширине 375px страница /feedback отображает поле имени (type='text'), поле сообщения (textarea), кнопку отправки (type='submit') и список последних 3 записей без горизонтальной прокрутки, наложений элементов или обрезки текста. Уровень: ручной факт.

Ключевое отличие: каждый факт содержит конкретную команду или условие проверки, ожидаемый результат и критерий успеха, исключающий двойственную интерпретацию.

Сложность: beginner

Название: Применение матрицы рисков

Проблема: Команда разрабатывает следующие фичи: (A) добавление баннера с акцией на главную страницу, (B) миграция базы данных для добавления поля email к таблице users, (C) новый endpoint POST /payments для обработки платежей, (D) валидация формы регистрации с проверкой уникальности email. Для каждой фичи определите, какие уровни фактов обязательны согласно матрице рисков, и объясните, почему.

Решение: A — Баннер (визуальное/UI-изменение): Пример (рендерится корректный HTML) + Ручной факт (визуальная иерархия, читаемость на мобильном). Без ручной проверки невозможно подтвердить визуальное качество.

B — Миграция данных: Инвариант (повторный запуск не меняет схему/не дублирует колонку) + Свойство (миграция применяется идемпотентно для всех существующих записей). Пример недостаточен: нужно гарантировать безопасность данных при масштабе.

C — Платёжный endpoint: Пример (конкретный успешный платёж проходит) + Контракт (при невалидных реквизитах → 400 с конкретной ошибкой; при дублировании idempotency-ключа → 409). Побочные эффекты требуют строгих контрактов.

D — Валидация регистрации: Пример (валидные данные создают пользователя) + Свойство (любой дублирующий email отклоняется) + Контракт (при отсутствии обязательного поля → 400 с указанием отсутствующего поля). Валидация форм требует свойств для классов некорректных входов.

Проверка: если для миграции B указан только пример без инварианта — это сигнал переписать validation.md.

Сложность: intermediate

Название: Создание полного validation.md

Проблема: Разработайте validation.md для фичи «Hello Hono» — минимального веб-приложения на Hono с серверным рендерингом. Фича включает: установку Hono и tsx, маршрут GET /, возвращающий HTML с заголовком AgentClinic, подключение static/style.css, скрипт проверки типов. Используйте жизненный цикл статусов и укажите ответственных за проверку.

Решение: ```markdown

Проверка — Hello Hono

Набор фактов

F1 — TypeScript компилируется

Команда: npm run typecheck
Ожидание: код выхода 0, отсутствие ошибок типизации
Ответственный: автоматическая проверка (CI + локально)
Статус: обязательный → реализован

F2 — Сервер разработки запускается

Команда: npm run dev (фон), затем curl -s http://localhost:3000
Ожидание: HTTP 200, Content-Type содержит text/html
Ответственный: автоматическая проверка
Статус: обязательный → реализован

F3 — HTML содержит ориентир

Команда: curl -s http://localhost:3000 | grep '<h1>AgentClinic</h1>'
Ожидание: ровно одно совпадение, код выхода grep равен 0
Ответственный: автоматическая проверка
Статус: обязательный → реализован

F4 — Статические файлы отдаются

Команда: curl -s -o /dev/null -w '%{http_code}' http://localhost:3000/static/style.css
Ожидание: HTTP 200, тело содержит CSS-правила (проверка через | head -c 100)
Ответственный: автоматическая проверка
Статус: обязательный → реализован

F5 — Структура страницы семантически корректна

Проверка: открыть исходный код ответа (curl -s http://localhost:3000)
Ожидание: наличие тегов <header>, <main>, <footer> в корректной иерархии
Ответственный: ручная проверка разработчика
Статус: обязательный → реализован

F6 — Визуальная целостность на мобильном

Проверка: DevTools, ширина 375px, высота 667px
Ожидание: заголовок, основное содержимое и подвал не перекрываются; горизонтальная прокрутка отсутствует
Ответственный: ручная проверка разработчика
Статус: обязательный → реализован

Критерии готовности

[x] Все автоматические факты (F1-F4) проходят в CI
[x] Ручные факты (F5-F6) проверены локально
[x] Дорожная карта обновлена: фаза Hello Hono отмечена завершённой
[x] Коммиты содержат все изменения specs/ и src/

Обратите внимание: F1-F4 — автоматические, воспроизводимые команды; F5-F6 — ручные, но с конкретными условиями и критериями. Нет ни одного пожелания в прозе.

Сложность: intermediate

Название: Анализ отклонения спецификации

Проблема: При проверке фичи «форма обратной связи» тесты проходят, но реализация: (1) добавляет поле «телефон», не указанное в requirements.md, (2) перенаправляет на /success вместо /feedback после отправки, (3) не валидирует длину сообщения (требовалось ≤500 символов). Составьте запрос к Qwen Code для анализа отклонений и опишите, какие файлы нужно обновить синхронно.

Решение: Запрос к Qwen Code:

/clear Сравни эту ветку с @specs/2026-05-01-feedback-form/validation.md.

Покажи:

факты, которые реализованы и проходят;
факты, которых не хватает (валидация длины сообщения ≤500);
факты, которые неоднозначны и требуют переписывания;
решения в реализации, не описанные в requirements.md (поле «телефон», редирект на /success);
устаревшие утверждения спецификации.

Пока не изменяй файлы.

После анализа синхронное обновление:
1. **requirements.md**: либо добавить обоснование для поля «телефон» и /success, либо вернуть к исходным требованиям.
2. **plan.md**: обновить структуру компонентов, если добавление поля требует нового компонента.
3. **validation.md**: 
   - Добавить F-new: POST /feedback с сообщением >500 символов возвращает 400.
   - Обновить F-redirect: ожидание изменено на /feedback или /success — в зависимости от продуктового решения.
   - Добавить факт для поля телефона, если оно остаётся; или удалить из реализации.
4. **Код**: привести в соответствие с обновлёнными спецификацией и фактами.

Принцип: любое решение, принятое по ходу реализации, должно быть отражено в specs, а не оставаться только в чате или коммит-сообщении.

Сложность: advanced

Название: Формирование пакета доказательств для слияния

Проблема: Подготовьте описание запроса на слияние (пакет доказательств) для фичи «Hello Hono» на основе выполненных упражнений. Включите все обязательные элемент evidence bundle и продемонстрируйте, как ревьюер может точечно перепроверить любой факт.

Решение: ```markdown
## Пакет доказательств: Hello Hono

### Спецификация
- Папка: `specs/2026-05-01-hello-hono/`
- requirements.md: фиксирует намерение (минимальный SSR на Hono)
- plan.md: структура Layout/Header/Main/Footer
- validation.md: 6 фактов (см. ниже)

### Статусы фактов
| ID | Факт | Статус | Подтверждение |
|---|---|---|---|
| F1 | TypeScript компилируется | ✅ подтверждён | `npm run typecheck` → exit 0 |
| F2 | Сервер отвечает 200 | ✅ подтверждён | `curl -s -o /dev/null -w '%{http_code}' http://localhost:3000` → 200 |
| F3 | HTML содержит <h1>AgentClinic</h1> | ✅ подтверждён | `curl -s http://localhost:3000 \| grep '<h1>AgentClinic</h1>'` → match |
| F4 | static/style.css отдаётся | ✅ подтверждён | `curl -s -w '%{http_code}' http://localhost:3000/static/style.css` → 200 |
| F5 | Семантическая структура | ✅ подтверждён | Ручная проверка: исходный код содержит <header>, <main>, <footer> |
| F6 | Мобильная целостность | ✅ подтверждён | Ручная проверка: DevTools 375×667, скриншот прилагается |

### Следы команд

$ npm run typecheck > tsc --noEmit

exit code 0

$ npm run dev & $ curl -s http://localhost:3000 | head -c 200 <!DOCTYPE html><html><head>...<<h1>AgentClinic</h1>...

$ curl -s -w '\nHTTP %{http_code}' http://localhost:3000/static/style.css body { font-family: system-ui; } HTTP 200

### Решения, принятые по ходу реализации
- Добавлен компонент Layout для единообразия: plan.md обновлён, факт F5 добавлен.
- static/style.css подключён через `<link>` в Layout, не inline: план и факты синхронизированы.

### Коммиты
- `a1b2c3d` — feat: Hono setup with SSR
- `e4f5g6h` — feat: Layout/Header/Main/Footer structure
- `i7j8k9l` — docs: validation.md and roadmap update

### Точечная перепроверка для ревьюера

Быстрая проверка всех автоматических фактов:

npm install && npm run typecheck && npm run dev & sleep 2 && curl -s http://localhost:3000 | grep -q 'AgentClinic' && echo 'F3 OK'

Ключевая ценность: ревьюер за 30 секунд понимает, что проверял автор, и может либо принять, либо запустить одну команду для перепроверки, не воспроизводя всё с нуля.

Сложность: advanced

Кейсы: Название: Отклонение миграции без инварианта: потеря данных в стартапе

Сценарий: Команда из 4 разработчиков разрабатывала SaaS-платформу для клиник. Фича «миграция данных» добавляла таблицу patient_records с внешним ключом на users. Разработчик подготовил migration.sql и проверил его один раз локально — работало. В validation.md был только один факт: «Пример: миграция применяется успешно на пустой базе».

Задача: После слияния в staging обнаружилось, что повторный запуск миграции (из-за ошибки в CI-скрипте) создал дублирующую колонку patient_records_id_1 и сломал индексы. Продакшн-деплой был отложен на 3 дня. Откат потребовал ручного вмешательства DBA. Проблема: отсутствие инварианта «повторный запуск не меняет схему» и свойства «миграция идемпотентна для базы с существующими данными».

Решение: Команда ввела обязательную матрицу рисков для всех миграций. Для patient_records переписали validation.md:

F1 (инвариант): npm run migrate:up && npm run migrate:up → схема не изменяется, код выхода 0 оба раза.
F2 (свойство): Для базы с 10K+ пользователей миграция выполняется за <30 секунд без блокировки таблицы.
F3 (пример): После миграции SELECT COUNT(*) FROM patient_records возвращает 0 для новых клиник, корректно считает существующие для мигрированных.
Добавили CI-шаг: запуск миграции дважды с проверкой pg_dump --schema-only | diff -.

Также синхронно обновили plan.md: миграции разделили на pre-deploy (безопасные) и post-deploy (требующие мониторинга).

Результат: Время проверки миграций сократилось с 2 часов ручной проверки до 5 минут автоматической. За 8 месяцев после внедрения не произошло ни одного инцидента с миграцией. Команда смогла деплоить 3 раза в неделю вместо 1 раза в две недели. Ревьюеры стали доверять пакетам доказательств и не перезапускали миграции локально без причины.

Извлечённые уроки: Матрица рисков не бюрократия — она выявляет слепые зоны: миграция с одним примером без инварианта — классический антипаттерн

Инвариант «идемпотентность» для миграций важнее десятков примеров: он покрывает все случаи повторного применения

CI должен проверять именно тот сценарий, который страшен в продакшене, а не только «happy path»

Пакет доказательств снижает когнитивную нагрузку ревьюера — он принимает решение по артефактам, а не по догадкам

Связанные концепции: Матрица рисков

Инвариант

validation.md

Пакет доказательств

Жизненный цикл факта

Название: UI-фича без ручных фактов: регрессия доступности в финтех-приложении

Сценарий: Крупный банк разрабатывал новый экран переводов. Фича включала сложную форму с суммой, получателем и подтверждением. Команда полностью полагалась на автоматизированные тесты: 47 unit-тестов, 12 интеграционных тестов, 100% покрытие ветвлений. validation.md содержал только автоматические факты.

Задача: После релиза поступили жалобы от пользователей с нарушениями зрения: при навигации с клавиатуры фокус терялся на модальном окне подтверждения, а скринридер не озвучивал ошибки валидации. Автотесты проходили, но не проверяли порядок табуляции, aria-атрибуты, контрастность. Регрессия затронула 12% пользователей мобильного приложения в веб-вью. Откат стоил банку репутационных потерь и штрафа регулятора за нарушение требований доступности.

Решение: Команда ввела обязательные ручные факты для всех UI-фич, влияющих на финансовые операции:

F-manual-1: При ширине 320px и 200% масштабе все интерактивные элементы остаются доступны без горизонтальной прокрутки.
F-manual-2: Навигация Tab проходит через все поля формы, кнопку подтверждения и ссылку «Отмена» в логичном порядке, без зацикливания в модальном окне.
F-manual-3: Скринридер NVDA/VoiceOver корректно озвучивает ошибки валидации при потере фокуса на поле.
Для повторяющихся проверок внедрили Playwright с axe-core, но сохранили ручной факт для новых паттернов интерфейса.

Синхронно обновили plan.md: каждый UI-компонент обязан иметь файл accessibility-notes.md с ожидаемым поведением фокуса и скринридера.

Результат: Ручные факты выявили 3 потенциальные регрессии на этапе разработки следующей фичи. Время от разработки до релиза сократилось на 20%, так как меньше багов возвращалось из QA. Регуляторный аудит доступности пройден без замечаний. Команда начала делиться пакетами доказательств с отделом compliance, что ускорило согласования.

Извлечённые уроки: Автоматическое покрытие ≠ качество: 100% ветвлений не гарантирует доступность, которую проверяет только человек

Ручные факты не слабее автоматических, если они конкретны и воспроизводимы

Повторяющийся ручной факт — сигнал к автоматизации через специализированные инструменты (Playwright + axe)

Синхронное обновление plan.md и validation.md предотвращает «дрейф» реализации от намерения при работе с агентами

Связанные концепции: Ручной факт

Матрица рисков (визуальное/UI-изменение)

Проверка с участием человека

Синхронное обновление спецификации, плана и фактов

Название: Работа с агентом: предотвращение дрейфа спецификации в AI-native проекте

Сценарий: Стартап AgentClinic полностью использовал Qwen Code для генерации кода. Фича «детали агента» требовала отображения списка недугов для каждого начального агента. Первоначальная спецификация описывала монолитный компонент страницы. Агент реализовал его корректно, но при повторной сессии (через неделю, другой контекст) начал генерировать другую структуру — без компонента Layout.

Задача: Агент интерпретировал одну и ту же текстовую спецификацию по-разному в разных сессиях. Отсутствие фиксированных фактов в validation.md приводило к тому, что каждая новая сессия «творчески» переосмысляла структуру. Код работал, но архитектура дрейфовала. Ревьюеры тратили время на выявление неявных изменений, не зафиксированных в спецификации.

Решение: Команда ввела строгий процесс:

После первой реализации обновили plan.md: страница = Layout(Header, Main, Footer).
Добавили в validation.md факты, закрепляющие структуру:

F-structure: curl -s http://localhost:3000/agents/1 | grep -E '<(header|main|footer)' → ровно 3 совпадения.
F-css: curl -s -w '%{http_code}' http://localhost:3000/static/style.css → 200.
F-typecheck: npm run typecheck → 0.

Запрос к агенту теперь всегда включал: «Обнови реализацию в соответствии с @specs/.../plan.md и @specs/.../validation.md. Пока не изменяй файлы specs без явного запроса.»
Ввели проверку: git diff --stat main...HEAD + запрос к агенту на сравнение с validation.md перед каждым коммитом.

При обнаружении необходимости изменения структуры использовали синхронный запрос: обновить plan.md, validation.md и реализацию одновременно.

Результат: Дрейф архитектуры прекратился. 90% сессий с агентом генерировали код, совместимый с существующей структурой, без дополнительных правок. Время на ревью сократилось на 60%. Новые разработчики (люди) понимали структуру проекта за минуты, а не часы, благодаря фактам в validation.md, которые служили исполняемой документацией.

Извлечённые уроки: Текстовая спецификация интерпретируется агентом по-разному; факты — единственный стабильный контракт между сессиями

Факт «ответ содержит ориентиры header/main/footer» лучше, чем «страница структурирована правильно» — он проверяется машиной без интерпретации

Синхронное обновление plan.md + validation.md + кода предотвращает «творческий дрейф» агента

Проверка git diff + validation.md перед коммитом создаёт обратную связь, которая обучает агента (и человека) соблюдать контракты

Связанные концепции: Факт

validation.md

Проверка с участием агента

Синхронное обновление спецификации, плана и фактов

Начните с различий

Советы по изучению: Начинайте практику с «инверсии»: берите плохие проверки в прозе и превращайте их в факты — это тренирует «мышление фактами» лучше чтения теории

Используйте матрицу рисков как чек-лист «чего не хватает», а не как обязательный набор: цель — выявить пропуск, а не создать бюрократию

Практикуйтесь с реальными curl-командами: пишите их в терминале, проверяйте коды выхода, копируйте в validation.md — факт должен быть воспроизводимым

Создайте шаблон validation.md для своего проекта и используйте его как стартовую точку для каждой фичи — это снижает порог начала работы

Проводите «аудит фактов» с коллегой: один читает validation.md, другой пытается выполнить проверки, не читая кода — выявляет неоднозначности за минуты

Для работы с агентами сохраняйте историю запросов на сверку с validation.md — они становятся обучающим материалом для новых сессий

Ведите журнал «факт изменён после провала» — явно документированное изменение факта нормальна; скрытое — антипаттерн, который вернётся как технический долг

Переходите от ручных фактов к автоматическим, когда замечаете повторение: трижды проверенный ручной факт — кандидат на Playwright или интеграционный тест

Используйте жизненный цикл статусов для управления ожиданиями стейкхолдеров: «отложен» с объяснением лучше, чем «забытый» факт, который всплывёт перед релизом

Практикуйте формирование пакета доказательств даже для личных проектов — навык структурирования аргументов для ревьюера переносится на любую командную работу

Дополнительные ресурсы: Приложение c к курсу (шаблон пакета доказательств для pr): Официальный шаблон описания запроса на слияние с evidence bundle — использовать как стартовую точку для всех проектов

Часть 20 курса (скрытые изменения фактов как антипаттерн): Углублённый разбор эволюции фактов и управления техническим долгом спецификаций

Playwright documentation (playwright.dev): Инструмент для автоматизации ручных фактов: скриншот-тестирование, проверка доступности, мобильные viewport

Axe-core (deque.com/axe): Библиотека для программной проверки accessibility — кандидат на автоматизацию ручных фактов UI

Hono framework documentation (hono.dev): Контекст фреймворка, используемого в примерах курса — для воспроизведения упражнений

Git documentation: git diff, git status, git log: Основные команды для практики «начните с различий» при проверке фичи

Контрольные вопросы к части 9 (из исходного документа): Самопроверка: 1) Почему спецификация не должна быть единственным допуском? 2) Чем факт отличается от пожелания? 3) Когда ручная проверка — факт? 4) Что делать, если тесты проходят, но реализация не соответствует requirements.md? 5) Почему «спецификации направляют, факты допускают» лучше просто «пишите спецификации лучше»?

Резюме: Проверка фичи — это отдельный режим работы, где текстовая спецификация превращается в проверяемые факты. Спецификации направляют разработку, но только факты допускают к слиянию. Факт — это исполняемое или однозначно проверяемое утверждение, а не пожелание в прозе. Четыре уровня фактов (примеры, инварианты, свойства, контракты) и матрица рисков помогают выбрать минимально достаточную плотность проверок для каждого типа фичи. Центральный артефакт — validation.md с жизненным циклом статусов, отделяющим намерение от доказательства. Ручные факты не слабее автоматических, если конкретны; повторяющиеся ручные проверки — сигнал к автоматизации. При работе с агентами факты критически важны: они преодолевают неоднозначность интерпретации текстовых спецификаций между сессиями. Пакет доказательств (evidence bundle) превращает ревью из догадок в проверку артефактов. Синхронное обновление спецификации, плана и фактов предотвращает дрейф реализации и делает проект понятным для будущих разработчиков и агентов.