Редагування та ітерації змін

Кожен артефакт у зміні — це просто Markdown-файл, який ви можете редагувати в будь-який час. Немає заблокованої «планувальної фази», жодних контрольних точок схвалення, жодного спеціального режиму редагування. Хочете змінити пропозицію після того, як почали будувати? Відкрийте proposal.md та змініть її. Зрозуміли, що дизайн неправильний посередини реалізації? Виправте design.md і продовжуйте. Це повна відповідь, і це навмисно так.

Ця сторінка для того моменту, коли ви думаєте: «Стривай, чи можу я повернутися і змінити це?» Так. Ось як, у кожному поширеному випадку.

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

У вас завжди є обидва варіанти:

1. Редагуйте файл безпосередньо. Артефакти — це звичайний Markdown у openspec/changes/<name>/. Відкрийте proposal.md, design.md, tasks.md або delta spec у specs/ у своєму редакторі та змініть його. Нічого іншого не потрібно.

2. Попросіть AI переглянути його. У чаті просто скажіть, що ви хочете: «Оновіть пропозицію, щоб відмовитися від ідеї кешування та додати розділ із обмеженням швидкості», або «дизайн має використовувати чергу (queue), а не опитування (polling)». AI редагує артефакт за вас, використовуючи решту змін як контекст.

Використовуйте те, що підходить у даний момент. Незначна зміна формулювань? Відредагуйте файл. Суттєве переосмислення? Дозвольте AI відредагувати з повним контекстом.

«Як мені оновити пропозицію (або специфікації) після того, як я почав?»

Просто оновіть її. Та сама зміна, але вдосконалена.

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

Ментальна модель: артефакти — це живий план, а не підписаний контракт. AI завжди працює з їхнім поточним вмістом, тому редагування керує роботою.

You: I want to change the approach in this change.

You: [edit design.md, or tell the AI:]
     Update design.md to use a background job instead of a synchronous call.

AI:  Updated design.md. The task list still fits; want me to continue applying?

You: /opsx:apply

Це відповідає на дуже поширене питання: не існує окремої команди «оновлення пропозиції», тому що вона вам не потрібна. Файл є джерелом істини, і редагування його (вручну або через AI) є оновленням.

«Як мені повернутися до перегляду після реалізації?»

Вам не потрібно «повертатися», бо ви ніколи й не відходили. Робочий процес є гнучким: перегляд, редагування та реалізація — це не послідовні фази, у які ви застрягли.

Конкретно, після деякої роботи з /opsx:apply:

• Хочете ще раз розглянути план? Відкрийте артефакти та прочитайте їх або запустіть openspec show <change> у своєму терміналі для консолідованого вигляду.
• Знайшли щось, що потрібно змінити? Відредагуйте артефакт (або попросіть AI), а потім продовжуйте.
• Хочете структуровану перевірку того, чи код відповідає плану? Запустіть /opsx:verify (розширена команда). Він звітує про повноту, коректність та узгодженість без блокування чогось. Дивіться Workflows: Verify.

Немає «фази перегляду», до якої можна було б повернутися, тому що перегляд — це те, що ви можете робити в будь-який момент, включно з після реалізації.

«Я відредагував код вручну. Як мені це узгодити з OpenSpec?»

Це відбувається постійно, і це нормально. Ви трохи змінили у своєму редакторі, і тепер код та артефакти не збігаються. Зробіть їх синхронними в тому напрямку, який є правдою:

• Код зараз правильний, специфікакація застаріла. Оновіть delta spec (та завдання, якщо це релевантно), щоб описати поведінку, яку ви насправді відправили. Специфікація має відповідати реальності перед архівуванням, оскільки архівування зливає специфікацію у ваше джерело істини.
• Специфікація правильна, код "відхилив"ся. Продовжуйте будувати або виправляти, доки код не збігнеться зі специфікацією.

Швидкий спосіб виявити розбіжності — це /opsx:verify: він читає ваші артефакти та ваш код і повідомляє, де вони відрізняються. Розглядайте його вивід як список завдань для узгодження, а потім архівуйте, коли вони згодні.

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

Удосконалення пропозиції, яка вас не влаштовує

Якщо згенерована пропозиція не відповідає очікуванням, у вас є три хороші варіанти:

• Ітеруйте на місці. Скажіть AI, що не так («обсяг занадто широкий, відмовтеся від адміністративних функцій») і дозвольте йому переглянути. Найдешевший і зазвичай правильний варіант.
• Спочатку дослідіть, а потім знову запропонуйте. Якщо проблема в тому, що сама ідея нечітка, поверніться до /opsx:explore, обдумайте це і дозвольте більш чіткій пропозиції виникнути з цього. Дивіться Explore First.
• Почніть з нуля. Якщо намір кардинально змінився, нова зміна може бути зрозумілішою, ніж латання старої.

Цей останній крок має власний посібник із прийняття рішень, далі.

Коли оновлювати, а коли починати нову зміну

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

• Та сама мета, кращий підхід? Оновіть.
• Зменшення обсягу (відправити MVP зараз, більше пізніше)? Оновіть, потім архівуйте, а потім нова зміна для фази два.
• Сама проблема змінилася («додати темну тему» перетворилося на «створити повну систему темизації»)? Нова зміна.

Повний блок-схема та приклади роботи знаходяться у Workflows: When to Update vs Start Fresh, а глибше обговорення — у OPSX: When to Update vs. Start Fresh.

Примітка щодо завдань

tasks.md — це живий контрольний список, а не застиглий план. Під час реалізації ви можете додавати відкриті завдання, які ви виявили, видаляти ті, які виявилися непотрібними, або змінювати їх порядок. AI відмічає пункти як виконані під час /opsx:apply, і він продовжує з першим невідзначеним завданням, якщо ви повернетеся пізніше. Редагування списку під час процесу очікується.

Куди рухатися далі

• Workflows — шаблони, а також посібник із прийняття рішення (оновлювати чи нова зміна)
• Explore First — місце, куди повернутися, коли ідея потребує переосмислення
• Commands — /opsx:continue, /opsx:apply та /opsx:verify детально
• Concepts: Artifacts — для чого потрібні кожен артефакт