Проверка изменения
Вся суть обещания OpenSpec заключается в том, что вы и ваш ИИ договариваетесь о том, что нужно разработать, до написания любого кода. Это соглашение имеет смысл только если вы действительно прочитаете то, что подготовил ИИ. На этой странице описано, как потратить эти две минуты: что открывать, в каком порядке и на что обращать внимание.
Ставка простая: исправить ошибное направление в плане из одного абзаца практически не стоит усилий. Исправить ту же ошибку в 300 строках кода — уже нет. Проверка — это то место, где вы получаете выигрыш от этой ставки.
Два момента для проверки
Их ровно два:
/opsx:propose ──► REVIEW THE PLAN ──► /opsx:apply ──► REVIEW THE CODE ──► /opsx:archive
(before any code) (/opsx:verify)- После выполнения
/opsx:propose(или/opsx:ff), до/opsx:apply— читайте план, пока он состоит только из слов. - После сборки с помощью
/opsx:verify— проверьте, что код действительно сделал то, что было указано в плане.
Первая проверка дает наибольшую пользу, и именно ее чаще всего пропускают. На этой странице мы посвятим ей большую часть внимания.
Порядок чтения файлов
Изменение представляет собой папку с обычными Markdown-файлами в openspec/changes/<name>/. Читайте файлы в таком порядке, чтобы можно было закончить как можно раньше, если в них есть ошибки:
openspec/changes/add-dark-mode/
├── proposal.md 1. the intent and scope ← if this is wrong, stop here
├── specs/…/spec.md 2. the requirements ← the heart of the review
├── design.md (only for bigger changes) — the technical approach
└── tasks.md 3. the plan of workВам не нужно читать каждую строку. Вам нужно ответить на три вопроса, по одному на каждый файл.
Предложение: это правильная проблема?
Сначала откройте proposal.md. В нем описаны «зачем» и «что» — назначение, область применения и подход в одном-двух абзацах.
Что считается хорошим результатом: одно четкое назначение, понятная вам область применения и причина, почему это стоит делать именно сейчас.
Красные флаги:
- Оно решает немного другую проблему, чем та, которую вы озвучили.
- Область применения расширилась: вы попросили добавить переключатель темы, а в предложении также затрагивается аутентификация «пока мы уже здесь».
- Оно расплывчато. «Улучшить страницу настроек» — это не область применения; «добавить переключатель темной темы, который учитывает предпочтения операционной системы» — уже да.
Вопрос, на который нужно ответить: Соответствует ли это тому, что вы действительно запросили, и не проникает ли что-то лишнее? Если ответ отрицательный — остановитесь, не читайте дальше, исправьте предложение (см. Отстаивать свою позицию).
Дельта-спецификации: правильно ли определено понятие «готово»?
Это основная часть проверки. Дельта-спецификации в папке specs/ описывают, что будет верно после выпуска изменения: требования и сценарии, которые их подтверждают:
markdown
## ADDED Requirements
### Requirement: Dark Mode Toggle
The system SHALL let a user switch between light and dark themes.
#### Scenario: Respects the OS preference on first load
- GIVEN a user who has never set a theme
- WHEN they open the app on a device set to dark mode
- THEN the app renders in dark modeЧто считается хорошим требованием: одно четкое утверждение с SHALL/MUST, которое можно передать тестировщику, и как минимум один сценарий, в котором блоки GIVEN/WHEN/THEN действительно проверяют это утверждение.
Красные флаги:
- Расплывчатое требование. «Система ДОЛЖНА быть быстрой» нельзя реализовать или протестировать. Что значит «быстрая»?
- Требование без сценария или сценарий, который не проверяет требование, под которым он находится.
- Самая ценная находка из всех: то, что отсутствует. ИИ точно записывает то, что вы сказали. Ваша задача — заметить то, что вы забыли упомянуть. Если для вас важнее всего случай с предпочтениями ОС, а в сценариях о нем нет, значит проверка уже окупила себя.
Читая дельта-спецификации, задавайте себе вопрос: буду ли я доволен, если система сделает именно это — и только это? Здесь еще нет упоминаний о коде, поэтому изменения будут дешевыми.
Задачи: разумный ли план работ?
tasks.md открывайте последним. Это чек-лист реализации, по которому будет работать ИИ.
Что считается хорошим результатом: упорядоченные шаги, каждый из которых можно отследить до конкретного требования, без неясных моментов.
Красные флаги:
- Задача без соответствующего требования (откуда она взялась?).
- Одна огромная задача «реализовать функцию», которая скрывает все реальные решения.
- Задача, которая затрагивает что-то за пределами области применения, которую вы только что утвердили.
Здесь вам не нужно оценивать сроки или заниматься микроменеджментом — вы просто проверяете, что план соответствует уже утвержденным требованиям.
Отстаивать свою позицию дешево
Если ответ на любой из трех вопросов оказался отрицательным, скажите об этом. Нет никаких фаз и ничего не заблокировано — вы исправляете это и двигаетесь дальше. Два способа сделать это, точно как в разделе Редактирование изменения:
- Отредактируйте файл самостоятельно. Это обычный Markdown: измените строку с областью применения, уточните требование, удалите задачу.
- Скажите ИИ, что не так и позвольте ему внести исправления: «убери изменения, связанные с аутентификацией — они за scopeом», «добавь сценарий для случая, когда пользователь уже выбрал тему», «разбей задачу 3 на схему данных и пользовательский интерфейс».
Затем перечитайте измененную часть. Перерабатывайте документ, пока не получите план, за который вы готовы подписаться. Именно этот обмен правками и есть работа над продуктом.
После написания кода: проверка
После того как работа собрана, /opsx:verify — это ваша вторая проверка. Она повторно читает артефакты и код, и сообщает о несоответствиях по трем направлениям:
| Направление | Что проверяется |
|---|---|
| Полнота | Все задачи выполнены, все требования реализованы, все сценарии покрыты |
| Корректность | Реализация соответствует назначению спецификации, обработаны крайние случаи |
| Согласованность | Проектные решения действительно отражены в коде |
You: /opsx:verify
AI: Verifying add-dark-mode...
COMPLETENESS
✓ All 8 tasks in tasks.md are checked
✓ All requirements in specs have corresponding code
⚠ Scenario "Respects the OS preference on first load" has no test coverageОна помечает проблемы как КРИТИЧЕСКИЕ, ПРЕДУПРЕЖДЕНИЯ или ПРЕДЛОЖЕНИЯ, и не блокирует архивацию — она только выявляет пробелы, а решение остается за вами. Это разница между вопросами «написал ли ИИ код» и «сделал ли он то, что мы договорились».
/opsx:verify доступен в расширенном профиле. Если у вас его нет, включите его с помощью команды openspec config profile (затем выполните openspec update), или просто перечитайте изменение и его diff самостоятельно.
Адаптируйте проверку под размер изменения
Не каждое изменение требует полной проверки. Исправление опечатки в одном файле заслуживает двадцатисекундного просмотра. Изменение, которое затрагивает аутентификацию, платежи или данные, которые нельзя восстановить, заслуживает ответа на все вопросы выше. Речь никогда не шла о формальностях — нужно тратить внимание там, где ошибка будет дорого стоить, и просматривать бегло там, где она не несет риска.
Двухминутный чек-лист
- [ ] Назначение предложения соответствует тому, что вы запросили.
- [ ] В область применения не проникло ничего лишнего.
- [ ] Каждое требование достаточно конкретное, чтобы его можно было протестировать.
- [ ] У каждого требования есть сценарий, который его реально проверяет.
- [ ] Самый важный для вас случай покрыт.
- [ ] Задачи соответствуют требованиям, нет неясных моментов или задач за пределами области применения.
- [ ] Вы будете спокойны, если ИИ реализует именно это и ничего больше.
Если все семь пунктов пройдены, запускайте /opsx:apply с уверенностью. Если какой-то не пройден — это не неудача, это две минуты, которые выполнили свою работу.
Дальнейшие шаги
- Написание качественных спецификаций — обратная сторона: как формулировать требования и сценарии, которые стоит утверждать.
- Редактирование и итерация изменения — механика изменения плана после того, как вы начали работу.
- Рабочие процессы — как проверка вписывается в общий цикл работы.