Основні концепції наочно

OpenSpec — це легкий рівень узгодження між вами та вашим ШІ. Ви описуєте, що має робити зміна; ШІ створює деталі; ви обоє переглядаєте один і той самий план, і лише потім код пишеться. Ця сторінка є повною ментальною моделлю на одному екрані. Якщо вам потрібна повна версія, Concepts містить її.

Ось вся суть у п'яти словах: спочатку погодитися, а потім впевнено будувати.

П’ять ідей

Усе в OpenSpec побудовано на основі п'яти концепцій. Вивчіть їх, і решта — це деталі.

1. Специфікації є правдою. Spec описує те, як працює ваша система зараз. Вони знаходяться у openspec/specs/ та організовані за доменами (auth/, payments/, ui/). Specs складаються з вимог ("система МАЄ закінчувати сесії через 30 хвилин") та сценаріїв (конкретних прикладів given/when/then). Уявіть specs як єдину узгоджену відповідь на питання: "що робить це програмне забезпечення?".

2. Зміна — це одиниця роботи. Коли ви хочете додати, змінити або видалити поведінку, ви створюєте зміну: папку в openspec/changes/, яка містить усе про цю роботу в одному місці. Пропозиція, дизайн, список завдань та редагування специфікацій. Одна зміна — одна папка — одна функція.

3. Delta specs описують зміни, а не весь світ. У межах однієї зміни ви не переписуєте всю специфікацію. Ви пишете невелику дельту: ADDED ця вимога, MODIFIED та інша, REMOVED третя. Це той трюк, який робить OpenSpec хорошим у редагуванні існуючих систем, а не лише нових. Ви описуєте різницю (diff), а не кінцевий стан.

4. Артефакти будуються одне на одному. Зміна містить декілька документів, створених у природному порядку, кожен з яких є основою для наступного:

proposal ──► specs ──► design ──► tasks ──► implement
   why        what       how       steps      do it

Ви можете повернутися до будь-якого з них у будь-який час. Вони є фасилітаторами, а не перешкодами. (Більше про це нижче.)

5. Архівування повертає зміну назад у правду. Коли робота виконана, ви архівуєте зміну. Її delta specs зливаються з вашими основними специфікаціями, а папка зміни переміщується до changes/archive/ із міткою дати. Тепер ваші специфікації описують нову реальність, і ви готові до наступної зміни. Цикл закривається.

Зображення

┌─────────────────────────────────────────────────────────────────┐
│                          openspec/                              │
│                                                                 │
│   ┌──────────────────┐         ┌──────────────────────────┐    │
│   │     specs/       │         │        changes/          │    │
│   │                  │ ◄─────  │                          │    │
│   │ source of truth  │  merge  │ one folder per change    │    │
│   │ how things work  │  on     │ proposal · design ·      │    │
│   │ today            │ archive │ tasks · delta specs      │    │
│   └──────────────────┘         └──────────────────────────┘    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Дві папки. specs/ — це правда. changes/ — це те, що ви пропонуєте. Архівування переносить пропозицію у сферу правди.

Цикл, який ви насправді будете виконувати

У стандартній конфігурації ваш день виглядатиме так. Опційно спочатку подумайте над цим; потім одна команда створює план, ви його читаєте, наступна будує його, а остання зберігає файли.

/opsx:explore                   →  (опціонально) спочатку обміркувати з ШІ
/opsx:propose add-dark-mode     →  ШІ створює пропозицію, specs, дизайн та завдання
        (ви читаєте та коригуєте план)
/opsx:apply                     →  ШІ будує це, відзначаючи виконані завдання
/opsx:archive                   →  specs оновлені, зміна заархівована

Коли ви сумніваєтеся, почніть з дослідження. /opsx:explore — це партнер для мислення без ризиків: він читає ваш код, розкладає варіанти та перетворює невизначену ідею на конкретний план до появи будь-якого артефакту. Це найкращий антидот проти ШІ, який інакше створить щось з розпливчастого запиту. Уже знаєте, що саме хочете? Пропустіть прямо до /opsx:propose. У будь-якому випадку, дослідження є у стандартному профілі, тому воно завжди доступне. Дивіться Explore guide.

Це slash commands, які вводяться в чаті вашого помічника ШІ. Налаштування (openspec init) виконується у терміналі. Якщо цей поділ вам незвичний, спочатку прочитайте How Commands Work; це найпоширеніша точка плутанини.

"Фасилітатори, а не бар'єри"

Ця фраза зустрічається всюдині в OpenSpec, тому ось що вона означає простими словами.

Старі процеси специфікації — це водоспади: спочатку завершуєте планування, потім вам дозволено реалізувати, і повернення назад болісне. OpenSpec цього не допускає. Порядок proposal → specs → design → tasks показує те, що стає можливим далі, а не те, що ви змушені зробити наступним.

Виявляєте під час реалізації, що дизайн був неправильним? Редагуйте design.md і продовжуйте. Зрозуміли, що обсяг має зменшитися? Оновіть пропозицію. Ніщо не блокується. Залежності існують лише для того, щоб ШІ мав необхідний контекст (ви не можете написати хороші завдання без специфікацій як основу), а не для того, щоб вас обмежувати.

Сила тут полягає в чесності: реальна робота хаотична та ітеративна, і OpenSpec це дозволяє. Компроміс положено на дисципліну: оскільки ніщо вас не змушує рухатися вперед, ви самі повинні тримати зміну сфокусованою, а не дозволити їй розростатися. Гайд Workflows містить хороші звички для цього.

Чому це варто невеличкого навантаження

Проста правда: OpenSpec додає крок. Ви пишете короткий план перед тим, як будуєте. То що ви отримуєте за це?

• Ви ловите помилки до того, як вони коштувати почнуть. Виправлення непорозуміння в одній параграфічній пропозиції — це безкоштовно. Виправлення після того, як ШІ написав 400 рядків — ні.
• План та код залишаються в одному репозиторії. Через пів року специфікація скаже вам (і наступному сеансу ШІ), чому система працює саме так.
• Зміни можна переглянути. Папка зміни — це охайний пакет: прочитайте пропозицію, швидко перегляньте дельти, перевірте завдання. Жодної археології через історію чату.
• Це підходить для існуючих кодових баз. Дельти означають, що ви можете специфікувати зміну у 50 000-рядковій програмі, не документуючи всю її суть спочатку.

І чесний компроміс: для справді тривіального однорядкового виправлення церемонія може не окупитися, і це нормально. OpenSpec створений бути легким, але він не безкоштовний. Використовуйте його там, де важлива згода, а це, як виявляється, більшість часу, коли ви працюєте з ШІ, який впевнено створить те, що ви невиразно попросили.

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

• Новички? Getting Started повністю проходить першу зміну.
• Не впевнені, що будувати? Explore First — це місце для початку.
• Збентежені щодо того, де виконуються команди? How Commands Work.
• Хочете глибоку версію всього вищесказаного? Concepts.
• Навчання на прикладах? Examples & Recipes.
• Потрібно визначити термін? Glossary.