Personalização

O OpenSpec oferece três níveis de personalização:

Nível	O que faz	Ideal para
Configuração do Projeto	Define padrões, injeta contexto/regras	A maioria das equipes
Schemas Personalizados	Define seus próprios artefatos de fluxo de trabalho	Equipes com processos únicos
Substituições Globais	Compartilha schemas entre todos os projetos	Usuários avançados

---

Configuração do Projeto

O arquivo openspec/config.yaml é a maneira mais fácil de personalizar o OpenSpec para sua equipe. Ele permite que você:

• Defina um schema padrão - Pule --schema em todos os comandos
• Injete contexto do projeto - A IA vê sua stack tecnológica, convenções, etc.
• Adicione regras por artefato - Regras personalizadas para artefatos específicos
• Adicione orientação por operação - Preferências de aconselhamento para trabalhos de apply e archive
• Lembre escolhas de integração - ex. a aceitação do agente de codificação em nuvem GitHub Copilot

Configuração Rápida

openspec init

Isso guia você na criação de uma configuração de forma interativa. Ou crie uma manualmente:

# 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

# Set by `openspec init` when you choose (or decline) the GitHub Copilot
# cloud coding agent; controls whether `init`/`update` generate its files.
githubCopilot:
  cloudAgent: false

Como Funciona

Schema padrão:

# Sem configuração
openspec new change my-feature --schema spec-driven

# Com configuração - o schema é automático
openspec new change my-feature

Injeção de contexto e regras:

Ao gerar qualquer artefato, seu contexto e suas regras são injetados no prompt da IA:

<context>
Tech stack: TypeScript, React, Node.js, PostgreSQL
...
</context>

<rules>
- Include rollback plan
- Identify affected teams
</rules>

<template>
[Template integrado do schema]
</template>

• Contexto aparece em TODOS os artefatos
• Regras aparecem SOMENTE para o artefato correspondente

Orientação de operação:

operations.apply.guidance e operations.archive.guidance são matrizes opcionais de instruções de aconselhamento sobre como um agente deve conduzir essas operações. Elas são separadas das rules: a orientação de operação não restringe o conteúdo dos artefatos, e as regras de artefatos nunca são rotuladas como orientação de operação.

Apply e archive buscam essas entradas no momento da execução:

openspec instructions apply --change my-feature --json
openspec instructions archive --change my-feature --json

Ambas as superfícies retornam o context atual do projeto e a operationGuidance correspondente como campos opcionais separados. Cada invocação lê um snapshot atualizado da raiz resolvida. Quando --store <id> é selecionado, a mudança, o contexto e a orientação vêm todos desse store, em vez do repositório atual. O comando de instrução de archive é somente leitura: ele não inspeciona ou mescla delta specs, não escreve main specs, não move a mudança e não executa o fluxo de trabalho de arquivamento estático.

O contexto do projeto é uma entrada obrigatória no nível do prompt. Os fluxos de trabalho gerados o leem e aplicam fatos, convenções e restrições relevantes do projeto. A orientação de operação é um conselho adicional opcional: os fluxos de trabalho consideram cada entrada e seguem as entradas que são aplicáveis e compatíveis com o fluxo de trabalho integrado.

Ambos os campos permanecem separados do estado controlado pela CLI, caminhos resolvidos, etapas integradas, escolhas explícitas do usuário e regras de artefatos. Um fluxo de trabalho relata conflitos de contexto preservando o valor controlador. Ele não segue orientação inaplicável ou conflitante e explica o porquê. Nenhum campo é uma verificação aplicável, e os fluxos de trabalho não copiam seu texto para arquivos de implementação, specs, artefatos de mudança ou resumos, a menos que o usuário solicite esse conteúdo separadamente.

Segurança de entrada de archive e sincronização de specs:

Archive, archive em lote e sincronização independente usam artifactPaths.specs.existingOutputPaths de openspec status --json como a única fonte de delta-spec. Um schema sem um artefato de specs, ou uma mudança cuja lista de saídas concretas está vazia, não tem nada para sincronizar; outros artefatos não são usados para inferir delta specs.

