Configurar seu projeto

Adicione o OpenSpec a um projeto: execute init, veja o que foi criado e ajuste.

Escolha onde o OpenSpec reside

• No seu repositório (padrão): especificações e alterações ficam ao lado do código que descrevem e são versionadas com ele. O restante desta página segue esse caminho.
• Em um armazenamento (store): um repositório de planejamento separado, compartilhado pelos repositórios que o utilizam, para configurações multi-repo ou para manter o planejamento totalmente fora do repositório. Stores (beta) aborda quando isso vale a pena e como configurar um.

Inicializar seu projeto

Com a CLI instalada (Instalação), execute init na raiz do seu projeto. No terminal:

cd <seu-projeto>
openspec init

Init pergunta quais ferramentas de IA você utiliza, grava os arquivos de fluxo de trabalho para as que você escolher e informa o que foi gerado:

OpenSpec Setup Complete

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

Reinicie sua IDE para que os novos comandos tenham efeito.

Executar init novamente é seguro:

• Ferramentas já configuradas exibem Refreshed em vez de Created.
• Executar init novamente com uma nova ferramenta selecionada adiciona essa ferramenta.
• A flag --tools ignora o seletor (Referência da CLI).

Migrar um project.md existente

Init não copia o arquivo legado openspec/project.md para config.yaml. Ele mantém o arquivo e exibe uma solicitação de migração assistida por IA.

No seu chat de IA:

Revise openspec/project.md e migre seu conteúdo útil para openspec/config.yaml.
Mantenha o contexto conciso: inclua apenas fatos do projeto necessários durante a criação de artefatos, apply e archive.
Mova orientações específicas de artefatos para rules nos artefatos correspondentes.
Mova orientações para apply ou archive para a entrada de operações correspondente.
Deixe de fora material genérico, desatualizado ou prolixo. Não exclua project.md.

Revise config.yaml e, quando estiver pronto, exclua project.md.

O que o init instala

Executar init cria duas coisas no seu projeto:

• Uma pasta openspec/ na raiz do repositório
• Arquivos de fluxo de trabalho (skills e comandos) adicionados à pasta da sua ferramenta de IA (.agents/, .claude/, etc.)

Faça commit de tudo como faz com o restante do código fonte. Init não altera mais nada no seu repositório (se encontrar resquícios de uma versão anterior do OpenSpec, pergunta antes de limpá-los).

A pasta openspec/

Todo artefato do OpenSpec reside aqui, na raiz do seu projeto. Veja como fica:

openspec/
├── config.yaml     configurações do projeto e contexto para a IA
├── specs/          suas especificações (vazio por enquanto)
└── changes/        alterações em andamento (vazio por enquanto)
    └── archive/    alterações concluídas são movidas para cá

Configuração do projeto aborda o config.yaml.

Os arquivos de fluxo de trabalho (skills e comandos)

Estes são os fluxos de trabalho do OpenSpec, as ações que você usará enquanto trabalha. Aqui estão como skills instalados, na pasta compartilhada .agents/ que a maioria das ferramentas usa:

.agents/skills/
├── openspec-explore/              pensar primeiro em uma ideia
├── openspec-propose/              propor uma alteração
├── openspec-apply-change/         implementar as tarefas de uma alteração
├── openspec-update-change/        revisar o plano de uma alteração
├── openspec-sync-specs/           sincronizar as atualizações de especificação de uma alteração para specs/
├── openspec-archive-change/       mover uma alteração finalizada para o arquivo
├── openspec-verify-change/        verificar se a implementação corresponde ao plano (não incluso por padrão)
└── openspec-bulk-archive-change/  arquivar várias alterações de uma vez (não incluso por padrão)

Este é o conjunto padrão mais dois fluxos de trabalho opcionais. Perfis lista todos os doze.

Por padrão, cada fluxo de trabalho é instalado de duas formas:

• Skill (openspec-apply-change): instruções que seu agente capta automaticamente quando você solicita o trabalho.
• Comando (/opsx:apply no Claude Code): um ponto de entrada digitado para o mesmo fluxo de trabalho, com um nome mais curto.

As duas formas são funcionalmente idênticas. O skill e o comando de um fluxo de trabalho carregam as mesmas instruções.

Por que duas: os comandos vieram primeiro, e cada ferramenta os escreve de um jeito. Skills são o padrão mais novo, compartilhado entre ferramentas, mas nem toda ferramenta consegue invocar um skill diretamente, então os comandos permanecem como o ponto de entrada para essas ferramentas.

Algumas ferramentas instalam apenas na forma de skill. Quando a ferramenta executa skills diretamente, init omite comandos e informa (Commands skipped for: codex (uses skills)).

Preferimos skills e esperamos descontinuar os comandos futuramente.

Alterar o que é instalado

O seletor interativo altera a forma de entrega e o conjunto de fluxos de trabalho (Perfis). No terminal:

openspec config profile

Exemplo de troca para apenas skills:

Current profile settings
  Delivery: both

? O que você deseja configurar? Delivery only
? Modo de entrega (como os fluxos de trabalho são instalados): Skills only

Alterações de configuração:
  delivery: both -> skills
? Aplicar alterações a este projeto agora? (S/n) s

Responder sim aplica ao projeto atual imediatamente. Outros projetos captarão a alteração no próximo openspec update. A configuração é global, por máquina.

Claude Code não mostra os fluxos de trabalho

O Claude Code carrega os fluxos de trabalho do OpenSpec a partir de um ou ambos os caminhos do projeto, com base na sua configuração de entrega:

• Skills: .claude/skills/openspec-*/SKILL.md
• Comandos: .claude/commands/opsx/<id>.md

Se os arquivos estiverem ausentes, atualize o projeto. No terminal:

openspec update

Se os arquivos de comando existirem, mas /opsx: não mostrar comandos do OpenSpec, atualize o Claude Code e reinicie-o. Se os comandos ainda não carregarem, habilite também os skills. No terminal:

openspec config set delivery both
openspec update

Reinicie o Claude Code e, em seguida, execute /openspec-propose no chat. Se apenas alguns fluxos de trabalho estiverem faltando, altere seu perfil.

A configuração está concluída. O Guia rápido conduz sua primeira alteração a partir daqui.