Швидкий старт
Ваш перший змін: від ідеї до архівування у новому або наявному проєкті.
Перед початком вам потрібен CLI на вашій машині (Встановлення) та ініціалізований OpenSpec у вашому проєкті (Налаштування вашого проєкту).
Початок з порожнього проєкту
Ви можете розпочати без обраного стеку або повної архітектури. Ініціалізуйте OpenSpec у папці вашого проєкту, а потім попросіть агента розглянути варіанти разом з вами. У вашому чаті ШІ:
Допоможи мені дослідити завдання для трекера задач з нуля. Я ще не обрав стек. Порівняй варіанти та допоможи мені обрати першу поведінку, яку потрібно реалізувати.Визначте, що потрібно для першої зміни, і залиште пізніші архітектурні рішення відкритими. Попросіть агента запропонувати цю одну зміну, а потім виконуйте описані нижче кроки. Ви можете переглядати архітектуру зі зростанням проєкту.
Ітераційний цикл у стислому вигляді
Кожна зміна проходить через ті самі п'ять кроків: ви обмірковують ідею з агентом, він складає чернетку плану, ви коригуєте план до того, як буде існувати код, агент будує його, а архівування оновлює ваші специфікації тим, що було реалізовано.
flowchart LR
explore["1 · Дослідження<br/>розмірковуйте разом"] --> propose["2 · Запропоновання<br/>агент складає чернетку плану"]
propose --> review["3 · Відгук<br/>ви коригуєте план"]
review --> apply["4 · Застосування<br/>агент будує, завдання за завданням"]
apply --> archive["5 · Архівування<br/>специфікації поглинають зміну"]
archive -. "наступна зміна" .-> explore
Кожне далі промпт укладається у ваш чат ШІ, туди ж, де ви просите код. Приклади використовують просту мову, щоб працювати з різними інструментами. Ви також можете безпосередньо активувати навичку; синтаксис залежить від інструменту (підтримувані інструменти).
Крок 1: Дослідження
Розмірковуйте над ідеєю з агентом, перш ніж просити план. У вашому чаті ШІ:
Допоможи мені дослідити, як у цьому застосунку має працювати обмеження швидкості.Дослідження — це режим міркування. Агент досліджує вашу кодову базу, ставить важливі запитання, окреслює варіанти та ставить під сумнів припущення. Він ніколи не пише код. Він не пише нічого іншого, якщо ви не попросите зафіксувати те, що ви вирішили, або не скажете так, коли він запропонує це. Результатом є точніша ідея.
Залишайтеся на цьому етапі так довго, як цього вимагає проблема. Коли структура здасться вам правильною, передайте естафету:
Запропонуй зміну, яку ми щойно обговорили.Цей рядок запускає для вас етап запропоновання, передаючи все, на чому ви домовилися. Пропустіть перший промпт на кроці 2.
Крок 2: Запропоновання
Запропоновання перетворює ідею на переглядуваний план. Приходячи з дослідження, процес вже запущено. Якщо ви починаєте з нуля, коли зміна є чіткою у вашій голові, просто попросіть прямо. У вашому чаті ШІ:
Запропонуй зміну для додавання обмеження швидкості.Агент запитує те, що йому потрібно, а потім створює папку змін:
openspec/changes/add-rate-limiting/
├── proposal.md чому, і що змінюється
├── specs/ що означає "завершено", як тестувані вимоги
├── design.md технічні рішення (лише коли зміна потребує цього)
└── tasks.md чек-лист реалізаціїПоки що без коду. Запропоновання зупиняється на етапі плану.
Крок 3: Перегляньте та виправте план
Виправте план, доки він ще є словами і нічого не побудовано. Читайте в такому порядку:
proposal.md: чи це правильна проблема, правильного розміру?specs/: читання з найвищою цінністю. Чи приймете ви ці вимоги як виконані?tasks.md: чи покриті завданнями специфікації, і нічого більше?
Щоб щось виправити, підійде будь-який із способів:
- Відредагуйте файл самостійно. Артефакти — це звичайний markdown, і файли є планом.
- повідомте своєму агенту, що не так ("у специфікації бракує випадку без автентифікації"). Він оновить артефакти.
Крок 4: Застосування
Застосування перетворює план у код. Розпочніть нову сесію чату, оскільки реалізація краще йде в чистому контекстному вікні. У вашому чаті ШІ:
Застосуй зміну add-rate-limiting.Агент читає папку змін, а потім обробляє tasks.md, відзначаючи кожне завдання за мірою його виконання.
- Перервано, або вичерпано контекст? Відкрийте нову сесію та попросіть застосувати знову. Він відновить роботу з першого незазначеного завдання.
- План виявився неправильним? Виправте артефакти (будь-яким зі способів з кроку 3), а потім продовжуйте застосування.
- Прогрес зберігається у прапорцях у
tasks.md. Не існує прихованого стану.
Крок 5: Архівування
Архівування робить дві речі: воно оновлює ваші основні специфікації вимогами зміни та переміщує папку зміни до папки архіву (у /openspec/changes/archive/*).
Коли всі прапорці в tasks.md відзначені, у вашому чаті ШІ:
Архівуй зміну add-rate-limiting.Пройдіться по тому, що робить архівування:
## Завершена зміна
> Реалізацію завершено. Дельта-специфікація (те, що додає ця зміна) все ще перебуває всередині папки змін; specs/ поки що не знає про обмеження швидкості.
openspec/
├── specs/ (поки що немає специфікації обмеження швидкості)
└── changes/
└── add-rate-limiting/
├── proposal.md
├── tasks.md всі прапорці відзначені
└── specs/
└── rate-limiting/
└── spec.md дельта: ДОДАНО вимоги
## Вимоги потрапляють у specs/
> Кожна вимога в дельті потрапляє в основну специфікацію: додані доповнюють, змінені заміняють свою стару версію. Для нової можливості створюється новий файл специфікації.
openspec/
├── specs/
+ │ └── rate-limiting/
+ │ └── spec.md набуває "Вимога: Обмеження швидкості"
└── changes/
└── add-rate-limiting/
└── specs/
└── rate-limiting/
└── spec.md дельта, джерело злиття
## Папку переміщено до archive/
> Уся папка змін, включаючи дельту, переміщується в архів із префіксом дати. Ніщо не видаляється.
openspec/
├── specs/
│ └── rate-limiting/
│ └── spec.md
└── changes/
- └── add-rate-limiting/
+ └── archive/
+ └── 2026-08-08-add-rate-limiting/
+ ├── proposal.md
+ ├── tasks.md
+ └── specs/rate-limiting/spec.md
## Специфікації описують систему в реалізованому вигляді
> changes/ чистий для наступної зміни. specs/ є джерелом істини щодо того, що робить система; archive/ є історією того, як вона до цього дійшла.
openspec/
├── specs/
│ └── rate-limiting/
│ └── spec.md специфікація в реалізованому вигляді
└── changes/
└── archive/
└── 2026-08-08-add-rate-limiting/Git є окремим питанням. Відкомітьте папку змін разом з кодом, і нічого іншого у вашому workflow не змінюється.
Зберігайте чи чистіть заархівовані зміни
openspec/changes/archive/ зберігає пропозицію, дизайн, завдання та дельту для кожної завершеної зміни. У потоку архівування вище, дельта вже оновила openspec/specs/.
- Зберігайте всю папку змін, коли ви хочете самодостатній запис у поточному checkout.
- Видаляйте папку
specs/заархівованої зміни, коли Git є вашою історією специфікацій. Спочатку відкомітьте архів, а потім видалітьopenspec/changes/archive/<change>/specs/. Пропозиція, дизайн і завдання залишаються у checkout.openspec validate --archivedвсе ще працює, оскільки він перевіряє виконання завдань, а не застосовані дельти. - Видаляйте всю папку змін лише тоді, коли вам більше не потрібна її пропозиція, дизайн або історія завдань у checkout. Поточні специфікації не змінюються, але
openspec validate --archivedта пошуки в checkout більше не включають цю зміну.
[!ПЕРЕДІРЖУВАННЯ] Зберігайте коміт архіву в історії вашого репозиторію, якщо ви хочете, щоб Git зберіг видалені файли. Злиття (squash) комітів архіву та прибирання разом видаляє цей проміжний знімок.
OpenSpec не автоматично прибирає заархівовані зміни та не надає налаштування строків зберігання.
Для глибшого заглиблення
- Дельта-специфікації: як писати зміни поведінки в дельта-специфікації.
- Профілі: необов'язкові workflow поза основним набором (перевірка перед архівуванням, інкрементне планування).
Розширені посібники
Ще не написані; посібники, які ми плануємо додати:
- Спочатку прототип: проспікуйте код до будь-якої специфікації, а потім доповніть пропозицію тим, чого навчив вас прототип.
- Ітеративне побудування: послідовність невеликих змін замість одного великого пропонування.
- Перегляд реалізованої зміни: план потребує нового руху після застосування, але зміна ще не злита або заархована.