Настройка проекта

Добавьте OpenSpec в проект: запустите init, посмотрите, что он записал, и настройте под себя.

Выберите, где разместить OpenSpec

• В репозитории (по умолчанию): спецификации и изменения находятся рядом с кодом, который они описывают, и версионируются вместе с ним. Далее на этой странице описывается именно этот вариант.
• В хранилище: отдельный репозиторий для планирования, общий для использующих его репозиториев — для мульти-репозиторных конфигураций или для того, чтобы вообще не хранить планирование в репозитории. Раздел Хранилища (бета) рассказывает, когда это имеет смысл и как их настроить.

Инициализация проекта

Установив CLI (Установка), выполните init в корне вашего проекта. В терминале:

cd <your-project>
openspec init

Init спросит, какие AI-инструменты вы используете, запишет рабочие файлы для выбранных вами и сообщит о результате:

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).

Перенос существующего 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/ в корне репозитория
• Рабочие файлы (навыки и команды), добавленные в папку вашего AI-инструмента (.agents/, .claude/ и т.д.)

Закоммитьте всё это вместе с остальным исходным кодом. Init больше ничего в вашем репозитории не меняет (если он находит остатки от более старой версии OpenSpec, он запрашивает разрешение перед их удалением).

Папка openspec/

Здесь, в корне проекта, находятся все артефакты OpenSpec. Вот как это выглядит:

openspec/
├── config.yaml     настройки проекта и контекст для AI
├── specs/          ваши спецификации (пока пусто)
└── changes/        текущие изменения (пока пусто)
    └── archive/    завершённые изменения перемещаются сюда

Раздел Конфигурация проекта посвящён config.yaml.

Рабочие файлы (навыки и команды)

Это рабочие процессы OpenSpec — действия, которые вы будете использовать в работе. Вот они в виде установленных навыков в общей папке .agents/, которую использует большинство инструментов:

.agents/skills/
├── openspec-explore/              обдумать идею перед началом
├── openspec-propose/              предложить изменение
├── openspec-apply-change/         реализовать задачи изменения
├── openspec-update-change/        пересмотреть план изменения
├── openspec-sync-specs/           синхронизировать обновления спецификации в specs/
├── openspec-archive-change/       переместить завершённое изменение в архив
├── openspec-verify-change/        проверить соответствие реализации плану (не включён по умолчанию)
└── openspec-bulk-archive-change/  архивировать несколько изменений сразу (не включён по умолчанию)

Это набор по умолчанию плюс два необязательных рабочих процесса. В разделе Профили перечислены все двенадцать.

По умолчанию каждый рабочий процесс устанавливается в двух формах:

• Навык (openspec-apply-change): инструкции, которые ваш агент сам подхватывает, когда вы запрашиваете работу.
• Команда (/opsx:apply в Claude Code): вводимая точка входа для того же рабочего процесса под более коротким именем.

Они функционально идентичны. Навык и команда рабочего процесса содержат одни и те же инструкции.

Зачем две формы: команды появились раньше, и каждый инструмент записывает их по-своему. Навыки — более новый стандарт, общий для разных инструментов, но не каждый инструмент может напрямую вызвать навык, поэтому команды остаются точкой входа для таких инструментов.

Некоторые инструменты устанавливаются только в форме навыков. Если инструмент запускает навыки напрямую, init пропускает команды и сообщает об этом (Commands skipped for: codex (uses skills)).

Мы предпочитаем навыки и со временем планируем отказаться от команд.

Изменение устанавливаемого набора

Интерактивный выбор позволяет изменить форму доставки и набор рабочих процессов (Профили). В терминале:

openspec config profile

Вот как переключиться только на навыки:

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 не отображает рабочие процессы

Claude Code загружает рабочие процессы OpenSpec из одного или обоих следующих путей в проекте в зависимости от настройки доставки:

• Навыки: .claude/skills/openspec-*/SKILL.md
• Команды: .claude/commands/opsx/<id>.md

Если файлы отсутствуют, обновите проект. В терминале:

openspec update

Если файлы команд существуют, но /opsx: не показывает команды OpenSpec, обновите Claude Code и перезапустите его. Если команды по-прежнему не загружаются, включите также навыки. В терминале:

openspec config set delivery both
openspec update

Перезапустите Claude Code, затем выполните /openspec-propose в его чате. Если отсутствуют только некоторые рабочие процессы, измените профиль.

Настройка завершена. Краткое руководство поможет сделать первое изменение.