Antes de uma mesclagem semântica escrever um main spec, o fluxo de trabalho consome a saída atual de openspec instructions specs --change <name> --json. As regras de specs retornadas restringem apenas os main specs produzidos por essa mesclagem. O arquivamento único passa esse snapshot para a sincronização inline, a sincronização independente o busca diretamente, e o arquivamento em lote obtém cada snapshot necessário antes da primeira escrita de spec. Uma resposta de instrução de archive/specs JSON inválida ou com código de saída diferente de zero é uma falha de busca, não uma entrada vazia: o fluxo de trabalho para antes da escrita do spec afetado ou do movimento da mudança (para arquivamento em lote, antes de qualquer escrita ou movimento em lote).

Esta configuração não altera as fases de execução do arquivamento, prompts do usuário, operações do sistema de arquivos, a propriedade da mesclagem semântica, o comando direto openspec archive ou a estrutura e a saída das regras de artefatos.

Ordem de Resolução do Schema

Quando o OpenSpec precisa de um schema, ele verifica nesta ordem:

1. Flag da CLI: --schema <nome>
2. Metadados da mudança (.openspec.yaml na pasta da mudança)
3. Configuração do projeto (openspec/config.yaml)
4. Padrão (spec-driven)

---

Esquemas Personalizados

Quando a configuração do projeto não é suficiente, crie seu próprio esquema com um fluxo de trabalho totalmente personalizado. Esquemas personalizados ficam no diretório openspec/schemas/ do seu projeto e são versionados junto com seu código.

your-project/
├── openspec/
│   ├── config.yaml        # Project config
│   ├── schemas/           # Custom schemas live here
│   │   └── my-workflow/
│   │       ├── schema.yaml
│   │       └── templates/
│   └── changes/           # Your changes
└── src/

Criar um Fork de um Esquema Existente

A maneira mais rápida de personalizar é criar um fork de um esquema embutido:

openspec schema fork spec-driven my-workflow

Isso copia todo o esquema spec-driven para openspec/schemas/my-workflow/, onde você pode editá-lo livremente.

O que você recebe:

openspec/schemas/my-workflow/
├── schema.yaml           # Workflow definition
└── templates/
    ├── proposal.md       # Template for proposal artifact
    ├── spec.md           # Template for specs
    ├── design.md         # Template for design
    └── tasks.md          # Template for tasks

Agora edite o schema.yaml para alterar o fluxo de trabalho, ou edite os templates para alterar o que a IA gera.

Criar um Esquema do Zero

Para um fluxo de trabalho completamente novo:

# Interactive
openspec schema init research-first

# Non-interactive
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

Estrutura do Esquema

Um esquema define os artefatos do seu fluxo de trabalho e como eles dependem uns dos outros:

# 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    # Can't create design until proposal exists

  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    requires:
      - design

apply:
  requires: [tasks]
  tracks: tasks.md

Campos principais:

Campo	Propósito
id	Identificador único, usado em comandos e regras
generates	Nome do arquivo de saída (suporta globs como specs/**/*.md)
template	Arquivo de template no diretório templates/
instruction	Instruções para a IA ao criar este artefato
requires	Dependências — quais artefatos devem existir primeiro

Liste os artefatos na ordem em que deseja que sejam escritos. requires determina o que é possível; a ordem da lista artifacts: determina o que vem primeiro quando vários artefatos estão prontos ao mesmo tempo.

Templates

Templates são arquivos markdown que orientam a IA. Eles são injetados no prompt ao criar aquele artefato.

<!-- 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 -->

Templates podem incluir:

• Cabeçalhos de seção que a IA deve preencher
• Comentários HTML com orientações para a IA
• Formatos de exemplo mostrando a estrutura esperada

Validar Seu Esquema

Antes de usar um esquema personalizado, valide-o:

openspec schema validate my-workflow

Isso verifica:

• A sintaxe do schema.yaml está correta
• Todos os templates referenciados existem
• Não há dependências circulares
• Os IDs dos artefatos são válidos

Usar Seu Esquema Personalizado

Uma vez criado, use seu esquema com:

# Specify on command
openspec new change feature --schema my-workflow

# Or set as default in config.yaml
schema: my-workflow

Depurar a Resolução de Esquemas

Não tem certeza de qual esquema está sendo usado? Verifique com:

