Agent Dev 101

Модуль 15 · Урок 15.13

Урок 15.13. Кастомизация, мультиязычность и поддержка инструментов

На этой странице
  1. Зачем это нужно
  2. Основная идея
  3. Конфигурация проекта
  4. Кастомные схемы
  5. Мультиязычность: артефакты не на английском
  6. Поддерживаемые инструменты
  7. Community-витрина
  8. Практика
  9. Краткое резюме
  10. Вопросы для самопроверки
  11. Что дальше
  12. Источники

Зачем это нужно

Стандартный workflow OpenSpec (proposal → specs → design → tasks → apply → archive) устроен так, что его хватает большинству команд. Но реальные проекты отличаются: у одной команды стек и конвенции, у другой - собственный процесс с обязательным ревью до реализации, у третьей - артефакты должны писаться на русском или португальском.

OpenSpec отвечает тремя уровнями настройки и одним накладным вопросом:

  • конфигурация проекта - дефолты и контекст для большинства команд;
  • кастомные схемы - собственный набор артефактов для команд с уникальным процессом;
  • глобальные override - шары схем между проектами;

и отдельно - где физически записываются файлы skills и команд для каждого из 30+ поддерживаемых AI-инструментов.

Основная идея

Кастомизация OpenSpec держится на одном файле и одном каталоге:

text
openspec/config.yaml     настройки проекта: схема по умолчанию, контекст, правила
openspec/schemas/        собственные схемы: свои артефакты, шаблоны, зависимости

Все настройки в итоге попадают в один и тот же механизм: при генерации артефакта контекст, правила и шаблон схемы инжектятся в промпт AI-агента. OpenSpec не форсирует процесс - он поставляет материал, из которого агент собирает артефакт под ваш процесс.

Три уровня настройки:

Уровень Что делает Кому подходит
Конфигурация проекта Дефолты и инжект контекста/правил Большинству команд
Кастомные схемы Собственные артефакты workflow Командам с уникальным процессом
Глобальные override Шары схем между всеми проектами Продвинутым пользователям

Конфигурация проекта

openspec/config.yaml - простейший способ настроить OpenSpec под команду. Файл позволяет:

  • задать схему по умолчанию - не передавать --schema каждой команде;
  • инжектить контекст проекта - агент видит ваш стек, конвенции и ограничения;
  • добавить правила по артефактам - свои правила для конкретных артефактов;
  • добавить guidance по операциям - советы для работы apply и archive;
  • запомнить выбор интеграций - например, opt-in для облачного coding-агента GitHub Copilot.

Быстрая настройка

Интерактивно (создаст конфиг по шагам):

bash
openspec init

Или вручную:

yaml
# 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

Как это работает

Схема по умолчанию:

bash
# Без конфига
openspec new change my-feature --schema spec-driven

# С конфигом - схема подставляется сама
openspec new change my-feature

Инжект контекста и правил. При генерации любого артефакта контекст и правила попадают в промпт агента:

xml
<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 получают эти входы в момент выполнения:

bash
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 нужна схема, он проверяет в этом порядке:

  1. Флаг CLI: --schema <name>
  2. Метаданные изменения (.openspec.yaml в папке изменения)
  3. Конфигурация проекта (openspec/config.yaml)
  4. Дефолт (spec-driven)

Кастомные схемы

Когда конфигурации проекта мало, создайте собственную схему с полностью кастомным workflow. Кастомные схемы живут в каталоге openspec/schemas/ проекта и версионируются вместе с кодом.

text
your-project/
├── openspec/
│   ├── config.yaml        # Конфигурация проекта
│   ├── schemas/          # Здесь живут кастомные схемы
│   │   └── my-workflow/
│   │       ├── schema.yaml
│   │       └── templates/
│   └── changes/           # Ваши изменения
└── src/

Форк существующей схемы

Быстрее всего кастомизировать форком встроенной схемы:

bash
openspec schema fork spec-driven my-workflow

Команда копирует схему spec-driven целиком в openspec/schemas/my-workflow/, где ее можно свободно править. Что вы получаете:

text
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:

bash
# Интерактивно
openspec schema init research-first

# Неинтерактивно
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

Структура схемы

Схема определяет артефакты workflow и их зависимости:

yaml
# 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. Они инжектятся в промпт при создании артефакта.

markdown
<!-- 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;
  • примеры формата ожидаемой структуры.

Валидация схемы

Перед использованием кастомной схемы проверьте ее:

bash
openspec schema validate my-workflow

Проверяется:

  • синтаксис schema.yaml корректен;
  • все упоминаемые шаблоны существуют;
  • циклических зависимостей нет;
  • ID артефактов валидны.

Использование и отладка

bash
# Указать в команде
openspec new change feature --schema my-workflow

# Или сделать дефолтом в config.yaml
schema: my-workflow

Неясно, какая схема используется? Проверьте:

bash
# Откуда резолвится конкретная схема
openspec schema which my-workflow

# Список всех доступных схем
openspec schema which --all

Вывод показывает источник - проект, пользовательский каталог или пакет:

text
Schema: my-workflow
Source: project
Path: /path/to/project/openspec/schemas/my-workflow

