Використання OpenSpec у існуючому проєкті

Ви не документуєте весь свій код на початку. Ви пишете специфікації лише для того, що збираєтеся змінити. Це найважливіша річ, яку потрібно знати про впровадження OpenSpec у вже існуючий проєкт, і саме тому OpenSpec створений з акцентом на "brownfield" (існуючий код).

Поширена турбота звучить так: «Мій додаток має 80 000 рядків. Чи мушу я написати специфікації для всього цього, перш ніж OpenSpec стане корисним?» Ні. Вам би це не сподобалося, і нам теж. OpenSpec нарощує ваші специфікації по частинах, зміна за зміною. Ваша перша зміна документує ту частину, яку вона торкається; наступна зміна документує свою частину, і протягом місяців ваші специфікації природно заповнюються навколо тієї роботи, яку ви насправді виконуєте.

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

Версія у тридцять секунд

$ cd your-existing-project
$ openspec init          # adds openspec/ and your AI tool's commands

Потім у вашому чаті з AI:

/opsx:explore            # optional: have the AI read the area you'll touch
/opsx:propose <a real, small change you actually need>
/opsx:apply
/opsx:archive

Ваші специфікації тепер описують саме ту частину системи, яку торкнулася зміна, і нічого більше. Це правильно. Ви перестаєте турбуватися про інші 80 000 рядків.

Чому підхід "delta-first" є ключовим трюком

Зміни OpenSpec пишуться як дельти: ADDED, MODIFIED, REMOVED. Дельта описує, що змінюється відносно поточної поведінки, а не всю систему.

Це саме те, що потрібно для роботи з існуючим кодом (brownfield). Ви рідко коли починаєте з нуля. Ви додаєте поле, виправляєте перенаправлення, скорочуєте таймаут. Дельта дозволяє вам точно вказати цю одну зміну, не пишучи спочатку 40-сторінкову специфікацію про все навколо цього.

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

Якщо вам потрібні глибші механізми, дивіться Concepts: Delta Specs.

Ваша перша зміна на реальній кодовій базі

Оберіть щось маленьке і реальне. Не іграшку, не переписування. Зміну, яку ви збиралися зробити цього тижня. Маленькі перші зміни навчають вас робочому процесу з низькими ставками ризику.

Крок 1: Дозвольте AI прочитати відповідну область. Тут /opsx:explore виконує свою роботу на незвичній або великій кодовій базі. Направте його на ту частину, яку ви збираєтеся торкнутися, і дозвольте йому зіставити, як працюють речі, перш ніж щось пропонувати.

You: /opsx:explore

AI:  What would you like to explore?

You: I need to add rate limiting to our public API, but I'm not sure
     how requests currently flow through the middleware.

AI:  Let me trace it... [reads the router, middleware stack, and config]
     Requests hit Express, pass through auth middleware, then your
     controllers. There's no rate-limiting layer today. The cleanest
     insertion point is a middleware right after auth. Want me to scope it?

Зверніть увагу: AI тепер розуміє вашу фактичну структуру, тому пропозиція, яку він пише, відповідатиме вашому коду, а не загальному шаблону. На великій кодовій базі ця одна звичка рятує найбільше болю. Дивіться Explore First.

Крок 2: Запропонуйте зміну. Пропозиція та її дельта-специфікація охоплюють лише цю зміну.

You: /opsx:propose add-api-rate-limiting

Крок 3: Зберіть і заархівуйте за допомогою /opsx:apply та /opsx:archive, як будь-яку іншу зміну. Після архівації ви отримуєте реальну специфікацію для вашої поведінки обмеження швидкості, народжену з зміни, яку вам потрібно було зробити все одночасно.

Бажаєте керований тур? Використовуйте onboard

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

Спочатку увімкніть розширені команди:

$ openspec config profile      # select the expanded workflows
$ openspec update              # apply them to this project

Потім у чаті:

/opsx:onboard

Це найм’якше можливе введення в реальний проєкт, і воно залишає вам справжню (маленьку) зміну, яку ви можете зберегти або відкинути. Дивіться Commands: /opsx:onboard.

«Але у мене вже є документи вимог»

Можливо, у вас є PRD, SRS, формальна специфікація, навіть моделі TLA+. Добре. Ви не імпортуєте їх усі одразу, і ви й їх не викидаєте.

Поводьтеся з існуючими документами як матеріалом для дослідження, а не як специфікаціями для конвертації. Коли ви починаєте зміну, вставте або вкажіть AI на відповідний розділ і дозвольте йому сформувати сфокусовану дельту OpenSpec з цього матеріалу. Дельта фіксує поведінку, яку ви змінюєте зараз, у формі тестованої вимоги та сценарію OpenSpec. Ваші оригінальні документи залишаються на місці як фон.

Чесна причина: специфікації OpenSpec навмисно орієнтовані на поведінку і обмежені змінами. 40-сторінковий PRD — це інший артефакт із різною задачею. Примусова одноразова масова конвертація, як правило, створює велику, застарілу специфікацію, якій ніхто не довіряє. Дозволяючи специфікаціям рости з реальних змін, ви зберігаєте їхню точність.

You: /opsx:explore
You: Here's the section of our PRD about checkout. I'm implementing the
     "guest checkout" requirement next.
     [paste the relevant requirement]
AI:  [reads it, asks clarifying questions, then helps scope a change]
You: /opsx:propose add-guest-checkout

Організація специфікацій у великій кодовій базі

Специфікації зберігаються в openspec/specs/, згруповані за доменом: логічною областю, яка відповідає тому, як ваша команда думає про систему. Вам не потрібно проєктувати всю таксономію одразу. Створіть папку домену, коли потрібна перша зміна в цій області.

Поширені способи поділу на домени:

• За областю функцій: auth/, payments/, search/
• За компонентом: api/, frontend/, workers/
• За обмеженим контекстом: ordering/, fulfillment/, inventory/

Оберіть те, що змусить новачка кивнути. Ви можете вдосконалити це пізніше. Дивіться Concepts: Specs.

Монорепозиторії та робота, що охоплює кілька репозиторіїв

Для монорепозиторію найпростіша модель — це один каталог openspec/ у корені репо, з доменами, які відповідають вашим пакетам або сервісам. Це покриває більшість команд.

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

Кілька чесних застережень

• Спротивляйте спокусі заповнювати все назад. Написання специфікацій для коду, який ви не змінюєте, здається продуктивним, але зазвичай це не так. Ці специфікації стають застарілими, тому що ніщо не змушує їх відстежувати реальність. Нехай реальні зміни керують вашими специфікаціями.
• Тримайте ранні зміни малими. Ваші перші кілька змін настільки ж про навчання ритму, як і про випуск. Обмежена сфера робить цикл швидким, а уроки — дешевими.
• Commit openspec/ до git. Ваші специфікації та архів належать до системи контролю версій разом із кодом, який вони описують.
• Надайте контекст AI. На великій кодовій базі зі сильними конвенціями заповніть context: у openspec/config.yaml, щоб кожна пропозиція відповідала вашому стеку та шаблонам. Дивіться Customization.

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

• Explore First — ключова звичка для розуміння коду перед тим, як його змінювати
• Getting Started — повний покроковий огляд першої зміни
• Editing & Iterating on a Change — коригування змін у процесі навчання
• Concepts: Delta Specs — чому дельти роблять роботу з існуючим кодом чистою
• Customization — навчіть OpenSpec конвенціям вашого проєкту