Редактирование и итерация по изменению

Любой артефакт в изменении — это обычный Markdown-файл, который можно редактировать в любое время. Нет заблокированной «фазы планирования», нет контрольного пункта утверждения, нет специального режима редактирования, в который нужно входить. Хотите изменить предложение после начала разработки? Откройте proposal.md и внесите изменения. Поняли, что в реализации есть ошибка в проектировании? Исправьте design.md и продолжайте работу. Это и есть весь ответ, и так задумано изначально.

Эта страница для тех случаев, когда вы думаете: «подожду, а можно вернуться и это изменить?» Да. Вот как это сделать для каждого распространенного сценария.

Два способа редактировать что угодно

У вас всегда есть оба варианта:

1. Редактируйте файл напрямую. Артефакты — это обычные Markdown-файлы, расположенные в директории openspec/changes/<name>/. Откройте proposal.md, design.md, tasks.md или дельта-спецификацию в поддиректории specs/ в вашем редакторе и внесите изменения. Ничего больше не требуется.
2. Попросите ваш ИИ переработать артефакт. В чате просто сформулируйте, что вы хотите: «Обнови предложение, чтобы убрать идею с кэшированием и добавить раздел с ограничением частоты запросов», или «в проектировании нужно использовать очередь, а не опрос». ИИ отредактирует артефакт за вас, используя остальную часть изменения как контекст.

Используйте тот вариант, который подходит для текущей ситуации. Небольшая правка формулировки? Редактируйте файл. Серьезный пересмотр подхода? Позвольте ИИ переработать артефакт с полным контекстом.

«Как обновить предложение (или спецификации) после начала работы?»

Просто обновите их. То же самое изменение, но доработанное.

Если вы используете расширенные команды, естественный порядок работы такой: отредактируйте артефакт, затем запустите /opsx:continue, чтобы продолжить с нового состояния, или /opsx:apply, чтобы продолжить реализацию по обновленному плану. Если вы используете стандартные команды из набора core, отредактируйте артефакт и запустите /opsx:apply; команда считывает актуальные файлы, поэтому реализация ведется в соответствии с тем, что сейчас указано в артефактах.

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

Вы: Я хочу изменить подход в этом изменении.

Вы: [отредактируйте design.md, или дайте указание ИИ:]
     Обновите design.md, чтобы использовать фоновую задачу вместо синхронного вызова.

ИИ:  design.md обновлен. Список задач все еще подходит, хотите, чтобы я продолжил применение?

Вы: /opsx:apply

Это отвечает на очень распространенный вопрос: отдельной команды «обновить предложение» не существует, потому что она не нужна. Файл является единственным источником правды, и его редактирование (вручную или через ИИ) и есть обновление.

«Как вернуться к проверке после завершения реализации?»

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

Конкретно, после некоторой работы с помощью /opsx:apply:

• Хотите повторно изучить план? Откройте артефакты и прочитайте их, или запустите openspec show <change> в терминале, чтобы получить сводный вид.
• Нашли что-то, что нужно изменить? Отредактируйте артефакт (или попросите сделать это ИИ), затем продолжайте работу.
• Хотите провести структурированную проверку соответствия кода плану? Запустите /opsx:verify (расширенная команда). Она сообщает о полноте, корректности и согласованности без блокировки любых процессов. См. Рабочие процессы: Проверка.

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

«Я редактировал код вручную. Как привести его в соответствие с OpenSpec?»

Это происходит постоянно, и это нормально. Вы что-то подкорректировали в редакторе, и теперь код и артефакты не совпадают. Приведите их в синхронизацию в том направлении, которое соответствует действительности:

• Код теперь корректный, спецификация устарела. Обновите дельта-спецификацию (и задачи, если это актуально), чтобы описать поведение, которое вы фактически выпустили. Спецификация должна соответствовать фактическому состоянию дел перед архивацией, потому что при архивации спецификация сливается с вашим единственным источником правды.
• Спецификация корректная, код отклонился от требований. Продолжайте разработку или исправление, пока код не будет соответствовать спецификации.

Быстрый способ выявить несоответствия — запустить /opsx:verify: команда считывает ваши артефакты и код и сообщает, где они расходятся. Считайте ее вывод списком задач для приведения в соответствие, затем заархивируйте изменение, когда они совпадут.

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

Доработка предложения, которое вас не устроило

Если сгенерированное предложение не попадает в цель, у вас есть три хороших варианта действий:

• Итерируйте на месте. Скажите ИИ, что именно не так («область действия слишком широкая, убери функции для администраторов») и позвольте ему переработать предложение. Это самый дешевый вариант, и обычно он работает.
• Сначала изучите идею, затем сгенерируйте новое предложение. Если проблема в том, что сама идея неясна, вернитесь к шагу /opsx:explore, всесторонне продумайте ее, и из этого выйдет более точное предложение. См. Сначала изучите идею.
• Начните с нуля. Если исходное намерение коренным образом изменилось, новое изменение может быть понятнее, чем исправление старого.

Последний вариант имеет собственное руководство по принятию решений, оно находится ниже.

Когда обновлять существующее изменение, а когда создавать новое

Краткая версия: обновляйте, если это та же работа в доработанном виде; создавайте новое, если исходное намерение коренным образом изменилось или область действия разрослась до совершенно другой работы.

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

Полная блок-схема и рабочие примеры по этому вопросу находятся в разделе Рабочие процессы: Когда обновлять, а когда начинать с нуля, а более подробное описание — в OPSX: Когда обновлять, а когда начинать с нуля.

Примечание по задачам

tasks.md — это живой контрольный список, а не замороженный план. В процессе реализации вы можете добавлять обнаруженные задачи, удалять те, что оказались не нужны, или менять их порядок. ИИ отмечает выполненные пункты во время выполнения /opsx:apply, и при возврате к работе позже он продолжает с первого неотмеченного пункта. Редактирование списка в процессе работы ожидается и является нормальной практикой.

Что изучать дальше

• Рабочие процессы — паттерны, а также руководство по принятию решения «обновить или создать новое»
• Проверка изменения — быстрый обзор плана за две минуты перед началом разработки
• Сначала изучите идею — раздел, в который можно вернуться, если нужно переосмыслить идею
• Команды — подробное описание /opsx:continue, /opsx:apply и /opsx:verify
• Концепции: Артефакты — назначение каждого артефакта