# See where a specific schema resolves from
openspec schema which my-workflow

# List all available schemas
openspec schema which --all

A saída mostra se ele vem do seu projeto, do diretório do usuário ou do pacote:

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

---

Nota: O OpenSpec também suporta esquemas em nível de usuário em ~/.local/share/openspec/schemas/ para compartilhamento entre projetos, mas esquemas em nível de projeto em openspec/schemas/ são recomendados, pois são versionados junto com seu código.

---

Exemplos

Fluxo de Iteração Rápida

Um fluxo de trabalho mínimo para iterações rápidas:

# 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

Adicionar um Artefato de Revisão

Crie um fork do padrão e adicione uma etapa de revisão:

openspec schema fork spec-driven with-review

Depois edite o schema.yaml para adicionar:

  - 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
    # ... existing tasks config ...
    requires:
      - specs
      - design
      - review    # Now tasks require review too

---

Esquemas da Comunidade

O OpenSpec também suporta esquemas mantidos pela comunidade, distribuídos por meio de repositórios independentes. Eles fornecem fluxos de trabalho com opiniões que integram o OpenSpec com outras ferramentas ou sistemas, semelhante ao funcionamento do catálogo de extensões da comunidade do github/spec-kit para o spec-kit.

Esquemas da comunidade não são incorporados ao núcleo do OpenSpec — eles ficam em seus próprios repositórios com seu próprio ritmo de lançamentos. Para usar um, copie o pacote do esquema para o diretório openspec/schemas/<schema-name>/ do seu projeto (o README de cada repositório contém instruções de instalação).

Esquema	Mantenedor	Repositório	Descrição
intent-driven	@harikrishnan83	intent-driven-dev/openspec-schemas	Captura a intenção da mudança, comportamento observável, design técnico e decisões arquitetônicas duráveis antes da implementação. Adiciona um manifesto de revisão de ADR local à mudança e grava decisões de longa duração qualificadas como ADRs imutáveis e substituíveis.
superpowers-bridge	@JiangWay	JiangWay/openspec-schemas	Integra a governança de artefatos do OpenSpec com as habilidades de execução do obra/superpowers (brainstorming, writing-plans, TDD via subagents, code review, finishing). Adiciona um artefato retrospective baseado em evidências, preenchendo uma lacuna que o Superpowers não cobre nativamente.
nanopm	@nmrtn	nmrtn/nanopm	Fluxo de trabalho centrado em PM. Executa o pipeline de planejamento do nanopm (audit → strategy → roadmap → PRD) antes da implementação. Faz a ponte entre o planejamento de produto e o fluxo de trabalho de engenharia orientado por especificações do OpenSpec. Os artefatos são lidos de .nanopm/ se presente — a proposta usa o audit como fonte, o design usa a strategy como fonte, e as tasks usam a quebra do PRD como fonte.
e2e-runbooks	@Lukk17	Lukk17/openspec-schemas	Runbooks de testes ponta a ponta em nível de capacidade. Cada capacidade recebe uma especificação imutável, um template de tasks imutável e um registro de execução com timestamp por execução. As asserções são apenas comportamento observável (status HTTP, corpo da resposta, estado persistido — nunca substrings de log); cada execução registra início/fim em UTC, duração e consumo estimado de tokens de LLM.
anvil	@jikkujoyce	jikkujoyce/openspec-schemas	Fluxo de trabalho orientado por especificações com disciplina de TDD e uma etapa de revisão adversarial. Fluxo: proposal → specs → design → review → test-plan → tasks → apply → verify. O review é escrito por um revisor de contexto novo e somente leitura (um segundo modelo quando disponível) e emite uma linha VERDICT: instruindo o agente a bloquear test-plan, tasks e apply; o OpenSpec apenas verifica que os artefatos existem, então imponha o bloqueio com seu próprio CI ou hook. O test-plan mapeia cada cenário de especificação para um teste nomeado e serve como um livro-caixa red/green que o verify audita.

Deseja contribuir com um esquema da comunidade? Abra uma issue com um link para seu repositório, ou envie um PR adicionando uma linha a esta tabela.

---

Veja Também

• Referência CLI: Comandos de Esquema - Documentação completa de comandos