Важно: OpenSpec также поддерживает схемы уровня пользователя в ~/.local/share/openspec/schemas/ - для шаринга между проектами. Но рекомендуется хранить схемы в проекте (openspec/schemas/): они версионируются вместе с кодом.

Пример: схема rapid

Минимальный workflow для быстрых итераций:

yaml
# 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

Форкните дефолт и добавьте шаг ревью:

bash
openspec schema fork spec-driven with-review

Затем допишите в schema.yaml:

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 со строкой в таблицу.

Мультиязычность: артефакты не на английском

Быстрая настройка

Для нового проекта язык задается при инициализации:

bash
openspec init --language "Portuguese (pt-BR)"

Команда записывает языковую инструкцию в openspec/config.yaml. Если конфиг уже существует, отредактируйте поле context напрямую - так сохранятся существующие настройки проекта.

Тот же результат вручную:

yaml
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 остаются на английском, потому что на них опирается валидация. Проза требований и сценариев вокруг них - на выбранном языке.

Примеры языковых инструкций

yaml
context: |
  Language: Portuguese (pt-BR)
  All artifacts must be written in Brazilian Portuguese.
yaml
context: |
  Idioma: Español
  Todos los artefactos deben escribirse en español.
yaml
context: |
  语言:中文(简体)
  所有产出物必须用简体中文撰写。
yaml
context: |
  言語:日本語
  すべての成果物は日本語で作成してください。

Советы

Технические термины. Решите заранее, как обходиться с терминологией:

yaml
context: |
  Language: Japanese
  Write in Japanese, but:
  - Keep technical terms like "API", "REST", "GraphQL" in English
  - Code examples and file paths remain in English

Комбинация с другим контекстом. Языковая настройка работает вместе с остальным контекстом проекта:

yaml
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

Проверка

Убедиться, что языковая настройка работает:

bash
# Инструкции должны показать ваш языковой контекст
openspec instructions proposal --change my-change

Поддерживаемые инструменты

OpenSpec работает с десятками AI-ассистентов для написания кода. При openspec init OpenSpec настраивает выбранные инструменты в соответствии с активным профилем/workflow и режимом доставки.

Как это работает

Для каждого выбранного инструмента OpenSpec устанавливает:

  1. Skills (если доставка включает skills): .../skills/openspec-*/SKILL.md
  2. Commands (если доставка включает commands): специфичные для инструмента файлы команд opsx-*

Codex - только skills: OpenSpec ставит .agents/skills/openspec-*/SKILL.md для Codex даже когда доставка настроена на commands, и не генерирует кастомные prompt-файлы Codex. Существующие skills под легаси-путем .codex/skills сверяются после записи замен; кастомные и разошедшиеся файлы сохраняются.

По умолчанию используется профиль core:

text
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 - это skill openspec-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):

bash
# Настроить конкретные инструменты
openspec init --tools claude,cursor

# Настроить все поддерживаемые инструменты
openspec init --tools all

# Пропустить настройку инструментов
openspec init --tools none

# Переопределить профиль для этого запуска init
openspec init --profile core

Доступные ID инструментов (--tools; windsurf принимается как алиас devin):

text
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:

text
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 или поддерживающем его использование, без рекламных формулировок, реферальных и трекинг-ссылок; платные функции и обязательные аккаунты должны быть раскрыты.

Практика

  1. В тестовом проекте выполните openspec init и выберите свой основной инструмент; проверьте, какие пути из справочника выше реально появились.
  2. Добавьте в openspec/config.yaml контекст проекта (стек, конвенции) и правило для proposal (например, «Include rollback plan»). Создайте изменение и проверьте в сгенерированном proposal, что правило сработало.
  3. Выполните openspec schema fork spec-driven my-team-flow и изучите schema.yaml и шаблоны; добавьте артефакт review, требующий design, и перевалидируйте схему openspec schema validate my-team-flow.
  4. Настройте генерацию артефактов на русском: добавьте языковую инструкцию в 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.

Вопросы для самопроверки

  1. Чем context отличается от rules по охвату артефактов, а rules - от operations.apply.guidance по сфере действия?
  2. В каком порядке резолвится схема: флаг CLI, метаданные изменения, конфиг проекта, дефолт?
  3. Что означают поля generates, requires и instruction в schema.yaml и что решает порядок списка artifacts:?
  4. Почему языковая инструкция запрещает переводить SHALL/MUST и структурные заголовки?
  5. Почему /opsx:propose в разных инструментах пишется по-разному и где узнать правильную форму для вашего инструмента?
  6. Чем выбор agents (shared .agents/skills/) отличается от выбора специфичного ID инструмента, и какое исключение создает конфликт между Codex и Zed?
  7. Почему настройка облачного Copilot-агента - opt-in, и где хранится выбор?

Что дальше

Урок 15.14 заглядывает под капот OPSX: почему workflow гибкий, а не phase-locked, как устроена архитектура артефакт-ориентированного цикла, и что такое Agent Contract - machine-readable CLI-поверхности, которыми пользуются агенты.

Источники

Обновлено 03.10.2026