Зачем это нужно
Стандартный workflow OpenSpec (proposal → specs → design → tasks → apply → archive) устроен так, что его хватает большинству команд. Но реальные проекты отличаются: у одной команды стек и конвенции, у другой - собственный процесс с обязательным ревью до реализации, у третьей - артефакты должны писаться на русском или португальском.
OpenSpec отвечает тремя уровнями настройки и одним накладным вопросом:
- конфигурация проекта - дефолты и контекст для большинства команд;
- кастомные схемы - собственный набор артефактов для команд с уникальным процессом;
- глобальные override - шары схем между проектами;
и отдельно - где физически записываются файлы skills и команд для каждого из 30+ поддерживаемых AI-инструментов.
Основная идея
Кастомизация OpenSpec держится на одном файле и одном каталоге:
openspec/config.yaml настройки проекта: схема по умолчанию, контекст, правила
openspec/schemas/ собственные схемы: свои артефакты, шаблоны, зависимости
Все настройки в итоге попадают в один и тот же механизм: при генерации артефакта контекст, правила и шаблон схемы инжектятся в промпт AI-агента. OpenSpec не форсирует процесс - он поставляет материал, из которого агент собирает артефакт под ваш процесс.
Три уровня настройки:
| Уровень | Что делает | Кому подходит |
|---|---|---|
| Конфигурация проекта | Дефолты и инжект контекста/правил | Большинству команд |
| Кастомные схемы | Собственные артефакты workflow | Командам с уникальным процессом |
| Глобальные override | Шары схем между всеми проектами | Продвинутым пользователям |
Конфигурация проекта
openspec/config.yaml - простейший способ настроить OpenSpec под команду. Файл позволяет:
- задать схему по умолчанию - не передавать
--schemaкаждой команде; - инжектить контекст проекта - агент видит ваш стек, конвенции и ограничения;
- добавить правила по артефактам - свои правила для конкретных артефактов;
- добавить guidance по операциям - советы для работы apply и archive;
- запомнить выбор интеграций - например, opt-in для облачного coding-агента GitHub Copilot.
Быстрая настройка
Интерактивно (создаст конфиг по шагам):
openspec init
Или вручную:
# openspec/config.yaml
schema: spec-driven
context: |
Tech stack: TypeScript, React, Node.js, PostgreSQL
API style: RESTful, documented in docs/api.md
Testing: Jest + React Testing Library
We value backwards compatibility for all public APIs
rules:
proposal:
- Include rollback plan
- Identify affected teams
specs:
- Use Given/When/Then format
- Reference existing patterns before inventing new ones
operations:
apply:
guidance:
- Run focused tests before the full suite
archive:
guidance:
- Keep the completion summary concise
# Заполняется `openspec init`, когда выбираете (или отклоняете) облачного
# coding-агента GitHub Copilot; управляет, генерирует ли init/update его файлы.
githubCopilot:
cloudAgent: false
Как это работает
Схема по умолчанию:
# Без конфига
openspec new change my-feature --schema spec-driven
# С конфигом - схема подставляется сама
openspec new change my-feature
Инжект контекста и правил. При генерации любого артефакта контекст и правила попадают в промпт агента:
<context>
Tech stack: TypeScript, React, Node.js, PostgreSQL
...
</context>
<rules>
- Include rollback plan
- Identify affected teams
</rules>
<template>
[Встроенный шаблон схемы]
</template>
contextпоявляется во ВСЕХ артефактах;rulesпоявляются только у соответствующего артефакта.
Guidance по операциям. operations.apply.guidance и operations.archive.guidance - необязательные массивы советов о том, как агенту проводить эти операции. Они отделены от rules: guidance операции не ограничивает содержимое артефактов, а правила артефактов никогда не переименовываются в guidance операций.
Apply и archive получают эти входы в момент выполнения:
openspec instructions apply --change my-feature --json
openspec instructions archive --change my-feature --json
Обе поверхности возвращают текущий контекст проекта и подходящий operationGuidance отдельными необязательными полями. Каждый вызов читает свежий снимок из резолвленного корня. Когда выбран --store <id>, изменение, контекст и guidance приходят из Store, а не из текущего репозитория. Команда инструкций archive только читает: она не инспектирует и не мержит дельта-спецификации, не пишет основные specs, не двигает изменение и не запускает статический workflow архивации.
Контекст проекта - обязательный вход уровня промпта. Сгенерированные workflow читают его и применяют относящиеся к делу факты, конвенции и ограничения проекта. Guidance операции - необязательный аддитивный совет: workflow рассматривает каждую запись и следует тем, что применимы и совместимы со встроенным workflow.
Оба поля остаются отделенными от состояния, управляемого CLI, резолвленных путей, встроенных шагов, явных выборов пользователя и правил артефактов. Workflow сообщает конфликты контекста, сохраняя контролирующее значение. Неприменимый или конфликтующий guidance не выполняется - с объяснением, почему. Ни одно из полей не является принудительной проверкой, и workflow не копирует их текст в файлы реализации, specs, артефакты изменения или сводки, если пользователь отдельно об этом не попросил.
Безопасность входов archive и spec-sync. Archive, bulk archive и standalone sync используют artifactPaths.specs.existingOutputPaths из openspec status --json как единственный источник дельта-спецификаций. Схема без артефакта specs или изменение с пустым списком конкретных выходов не имеет что синхронизировать; другие артефакты для вывода дельта-спецификаций не используются.
Перед тем как семантический merge пишет основную спецификацию, workflow потребляет свежий вывод openspec instructions specs --change <name> --json. Возвращенные правила specs ограничивают только основные specs, произведенные этим merge. Одиночный archive передает снимок в inline sync, standalone sync получает его напрямую, bulk archive собирает все нужные снимки до первой записи спецификации. Ненулевой или невалидный JSON-ответ инструкций archive/specs - это ошибка выборки, а не пустой вход: workflow останавливается до записи затронутой спецификации или перемещения изменения (для bulk archive - до любой пакетной записи или перемещения).
Эта конфигурация не меняет фазы выполнения archive, пользовательские промпты, файловые операции, владение семантическим merge, прямую команду openspec archive и структуру/вывод правил артефактов.
Порядок резолюции схемы
Когда OpenSpec нужна схема, он проверяет в этом порядке:
- Флаг CLI:
--schema <name> - Метаданные изменения (
.openspec.yamlв папке изменения) - Конфигурация проекта (
openspec/config.yaml) - Дефолт (
spec-driven)
Кастомные схемы
Когда конфигурации проекта мало, создайте собственную схему с полностью кастомным workflow. Кастомные схемы живут в каталоге openspec/schemas/ проекта и версионируются вместе с кодом.
your-project/
├── openspec/
│ ├── config.yaml # Конфигурация проекта
│ ├── schemas/ # Здесь живут кастомные схемы
│ │ └── my-workflow/
│ │ ├── schema.yaml
│ │ └── templates/
│ └── changes/ # Ваши изменения
└── src/
Форк существующей схемы
Быстрее всего кастомизировать форком встроенной схемы:
openspec schema fork spec-driven my-workflow
Команда копирует схему spec-driven целиком в openspec/schemas/my-workflow/, где ее можно свободно править. Что вы получаете:
openspec/schemas/my-workflow/
├── schema.yaml # Определение workflow
└── templates/
├── proposal.md # Шаблон артефакта proposal
├── spec.md # Шаблон specs
├── design.md # Шаблон design
└── tasks.md # Шаблон tasks
Теперь правьте schema.yaml для изменения workflow или шаблоны - для изменения того, что генерирует AI.
Схема с нуля
Для полностью нового workflow:
# Интерактивно
openspec schema init research-first
# Неинтерактивно
openspec schema init rapid \
--description "Rapid iteration workflow" \
--artifacts "proposal,tasks" \
--default
Структура схемы
Схема определяет артефакты workflow и их зависимости:
# openspec/schemas/my-workflow/schema.yaml
name: my-workflow
version: 1
description: My team's custom workflow
artifacts:
- id: proposal
generates: proposal.md
description: Initial proposal document
template: proposal.md
instruction: |
Create a proposal that explains WHY this change is needed.
Focus on the problem, not the solution.
requires: []
- id: design
generates: design.md
description: Technical design
template: design.md
instruction: |
Create a design document explaining HOW to implement.
requires:
- proposal # Design нельзя создать, пока нет proposal
- id: tasks
generates: tasks.md
description: Implementation checklist
template: tasks.md
requires:
- design
apply:
requires: [tasks]
tracks: tasks.md
Ключевые поля:
| Поле | Назначение |
|---|---|
id |
Уникальный идентификатор; используется в командах и правилах |
generates |
Имя выходного файла (поддерживает glob-паттерны вида specs/**/*.md) |
template |
Файл шаблона в каталоге templates/ |
instruction |
Инструкции AI для создания этого артефакта |
requires |
Зависимости - какие артефакты должны существовать раньше |
Артефакты перечисляются в том порядке, в котором вы хотите их писать. requires решает, что возможно; порядок списка artifacts: решает, что идет первым, когда несколько артефактов готовы одновременно.
Шаблоны
Шаблоны - Markdown-файлы, которые направляют AI. Они инжектятся в промпт при создании артефакта.
<!-- templates/proposal.md -->
## Why
<!-- Explain the motivation for this change. What problem does this solve? -->
## What Changes
<!-- Describe what will change. Be specific about new capabilities or modifications. -->
## Impact
<!-- Affected code, APIs, dependencies, systems -->
Шаблон может содержать:
- заголовки разделов, которые AI должен заполнить;
- HTML-комментарии с подсказками для AI;
- примеры формата ожидаемой структуры.
Валидация схемы
Перед использованием кастомной схемы проверьте ее:
openspec schema validate my-workflow
Проверяется:
- синтаксис
schema.yamlкорректен; - все упоминаемые шаблоны существуют;
- циклических зависимостей нет;
- ID артефактов валидны.
Использование и отладка
# Указать в команде
openspec new change feature --schema my-workflow
# Или сделать дефолтом в config.yaml
schema: my-workflow
Неясно, какая схема используется? Проверьте:
# Откуда резолвится конкретная схема
openspec schema which my-workflow
# Список всех доступных схем
openspec schema which --all
Вывод показывает источник - проект, пользовательский каталог или пакет:
Schema: my-workflow
Source: project
Path: /path/to/project/openspec/schemas/my-workflow
Важно: OpenSpec также поддерживает схемы уровня пользователя в ~/.local/share/openspec/schemas/ - для шаринга между проектами. Но рекомендуется хранить схемы в проекте (openspec/schemas/): они версионируются вместе с кодом.
Пример: схема rapid
Минимальный workflow для быстрых итераций:
# openspec/schemas/rapid/schema.yaml
name: rapid
version: 1
description: Fast iteration with minimal overhead
artifacts:
- id: proposal
generates: proposal.md
description: Quick proposal
template: proposal.md
instruction: |
Create a brief proposal for this change.
Focus on what and why, skip detailed specs.
requires: []
- id: tasks
generates: tasks.md
description: Implementation checklist
template: tasks.md
requires: [proposal]
apply:
requires: [tasks]
tracks: tasks.md
Пример: артефакт review
Форкните дефолт и добавьте шаг ревью:
openspec schema fork spec-driven with-review
Затем допишите в schema.yaml:
- id: review
generates: review.md
description: Pre-implementation review checklist
template: review.md
instruction: |
Create a review checklist based on the design.
Include security, performance, and testing considerations.
requires:
- design
- id: tasks
# ... существующая конфигурация tasks ...
requires:
- specs
- design
- review # Теперь tasks требует и review
Инженерный вывод курса: это прямой способ встроить human gate в артефактную цепочку - тема, разобранная в модуле 14 как «ворота» процесса. В терминах capstone-потока из модуля 14 артефакт review - это формализованный human gate до apply.
Community-схемы
OpenSpec поддерживает community-схемы, распределяемые через отдельные репозитории. Это opinionated-workflow, интегрирующие OpenSpec с другими инструментами, - аналог каталога расширений spec-kit. Community-схемы не вендорятся в ядро OpenSpec: они живут в своих репозиториях со своим ритмом релизов. Для использования скопируйте bundle схемы в openspec/schemas/<schema-name>/ своего проекта (инструкции установки - в README каждого репозитория).
| Схема | Мейнтейнер | Репозиторий | Описание |
|---|---|---|---|
intent-driven |
@harikrishnan83 | intent-driven-dev/openspec-schemas | Фиксирует intent изменения, наблюдаемое поведение, технический design и прочные архитектурные решения до реализации. Добавляет change-local ADR review manifest и пишет долгоживущие решения как immutable, замещаемые ADR. |
superpowers-bridge |
@JiangWay | JiangWay/openspec-schemas | Интегрирует артефактное управление OpenSpec с execution-skills Superpowers (brainstorming, writing-plans, TDD через subagents, code review, finishing). Добавляет evidence-first артефакт retrospective. |
nanopm |
@nmrtn | nmrtn/nanopm | PM-first workflow: pipeline планирования nanopm (audit → strategy → roadmap → PRD) выше реализации. Артефакты читаются из .nanopm/: proposal берет audit, design - strategy, tasks - PRD breakdown. |
e2e-runbooks |
@Lukk17 | Lukk17/openspec-schemas | Runbooks e2e-тестов уровня возможности. Каждая возможность - immutable spec, immutable tasks-template и одна timestamped запись на выполнение. Assertions - только наблюдаемое поведение (HTTP status, response body, persisted state); каждая run-запись фиксирует start/end UTC, длительность и оценку потребления токенов LLM. |
anvil |
@jikkujoyce | jikkujoyce/openspec-schemas | Spec-driven workflow с дисциплиной TDD и adversarial review. Поток: proposal → specs → design → review → test-plan → tasks → apply → verify. review пишет ревьюер с чистым контекстом (вторая модель, если есть) и выдает строку VERDICT:; гейт нужно подкрепить своим CI или hook. test-plan отображает каждый сценарий спеки на именованный тест и работает как red/green-леджер, который аудирует verify. |
Полные ссылки на репозитории - в таблице «Community schemas» оригинальной документации. Хотите добавить свою схему - откройте issue со ссылкой на репозиторий или PR со строкой в таблицу.
Мультиязычность: артефакты не на английском
Быстрая настройка
Для нового проекта язык задается при инициализации:
openspec init --language "Portuguese (pt-BR)"
Команда записывает языковую инструкцию в openspec/config.yaml. Если конфиг уже существует, отредактируйте поле context напрямую - так сохранятся существующие настройки проекта.
Тот же результат вручную:
schema: spec-driven
context: |
Language: Russian (ru-RU)
All artifacts must be written in Russian.
Keep OpenSpec structural headings and SHALL/MUST keywords in English.
# Остальной контекст проекта ниже...
Tech stack: TypeScript, React, Node.js
Все генерируемые артефакты будут на выбранном языке.
Ключевой нюанс: структурные заголовки документов OpenSpec и нормативные ключевые слова SHALL/MUST остаются на английском, потому что на них опирается валидация. Проза требований и сценариев вокруг них - на выбранном языке.
Примеры языковых инструкций
context: |
Language: Portuguese (pt-BR)
All artifacts must be written in Brazilian Portuguese.
context: |
Idioma: Español
Todos los artefactos deben escribirse en español.
context: |
语言:中文(简体)
所有产出物必须用简体中文撰写。
context: |
言語:日本語
すべての成果物は日本語で作成してください。
Советы
Технические термины. Решите заранее, как обходиться с терминологией:
context: |
Language: Japanese
Write in Japanese, but:
- Keep technical terms like "API", "REST", "GraphQL" in English
- Code examples and file paths remain in English
Комбинация с другим контекстом. Языковая настройка работает вместе с остальным контекстом проекта:
schema: spec-driven
context: |
Language: Russian (ru-RU)
All artifacts must be written in Russian.
Tech stack: TypeScript, React 18, Node.js 20
Database: PostgreSQL with Prisma ORM
Проверка
Убедиться, что языковая настройка работает:
# Инструкции должны показать ваш языковой контекст
openspec instructions proposal --change my-change
Поддерживаемые инструменты
OpenSpec работает с десятками AI-ассистентов для написания кода. При openspec init OpenSpec настраивает выбранные инструменты в соответствии с активным профилем/workflow и режимом доставки.
Как это работает
Для каждого выбранного инструмента OpenSpec устанавливает:
- Skills (если доставка включает skills):
.../skills/openspec-*/SKILL.md - Commands (если доставка включает commands): специфичные для инструмента файлы команд
opsx-*
Codex - только skills: OpenSpec ставит .agents/skills/openspec-*/SKILL.md для Codex даже когда доставка настроена на commands, и не генерирует кастомные prompt-файлы Codex. Существующие skills под легаси-путем .codex/skills сверяются после записи замен; кастомные и разошедшиеся файлы сохраняются.
По умолчанию используется профиль core:
propose, explore, apply, update, sync, archive
Расширенный набор (new, continue, ff, verify, bulk-archive, onboard) включается через openspec config profile, затем openspec update.
Как вызывать
В документации /opsx:propose - каноническое имя, но каждый инструмент пишет его так, как загружает файл, созданный OpenSpec. Итак, /opsx:propose - это /opsx-propose в Cursor, @opsx-propose в Amazon Q и $openspec-propose в Codex.
| Файл команды, который пишет OpenSpec | Вы вводите | Инструменты |
|---|---|---|
.../commands/opsx/<id>.* - папка opsx/ дает namespace |
/opsx:<id> |
Claude Code, CodeBuddy, Crush, Gemini CLI, Lingma, Qoder, ZCode |
.../opsx-<id>.* - имя файла и есть команда |
/opsx-<id> |
Все остальные инструменты с командами, кроме Amazon Q и Devin |
.devin/workflows/opsx-<id>.md - читает только один из двух агентов Devin |
/opsx-<id> на Devin Desktop, /openspec-<skill> на Devin Local |
Devin Desktop |
.amazonq/prompts/opsx-<id>.md - это prompt, а не команда |
@opsx-<id> |
Amazon Q Developer |
| нет - только skills | /openspec-<skill> |
CodeArts, ForgeCode, Hermes, MiniMax Code, Mistral Vibe, Zed Agent, shared .agents |
| нет - Kimi Code | /skill:openspec-<skill> |
Kimi Code |
| нет - Codex CLI | $openspec-<skill> |
Codex (/openspec-<skill> не распознается) |
Две вещи варьируются независимо, поэтому строки таблицы не схлопываются:
- Имя. Первые две строки различаются только тем, как файл называет команду; стем
opsx-<id>/opsx:<id>один и тот же для всех инструментов с командными файлами. - Обертка. Amazon Q загружает файлы в библиотеку промптов, вызываемую через
@. Инструменты только-skills вообще не генерируют командных файлов, поэтому у них последние строки используют имена skills - из списка ниже - которые не отображаются один к одному на id команд (/opsx:apply- это skillopenspec-apply-change).
Паттерны путей команд расширение-нейтральны (.*) намеренно: расширение выбирает инструмент (.toml у Gemini CLI, .prompt у Continue, .prompt.md у Kiro и GitHub Copilot), и некоторые инструменты показывают имя с расширением. Сверяйте форму каталога, а не расширение.
Файлы, которые генерирует OpenSpec, и подсказка «Getting started» после установки уже используют правильную форму для выбранных вами инструментов - самый быстрый ответ просто прочитать подсказку.
Справочник каталогов инструментов
| Инструмент (ID) | Паттерн skills | Паттерн команд |
|---|---|---|
Amazon Q Developer (amazon-q) |
.amazonq/skills/openspec-*/SKILL.md |
.amazonq/prompts/opsx-<id>.md |
Antigravity (antigravity) |
.agent/skills/openspec-*/SKILL.md |
.agent/workflows/opsx-<id>.md |
Auggie (auggie) |
.augment/skills/openspec-*/SKILL.md |
.augment/commands/opsx-<id>.md |
IBM Bob Shell (bob) |
.bob/skills/openspec-*/SKILL.md |
.bob/commands/opsx-<id>.md |
Claude Code (claude) |
.claude/skills/openspec-*/SKILL.md |
.claude/commands/opsx/<id>.md |
Cline (cline) |
.cline/skills/openspec-*/SKILL.md |
.clinerules/workflows/opsx-<id>.md |
Command Code (command-code) |
.commandcode/skills/openspec-*/SKILL.md |
.commandcode/commands/opsx-<id>.md |
CodeArts (codeartsagent) |
.codeartsdoer/skills/openspec-*/SKILL.md |
Не генерируются (нет command adapter; используйте /openspec-*) |
CodeBuddy (codebuddy) |
.codebuddy/skills/openspec-*/SKILL.md |
.codebuddy/commands/opsx/<id>.md |
Codex (codex) |
.agents/skills/openspec-*/SKILL.md |
Не генерируются (skills-only; используйте $openspec-*) |
Devin Desktop, ранее Windsurf (devin) |
.devin/skills/openspec-*/SKILL.md |
.devin/workflows/opsx-<id>.md |
ForgeCode (forgecode) |
.forge/skills/openspec-*/SKILL.md |
Не генерируются (нет command adapter; используйте /openspec-*) |
Continue (continue) |
.continue/skills/openspec-*/SKILL.md |
.continue/prompts/opsx-<id>.prompt |
CoStrict (costrict) |
.cospec/skills/openspec-*/SKILL.md |
.cospec/openspec/commands/opsx-<id>.md |
Crush (crush) |
.crush/skills/openspec-*/SKILL.md |
.crush/commands/opsx/<id>.md |
Cursor (cursor) |
.cursor/skills/openspec-*/SKILL.md |
.cursor/commands/opsx/<id>.md |
Factory Droid (factory) |
.factory/skills/openspec-*/SKILL.md |
.factory/commands/opsx-<id>.md |
Gemini CLI (gemini) |
.gemini/skills/openspec-*/SKILL.md |
.gemini/commands/opsx/<id>.toml |
GitHub Copilot (github-copilot) |
.github/skills/openspec-*/SKILL.md |
.github/prompts/opsx-<id>.prompt.md |
Hermes Agent (hermes) |
.hermes/skills/openspec-*/SKILL.md |
Не генерируются (нет command adapter; используйте /openspec-*) |
iFlow (iflow) |
.iflow/skills/openspec-*/SKILL.md |
.iflow/commands/opsx-<id>.md |
Junie (junie) |
.junie/skills/openspec-*/SKILL.md |
.junie/commands/opsx-<id>.md |
Kilo Code (kilocode) |
.kilocode/skills/openspec-*/SKILL.md |
.kilo/command/opsx-<id>.md |
Kimi Code (kimi) |
.kimi-code/skills/openspec-*/SKILL.md |
Не генерируются (нет command adapter; используйте /skill:openspec-*) |
Kiro (kiro) |
.kiro/skills/openspec-*/SKILL.md |
.kiro/prompts/opsx-<id>.prompt.md |
Lingma (lingma) |
.lingma/skills/openspec-*/SKILL.md |
.lingma/commands/opsx/<id>.md |
MiniMax Code (minimax-code) |
~/.minimax/skills/openspec-*/SKILL.md |
Не генерируются (глобальные skills-only) |
Mistral Vibe (vibe) |
.vibe/skills/openspec-*/SKILL.md |
Не генерируются (нет command adapter; используйте /openspec-*) |
Oh My Pi (oh-my-pi) |
.omp/skills/openspec-*/SKILL.md |
.omp/commands/opsx-<id>.md |
OpenCode (opencode) |
.opencode/skills/openspec-*/SKILL.md |
.opencode/commands/opsx-<id>.md |
Pi (pi) |
.pi/skills/openspec-*/SKILL.md |
.pi/prompts/opsx-<id>.md |
SourceCraft Code Assistant (codeassistant) |
.codeassistant/skills/openspec-*/SKILL.md |
.codeassistant/commands/opsx-<id>.md |
Qoder (qoder) |
.qoder/skills/openspec-*/SKILL.md |
.qoder/commands/opsx/<id>.md |
Qwen Code (qwen) |
.qwen/skills/openspec-*/SKILL.md |
.qwen/commands/opsx-<id>.md |
Rovo Dev CLI (rovodev) |
.rovodev/skills/openspec-*/SKILL.md |
Не генерируются (нет slash-поверхности; skills матчатся автоматически или промптом) |
Zoo Code (roocode) |
.roo/skills/openspec-*/SKILL.md |
.roo/commands/opsx-<id>.md |
Trae (trae) |
.trae/skills/openspec-*/SKILL.md |
.trae/commands/opsx-<id>.md |
Zed Agent (zed) |
.agents/skills/openspec-*/SKILL.md |
Не генерируются (skills-only; используйте /openspec-* или @openspec-*) |
ZCode (zcode) |
.zcode/skills/openspec-*/SKILL.md |
.zcode/commands/opsx/<id>.md |
Shared .agents (agents) |
.agents/skills/openspec-*/SKILL.md |
Не генерируются (нет command adapter; используйте /openspec-*) |
Нюансы, которые стоит знать:
- GitHub Copilot. Prompt-файлы распознаются как кастомные слэш-команды в IDE-расширениях (VS Code, JetBrains, Visual Studio). Copilot CLI не читает
.github/prompts/*.prompt.mdнапрямую. Выборgithub-copilotможет также настроить облачного coding-агента GitHub (см. ниже). - Hermes. Читает skills из
~/.hermes/skills/по умолчанию. Для проектных skills добавьте каталог.hermes/skills/проекта вskills.external_dirsв~/.hermes/config.yaml; тогда Hermes открывает skills слэш-вызовами вида/openspec-propose. - Devin Desktop. Windsurf переименован в Devin Desktop 2 июня 2026 года; каталог конфигурации переехал:
.devin/- предпочтительное место чтения и записи,.windsurf/- легаси read-only fallback. ID инструмента -devin, но--tools windsurfпо-прежнему резолвится в него. Проект со старыми файлами в.windsurf/получит предложение переехать при следующемopenspec update. Devin Local не поддерживает workflows - только skills и вообще не читает.windsurf/, поэтому skills для Devin держат вызовы/openspec-*, работающие у обоих агентов. - SourceCraft. Поддержка - только расширение VS Code; web и JetBrains не настраиваются.
- MiniMax Code. Глобальная skills-only интеграция: пишется только
~/.minimax/skills/; репо-локальных каталогов нет. Commands-only доставка не трогает существующие глобальные skills - настройки одного проекта не могут удалить skills, которыми пользуется другое.
Облачный coding-агент GitHub Copilot
Облачный Copilot coding agent работает на GitHub в окружении GitHub Actions - отдельно от Copilot в редакторе. OpenSpec может настроить его на использование CLI, сгенерировав два файла:
.github/workflows/copilot-setup-steps.yml- ставит@fission-ai/openspecв окружение агента;.github/agents/openspec.agent.md- объясняет агенту, как управлять OpenSpec.
Поскольку это пишет GitHub Actions workflow в ваш репозиторий, настройка - opt-in:
| Способ | Поведение |
|---|---|
openspec init (интерактивно) |
Спрашивает, настраивать ли облачные файлы. Дефолт - нет. |
openspec init --copilot-cloud |
Настраивает без вопросов (для скриптов/CI). |
openspec init --no-copilot-cloud |
Пропускает без вопросов и удаляет ранее сгенерированные. |
openspec update |
Никогда не спрашивает. Обновляет файлы, только если вы согласились (или они уже есть). Если вы отказались - удаляет облачные файлы, управляемые OpenSpec. |
Выбор сохраняется в openspec/config.yaml как githubCopilot.cloudAgent: true|false, поэтому неинтерактивные обновления его уважают. OpenSpec пишет и удаляет только файлы, чье содержимое сам сгенерировал: если вы кастомизировали copilot-setup-steps.yml или openspec.agent.md или имели свои - они не тронуты (и init/update об этом сообщают).
Когда выбирать shared .agents
agents - vendor-нейтральная опция: пишет skills в .agents/skills/ - общий корень, который читают многие инструменты, - вместо специфичного для инструмента каталога.
| Ситуация | Выбор |
|---|---|
| У вашего инструмента есть своя строка выше | Его собственный ID - получите интеграцию инструмента, включая слэш-команды, где они поддерживаются |
Несколько агентов в одном репо, все читают .agents/skills |
agents - одно дерево skills вместо дерева на инструмент |
Инструмента нет в списке, но он читает .agents/skills |
agents |
Выбор вместе со специфичным ID - нормально: каждый пишет в свой корень. Исключения - Codex и Zed Agent, использующие один канонический корень .agents. Если Codex выбран вместе с Zed или agents, OpenSpec держит одно Codex-ведомое дерево; его handoffs называют и $openspec-* для Codex, и /openspec-* для остальных агентов. OpenSpec также предлагает agents автоматически, когда в проекте есть каталог .agents/skills/ (голого .agents/ мало - инструменты используют этот корень и для правил, и для subagent-определений). Заметьте: .agents - не .agent: единственное число принадлежит Antigravity.
Два факта:
- Только skills. Command adapter нет, командных файлов
opsx-*не появится; при доставке с командамиopenspec initперечислитagentsпод «Commands skipped for: ... (no adapter)». Workflow вызывается по имени skill - большинство ассистентов пишут это/openspec-propose. AGENTS.mdне создается и не редактируется. Цель - каталог.agents/. Если в корневомAGENTS.mdостались маркерные блоки OpenSpec от старой версии,openspec updateих уберет (урок 15.15).
Zed: поддержка - встроенный Zed Agent; External Agents и Terminal Threads имеют свои интеграции. Agent Skills требуют Zed v1.4.2+; проектные skills недоступны в недоверенном worktree, пока вы не выдадите trust.
В .agents/skills/ OpenSpec пишет, обновляет и удаляет только каталоги skills openspec-* для выбранных workflow плюс маркер .openspec-target, фиксирующий, кто отрисовал общее дерево (Codex, Zed Agent или vendor-нейтральная цель). Остальное в каталоге не трогается. Правки внутри openspec-* будут заменены при следующем openspec update - как у любого другого инструмента. Для проектов до появления маркеров владение выводится из управляемых ссылок: $openspec-* означает Codex, /openspec-* - vendor-нейтральную цель.
Неинтерактивная установка
Для CI/CD и скриптов - --tools (и опционально --profile):
# Настроить конкретные инструменты
openspec init --tools claude,cursor
# Настроить все поддерживаемые инструменты
openspec init --tools all
# Пропустить настройку инструментов
openspec init --tools none
# Переопределить профиль для этого запуска init
openspec init --profile core
Доступные ID инструментов (--tools; windsurf принимается как алиас devin):
amazon-q, antigravity, auggie, bob, claude, cline, command-code,
codeartsagent, codex, devin, forgecode, codebuddy, continue, costrict,
crush, cursor, factory, gemini, github-copilot, hermes, iflow, junie,
kilocode, kimi, kiro, lingma, minimax-code, vibe, oh-my-pi, opencode,
pi, qoder, qwen, roocode, codeassistant, trae, zed, zcode, agents
Зависимость установки от workflow
OpenSpec ставит артефакты workflow по выбранным workflow:
- Профиль core (дефолт):
propose,explore,apply,update,sync,archive - Свой набор: любое подмножество из
propose,explore,new,continue,apply,update,ff,sync,archive,bulk-archive,verify,onboard
Количество skills и команд зависит от профиля и режима доставки - оно не фиксировано.
Сгенерированные имена skills
При выборе по профилю/workflow OpenSpec генерирует эти skills:
openspec-propose
openspec-explore
openspec-new-change
openspec-continue-change
openspec-apply-change
openspec-update-change
openspec-ff-change
openspec-sync-specs
openspec-archive-change
openspec-bulk-archive-change
openspec-verify-change
openspec-onboard
Community-витрина
Community-витрина - общий awesome-список проектов и ресурсов, созданных с OpenSpec и для него. Проекты в списке поддерживаются независимо; попадание в список не означает официальной поддержки.
Примеры на срез документации:
- OpenSpec Workbench - запуск и надзор за агентами на изменениях OpenSpec;
- MySpec - облачная beta (нужен аккаунт): проводит управляемые spec-интервью и экспортирует бандлы из четырех файлов или совместимые с OpenSpec изменения. Сервис отправляет контент сторонним AI-провайдерам и не предназначен для чувствительных данных;
- openspec-guard - CLI и GitHub Action, сообщающие, какие сценарии OpenSpec покрыты тестом Vitest или Jest, без запуска тестов.
Добавить свой проект можно PR-ом: строка с именем, прямой ссылкой и коротким описанием связи с OpenSpec. Требования - фокус на построенном с OpenSpec или поддерживающем его использование, без рекламных формулировок, реферальных и трекинг-ссылок; платные функции и обязательные аккаунты должны быть раскрыты.
Практика
- В тестовом проекте выполните
openspec initи выберите свой основной инструмент; проверьте, какие пути из справочника выше реально появились. - Добавьте в
openspec/config.yamlконтекст проекта (стек, конвенции) и правило дляproposal(например, «Include rollback plan»). Создайте изменение и проверьте в сгенерированном proposal, что правило сработало. - Выполните
openspec schema fork spec-driven my-team-flowи изучитеschema.yamlи шаблоны; добавьте артефактreview, требующийdesign, и перевалидируйте схемуopenspec schema validate my-team-flow. - Настройте генерацию артефактов на русском: добавьте языковую инструкцию в
contextи проверьте черезopenspec instructions proposal --change <name>.
Краткое резюме
- Три уровня настройки:
openspec/config.yaml(схема-дефолт,contextво все артефакты,rulesпо артефактам,operations.*.guidanceкак советы apply/archive), кастомные схемы вopenspec/schemas/(свои артефакты, шаблоны и зависимостиrequires), глобальные схемы пользователя для шаринга между проектами. - Схемы:
openspec schema forkдля быстрого старта,schema initс нуля,schema validateперед использованием,schema whichдля отладки резолюции. - Community-схемы - opinionated-workflow из отдельных репозиториев; копируются в
openspec/schemas/. - Мультиязычность - строка в
context;SHALL/MUSTи структурные заголовки остаются на английском, проза - на вашем языке. - 30+ инструментов: skills (
openspec-*/SKILL.md) и/или команды (opsx-*); написание вызова зависит от инструмента (/opsx:,/opsx-,@opsx-,$openspec-,/skill:openspec-); shared.agents- vendor-нейтральный корень; облачный Copilot-агент - opt-in черезgithubCopilot.cloudAgent.
Вопросы для самопроверки
- Чем
contextотличается отrulesпо охвату артефактов, аrules- отoperations.apply.guidanceпо сфере действия? - В каком порядке резолвится схема: флаг CLI, метаданные изменения, конфиг проекта, дефолт?
- Что означают поля
generates,requiresиinstructionвschema.yamlи что решает порядок спискаartifacts:? - Почему языковая инструкция запрещает переводить
SHALL/MUSTи структурные заголовки? - Почему
/opsx:proposeв разных инструментах пишется по-разному и где узнать правильную форму для вашего инструмента? - Чем выбор
agents(shared.agents/skills/) отличается от выбора специфичного ID инструмента, и какое исключение создает конфликт между Codex и Zed? - Почему настройка облачного Copilot-агента - opt-in, и где хранится выбор?
Что дальше
Урок 15.14 заглядывает под капот OPSX: почему workflow гибкий, а не phase-locked, как устроена архитектура артефакт-ориентированного цикла, и что такое Agent Contract - machine-readable CLI-поверхности, которыми пользуются агенты.