Проверка изменения

Главное обещание OpenSpec — вы и ИИ договариваетесь о том, что нужно создать, ещё до написания кода. Эта договорённость имеет смысл, только если вы действительно прочитаете подготовленный ИИ черновик. На этой странице объясняется, как потратить на это две минуты: что открыть, в каком порядке и на что обратить внимание.

Идея проста: исправить неверный шаг в плане из одного абзаца почти ничего не стоит, а в 300 строках кода — совсем другое дело. Именно проверка позволяет воспользоваться этим преимуществом.

Два момента для проверки

Их ровно два:

/opsx:propose ──► ПРОВЕРЬТЕ ПЛАН ──► /opsx:apply ──► ПРОВЕРЬТЕ КОД ──► /opsx:archive
                  (до написания кода)                    (/opsx:verify)

1. После /opsx:propose (или /opsx:ff), до /opsx:apply — прочитайте план, пока он ещё состоит только из слов.
2. После реализации, с помощью /opsx:verify — проверьте, действительно ли код делает то, что указано в плане.

Первая проверка экономит больше всего времени, но её часто пропускают. Поэтому в этом руководстве основное внимание уделено именно ей.

Читайте в таком порядке

Изменение — это папка с обычными Markdown-файлами в openspec/changes/<name>/. Читайте файлы в таком порядке, чтобы как можно раньше остановиться, если обнаружите проблему:

openspec/changes/add-dark-mode/
├── proposal.md      1. цель и область работ  ← если они неверны, остановитесь
├── specs/…/spec.md  2. требования            ← главное в проверке
├── design.md        (только для крупных изменений) — технический подход
└── tasks.md         3. план работы

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

Предложение: правильно ли определена проблема?

Сначала откройте proposal.md. В нём описано «зачем» и «что»: цель, область работ и подход в одном-двух абзацах.

Хороший вариант: ясная цель, понятная область работ и объяснение, почему это стоит делать сейчас.

Повод насторожиться:

• Решается немного другая проблема, чем та, о которой вы просили.
• Область работ разрослась: вы просили добавить переключатель темы, а предложение заодно затрагивает авторизацию.
• Описание расплывчато. «Улучшить страницу настроек» — не область работ; «добавить переключатель тёмной темы с учётом предпочтений ОС» — область работ.

Вопрос, на который нужно ответить: Соответствует ли предложение моему запросу и не добавилось ли в него что-то лишнее? Если нет, остановитесь и исправьте предложение, не читая дальше (см. Возражения обходятся недорого).

Дельты спецификаций: правильно ли определено состояние «готово»?

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

## ADDED Requirements

### Требование: переключатель тёмной темы
Система SHALL позволять пользователям переключаться между светлой и тёмной темами.

#### Сценарий: учёт предпочтения ОС при первой загрузке
- GIVEN: пользователь ещё не выбирал тему
- WHEN: он открывает приложение на устройстве, настроенном на тёмный режим
- THEN: приложение отображается в тёмном режиме

Хорошее требование: ясное утверждение с SHALL/MUST, которое можно передать тестировщику, и хотя бы один сценарий, в котором условия GIVEN/WHEN/THEN действительно проверяют это утверждение.

Повод насторожиться:

• Расплывчатое требование. «Система SHALL работать быстро» нельзя реализовать или проверить. Насколько быстро?
• Требование без сценария или сценарий, не проверяющий соответствующее ему требование.
• Самая ценная находка — то, чего не хватает. ИИ точно записывает то, что вы сказали. Ваша задача — заметить то, о чём вы забыли упомянуть. Если для вас важнее всего учёт предпочтений ОС, но ни один сценарий этого не отражает, значит, проверка себя окупила.

Читайте дельты с вопросом: буду ли я доволен, если система будет делать именно это — и ничего сверх этого? Пока речь не о коде, внести изменения по-прежнему просто.

Задачи: реалистичен ли план работы?

Последним откройте tasks.md. Это контрольный список реализации, по которому будет работать ИИ.

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

Повод насторожиться:

• Задача, которой не соответствует ни одно требование (откуда она взялась?).
• Одна огромная задача «реализовать функцию», скрывающая все важные решения.
• Задача, затрагивающая то, что выходит за рамки одобренного вами плана.

Здесь не нужно оценивать трудозатраты или управлять каждым шагом — лишь проверьте, что план соответствует принятым вами требованиям.

Возражения обходятся недорого

Если ответ на любой из трёх вопросов отрицательный, скажите об этом. Этапов и блокировок нет: исправьте проблему и продолжайте. Есть два способа, как и в разделе Редактирование изменения:

• Отредактируйте файл самостоятельно. Это обычный Markdown: измените формулировку области работ, уточните требование или удалите задачу.
• Объясните ИИ, что не так, и попросите исправить: «Убери изменения авторизации — они вне рамок», «Добавь сценарий для пользователя, который уже выбрал тему», «Раздели задачу 3 на работу со схемой и интерфейсом».

Затем перечитайте изменённую часть. Продолжайте редактировать, пока не получите план, под которым готовы подписаться. Такая совместная работа и есть суть OpenSpec.

После написания кода: проверка

После реализации /opsx:verify поможет провести вторую проверку. Команда повторно читает артефакты и код, а затем сообщает о несоответствиях по трём направлениям:

Направление	Что проверяется
Полнота	Выполнены все задачи, реализованы все требования и учтены сценарии
Корректность	Реализация соответствует цели спецификации и учитывает граничные случаи
Согласованность	Решения, описанные в проекте, действительно отражены в коде

Вы: /opsx:verify

ИИ:  Проверяю add-dark-mode...

     ПОЛНОТА
     ✓ Отмечены все 8 задач в tasks.md
     ✓ Для всех требований в specs есть соответствующий код
     ⚠ Сценарий «учёт предпочтения ОС при первой загрузке» не покрыт тестами

Команда помечает проблемы как CRITICAL, WARNING или SUGGESTION и не блокирует архивацию: она показывает пробелы, а решение оставляет за вами. Так можно понять не только «написал ли ИИ код», но и «создал ли он то, о чём мы договорились».

/opsx:verify входит в расширенный профиль. Если команды нет, включите профиль с помощью openspec config profile (затем выполните openspec update) или самостоятельно перечитайте изменение и diff.

Соразмеряйте проверку изменению

Не для каждого изменения нужна полная проверка. Исправление опечатки в одном файле можно бегло просмотреть за двадцать секунд. Изменение авторизации, платежей или невосстановимых данных заслуживает внимания ко всем вопросам выше. Цель не в соблюдении формальностей, а в том, чтобы уделять внимание там, где ошибка дорого обойдётся, и бегло просматривать остальное.

Двухминутный контрольный список

• Цель предложения соответствует моему запросу.
• В область работ не проникло ничего лишнего.
• Каждое требование достаточно конкретно, чтобы его можно было проверить.
• Для каждого требования есть сценарий, который действительно его проверяет.
• Самый важный для меня случай учтён.
• Задачи соответствуют требованиям; нет непонятных задач или задач вне рамок.
• Я буду доволен, если ИИ реализует именно это и ничего сверх этого.

Если все семь пунктов выполнены, смело запускайте /opsx:apply. Если нет — это не неудача: значит, эти две минуты сработали как надо.

Что дальше

• Как писать хорошие спецификации — другая сторона процесса: подготовка достойных одобрения требований и сценариев.
• Редактирование и доработка изменения — как менять план после начала работы.
• Рабочие процессы — место проверки в общем цикле работы.