OpenSpec у команді

Все в інших посібниках працює однаково, незалежно від того, ви працюєте самі чи в команді з двадцяти осіб. Що змінюється в команді, так це питання на стику: де зберігаються специфікації, як колеги переглядають план і як все це вписується в наш наявний робочий процес pull-request.

Коротка відповідь: зміна — це просто файли, і OpenSpec ніколи не втручається в git. Таким чином, він вписується в ваш наявний робочий процес, а не замінює його. На цій сторінці описано конвенції, які працюють добре.

Одне правило: OpenSpec не втручається в git

OpenSpec читає та записує звичайний Markdown у теці openspec/. Він ніколи не робить коміти, не створює гілки, не виконує push або pull у вашому проєкті — і ніколи самостійно не клонує або синхронізує store. Це означає:

• Ви комітите openspec/ як будь-яке джерело коду. Специфікації, активні зміни та архів є частиною історії вашого проєкту. (Так, комітіть всю теку — див. FAQ.)
• Зміна — це тека, яку ви версіонуєте як код. openspec/changes/add-dark-mode/ — це просто файли на гілці.
• Все, що нижче, — це конвенція, а не примус. OpenSpec не змушуватиме вас робити так; він просто чудово вписується.

Повсякденний цикл

Робочий процес, який працює добре, відображає зміну на гілку та pull request:

git switch -c add-dark-mode        створіть гілку, як зазвичай
   │
/opsx:propose add-dark-mode        складіть план (пропозиція + специфікації + завдання)
   │
REVIEW THE PLAN                    прочитайте його перед будь-яким кодом — див. Reviewing a Change
   │
/opsx:apply                        зберіть його; артефакти + зміна коду разом
   │
git commit && open a PR            PR містить дельту специфікації ТА код
   │
teammate reviews, merges           колега переглядає, мерджить
   │
/opsx:archive                      додайте дельту до specs/, перемістіть зміну до archive/

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

Перегляд специфікацій у pull request

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

Гарний порядок перегляду для рецензента:

1. Прочитайте proposal.md — чи це правильна проблема та обсяг?
2. Прочитайте дельту в specs/ — чи правильно визначено "завершено"? (Це двохвилинний прохід Reviewing a Change, який тепер відбувається в PR.)
3. Потім прочитайте diff коду — чи він відповідає саме цим вимогам?

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

Коли архівувати

Архівання додає дельти зміни до вашої основної теки openspec/specs/ і переміщає теку зміни до openspec/changes/archive/YYYY-MM-DD-<name>/. Оскільки specs/ є спільним джерелом правди, час має значення в команді. Дві працездатні конвенції:

• Архівувати після злиття PR (рекомендовано). Гілка містить активну зміну; коли її злито з вашою основною гілкою, архівуйте там (часто це невеликий наступний коміт або заплановане очищення). Це змушує спільну теку specs/ рухатися вперед лише з роботою, яка фактично була випущена.
• Архівувати всередині PR. Простіше для малих команд: той самий PR, що додає код, також синхронізує та архівує. Компроміс полягає в тому, що ваш specs/ diff і ваш code diff опиняються разом, що може зробити PR більш зашумленим.

Виберіть одне і будьте послідовними. У будь-якому випадку, /opsx:archive перевіряє, чи завдання завершені, і пропонує спочатку синхронізацію, щоб нічого не злилося напівготовим випадково.

Два розробники, паралельні зміни

Оскільки зміни — це окремі теки, вони не конфліктують:

• Різні зміни, різні люди — без проблем. add-dark-mode і rate-limit-login — це різні теки на різних гілках; вони ніколи не торкаються одного одного, поки обидва не архівовані.
• Одна зміна, один власник. Два розробники, що редагують одну й ту саму теку змін, конфліктують так само, як два розробники, що редагують один і той самий файл. Зберігайте зміну за одним автором або розділіть її на дві зміни (ще одна причина right-size).
• Одне місце, де з'являються конфлікти — це specs/. Якщо дві зміни модифікують одну й ту саму вимогу, архівання другої викличе конфлікт у openspec/specs/…/spec.md — вирішіть його як будь-який конфлікт злиття, зберігши вимогу, яка відображає реальність. Це рідкісне явище, і це фіча: git каже вам, що дві зміни не погодилися щодо того, як система повинна поводитися.

Коли планування виходить за межі одного репозиторію

Все вище передбачає, що план живе у власній теці openspec/ репозиторію коду, що є правильним значенням за замовчуванням. Коли ваше планування справді охоплює кілька репозиторіїв або команд — одна фіча, що торкається трьох сервісів, або вимоги, якими володіє одна команда, а інші споживають — для цього існує бета-фіча stores: планування отримує власний репозиторій, на який може вказувати будь-який репозиторій коду. Почніть з Stores User Guide.

Куди далі

• Reviewing a Change — етап перегляду, тепер усередині вашого PR.
• Writing Good Specs — включаючи те, як right-size зміну, щоб вона відповідала одній гілці.
• Stores User Guide — планування, що охоплює репозиторії та команди.