Редактирование и доработка изменения

Каждый артефакт изменения — это обычный 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, обдумайте её и подготовьте более точное предложение. См. Сначала исследуйте.
• Начните заново. Если цель принципиально изменилась, новое изменение может быть понятнее, чем исправление старого.

Для последнего варианта ниже есть отдельное руководство.

Когда обновить изменение, а когда создать новое

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

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

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

Несколько слов о задачах

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

Что дальше

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