Налаштуйте свій проєкт

Додайте OpenSpec у ваш проєкт: запустіть init, перегляньте, що він створив, і налаштуйте його.

Виберіть, де OpenSpec розташовується

• У вашому репозиторії (за замовчуванням): спеки та зміни розташовані поряд з кодом, який вони описують, і версіонуються разом із ним. Решта цієї сторінки йде за цим шляхом.
• У сховищі: окремий планувальний репозиторій, який спільно використовується репозиторіями, що на ньому працюють, для багаторепозиторійних налаштувань або для того, щоб планування не зберігалося в репозиторії взагалі. Stores (beta) описує, коли це варто й як налаштувати таке сховище.

Налаштуйте свій проєкт

З клієнта OpenSpec (Installation) встановлено, запустіть init у корені вашого проєкту. У вашому терміналі:

cd <your-project>
openspec init

init запитує, які AI-інструменти ви використовуєте, створює файли workflow для обраних вами і повідомляє, що було створено:

OpenSpec Setup Complete

Created: Claude Code
6 skills and 6 commands in .claude/
Config: openspec/config.yaml (schema: spec-driven)

Перезапустіть IDE, щоб нові команди набули чинності.

Повторний запуск init безпечний:

• Інструменти, які ви вже налаштували, виводять Refreshed замість Created.
• Повторний запуск init із новим обраним інструментом додає цей інструмент.
• Флаг --tools пропускає засіб вибору (CLI reference).

Міграція існуючого project.md

init не копіює застарілий openspec/project.md у config.yaml. Він зберігає файл і виводить запит на міграцію з допомогою AI.

У вашому AI-чаті:

Review openspec/project.md and migrate its useful content to openspec/config.yaml.
Keep context concise: include only project-wide facts needed during artifact creation, apply, and archive.
Move artifact-specific guidance into rules for the matching artifacts.
Move guidance for apply or archive into the matching operations entry.
Leave out generic, outdated, or verbose material. Do not delete project.md.

Перегляньте config.yaml, потім видаліть project.md, коли будете готові.

Що створює init

Запуск init створює у вашому проєкті два елементи:

• Каталог openspec/ на корені репозиторію
• Файли workflow (skills and commands), додані до папки вашого AI-інструменту (.agents/, .claude/, etc.)

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

Каталог openspec/

Кожен OpenSpec-артефакт тут, на корені вашого проєкту. Ось як це виглядає:

openspec/
├── config.yaml     project settings and context for the AI
├── specs/          your specs (empty for now)
└── changes/        in-motion changes (empty for now)
    └── archive/    completed changes move here

Конфігурація проєкту охоплює config.yaml.

Файли workflow (skills and commands)

Це такі OpenSpec workflow, дії, які ви будете використовувати в роботі. Ось вони як встановлені skills у спільній папці .agents/, яку більшість інструментів використовує:

.agents/skills/
├── openspec-explore/              think through an idea first
├── openspec-propose/              propose a change
├── openspec-apply-change/         implement a change's tasks
├── openspec-update-change/        revise a change's plan
├── openspec-sync-specs/           sync a change's spec updates into specs/
├── openspec-archive-change/       move a finished change to the archive
├── openspec-verify-change/        check the implementation matches the plan (not included by default)
└── openspec-bulk-archive-change/  archive several changes at once (not included by default)

Це стандартний набір плюс два додаткові workflow. Profiles перелічує всі двінадцять.

За замовчуванням кожен workflow встановлюється у два форми:

• Skill (openspec-apply-change): інструкції, які ваш агент підхоплює самостійно, коли ви просите виконати роботу.
• Command (/opsx:apply in Claude Code): типовий вхідний пункт для того самого workflow, з коротшим ім'ям.

Це два однакові за функціями. Skill workflow та його command несе ті самі інструкції.

Чому два: commands з’явилися першими, і кожен інструмент вимовляє їх по-своєму. Skills — це новіший стандарт, який спільно використовується інструментами, але не кожен інструмент може безпосередньо викликати skill, тому commands залишилися як вхідні точки для цих інструментів.

Деякі інструменти встановлюються лише в формі skill. Де інструмент запускає skills безпосередньо, init пропускає commands і повідомляє про це (Commands skipped for: codex (uses skills)).

Ми віддаємо перевагу skills і плануємо згасити commands.

Змініть, що встановлюється

Інтерактивний засіб вибору змінює форму доставки та набір workflow (Profiles). У вашому терміналі:

openspec config profile

Ось як переключитися на skills only:

Current profile settings
  Delivery: both

? What do you want to configure? Delivery only
? Delivery mode (how workflows are installed): Skills only

Config changes:
  delivery: both -> skills
? Apply changes to this project now? (Y/n) y

Якщо відповісти так, це застосується до поточного проєкту одразу. Інші проєкти підхоплять це наступного запуску openspec update. Це глобальне налаштування, призначене для конкретної машини.

Claude Code не показує workflow

Claude Code завантажує OpenSpec workflow з одного або з обох цих шляхів у вашому проєкті, залежно від вашого налаштування доставки:

• Skills: .claude/skills/openspec_*/SKILL.md
• Commands: .claude/commands/opsx/<id>.md

Якщо файли відсутні, оновіть проєкт. У вашому терміналі:

openspec update

Якщо файли команд існують, але /opsx: не показує OpenSpec commands, оновіть Claude Code і перезапустіть його. Якщо commands все ще не завантажуються, також увімкніть skills. У вашому терміналі:

openspec config set delivery both
openspec update

Перезапустіть Claude Code, потім запустіть /openspec-propose у його чаті. Якщо не всі workflow відсутні, змініть ваш профіль.

Налаштування завершено. Quickstart веде до вашого першого change звідси.