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

Кожен артефакт у зміні — це просто 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
• Концепції: Артефакти — призначення кожного артефакту