Tutorial de OpenSpec: uma mudança real, da instalação ao archive

O OpenSpec não deixa o seu agente mais inteligente. Ele leva a discussão sobre o que construir para um arquivo, antes de existir código para discutir.

O OpenSpec é uma camada de spec open source para agentes de IA para código, feita pela Fission AI sob licença MIT. Você instala uma CLI pequena em Node, roda openspec init, e o seu agente (Claude Code, Codex, Cursor, GitHub Copilot, OpenCode e mais de quarenta outros) ganha slash commands que transformam um pedido numa pasta de mudança: uma proposta, um delta dos requisitos, um design e uma lista de tasks. Você lê o plano, o agente constrói, e arquivar incorpora o delta às specs que descrevem como o seu sistema funciona hoje.

Eu rodo spec-driven development todo dia, com os meus próprios kits com gate: o claude-sdd-kit no Claude Code e o pi-sdd-kit no Pi. Não com OpenSpec. Então, para este guia, fiz a parte que a maioria dos tutoriais pula: instalei o OpenSpec 1.14.1 e passei uma mudança real por ele com o Claude Code, num repo pequeno de ledger. Propose, um review que mudou o plano, apply, archive, e uma sessão de explore depois. Todo arquivo, tempo e citação abaixo vem dessa execução.

Se você está escolhendo entre ferramentas em vez de aprender esta, coloquei o OpenSpec ao lado do Spec Kit, do Superpowers e do pi-sdd-kit em ferramentas de SDD comparadas.

Duas pastas e um delta: o modelo mental inteiro

O OpenSpec mantém duas pastas. openspec/specs/ descreve como o seu sistema se comporta hoje, uma pasta por capability. openspec/changes/<name>/ guarda uma mudança proposta: o porquê, o que muda nos requisitos, o como e os passos.

O truque é o delta. Dentro de uma mudança você não reescreve a spec. Escreve só o que se move, sob requisitos ADDED, MODIFIED, REMOVED ou RENAMED. Quando você arquiva, o delta é aplicado à spec principal e a pasta da mudança vai para changes/archive/ com uma data na frente. As specs nunca são escritas de antemão. Elas se acumulam, uma mudança arquivada por vez.

Pense na spec principal como o mapa oficial de uma cidade, e numa mudança como uma folha de papel vegetal por cima dele, com só a quadra que você está reconstruindo desenhada em vermelho. Arquivar passa o vermelho a tinta no mapa e guarda o papel vegetal numa gaveta com data. A analogia esconde um detalhe que importa mais adiante: dentro do /opsx:archive, quem passa a tinta é o agente, à mão, seguindo as instruções da skill. Só o openspec archive, rodado no terminal, faz o merge do delta em código.

Este é o meu repo de teste logo depois do primeiro /opsx:propose:

O repo do ledger depois de um /opsx:propose

• openspec/
  • config.yaml// schema: spec-driven, mais o seu contexto e as suas regras
  • specs/// vazia até o primeiro archive
  • changes/
    • add-idempotent-transfers/mudança
      • .openspec.yaml// schema e data de criação
      • proposal.md// porquê, o que muda, impacto
      • specs/ledger-transfers/spec.md// o delta: cinco requisitos ADDED
      • design.md// decisões, e as alternativas que rejeitou
      • tasks.md// tasks com checkbox, a maioria com testes próprios
    • archive/// mudanças concluídas, com data
• .claude/
  • skills/// seis skills openspec-*
  • commands/opsx/// propose, explore, apply, update, sync, archive

Depois que arquivei essa mudança, specs/ tinha uma capability, ledger-transfers, com cinco requisitos. Mais nada. É a quantidade certa. A spec cobre o que eu toquei, e a próxima mudança vai adicionar o que ela tocar.

Metade dos tutoriais de OpenSpec ensina comandos que não existem mais

As primeiras versões do OpenSpec, em setembro de 2025, rodavam com três comandos: /openspec:proposal, /openspec:apply e /openspec:archive. Muitos dos tutoriais que ainda ranqueiam foram escritos nessa época. Em 26 de janeiro de 2026, a versão 1.0 apagou os três.

A reescrita se chama OPSX. Os comandos antigos empurravam uma mudança por fases fixas. O OPSX dá ações ao agente, e a CLI acompanha quais artefatos existem e qual é o próximo pronto. Os arquivos do projeto também mudaram: o OpenSpec parou de gerar arquivos de instrução como openspec/project.md, AGENTS.md e CLAUDE.md. Agora o seu agente recebe skills, e o contexto do projeto foi para openspec/config.yaml.

Como o OpenSpec chegou à 1.14

1. 6 de set. de 20250.1.0

   Primeira release no npm. A linha inicial rodava três comandos presos a fases e guardava o contexto do projeto em openspec/project.md.

2. 26 de jan. de 20261.0: a release do OPSX

   Comandos antigos removidos. Skills substituem os arquivos de prompt espalhados, e a CLI monta cada instrução a partir de config, regras e templates.

3. 23 de fev. de 20261.2: /opsx:propose e perfis

   Um comando rascunha o plano inteiro. O perfil core vira a instalação padrão.

4. 28 de jun. de 20261.5: Stores, em beta

   Specs e mudanças num repositório de planejamento próprio, para trabalho que atravessa repositórios.

5. 10 de jul. de 20261.6: /opsx:update

   Revisa o plano de uma mudança já começada, em vez de editar quatro arquivos à mão.

6. 29 de jul. de 20261.7: Codex só com skills

   O Codex invoca $openspec-propose. Mudanças podem declarar skip_specs para trabalho sem mudança de comportamento.

7. 30 de set. de 20261.14: mais agentes, navegação no archive

   Warp, Grok Build e DeepSeek Harness entre os novos alvos. list --archived mostra as mudanças concluídas. A 1.14.1 veio em 5 de outubro.

Se um guia manda você fazer o que está à esquerda, faça o que está à direita.

Conselhos antigos de OpenSpec vs. OpenSpec 1.14

O workflow da direita está estável desde fevereiro. A lista de ferramentas cresce a cada poucas semanas.

Guias antigos dizem	Faça isto na 1.14
/openspec:proposal, :apply, :archive	/opsx:propose, /opsx:apply, /opsx:archive
Descreva o seu projeto em openspec/project.md	Coloque as restrições em context: no openspec/config.yaml
/opsx:new, depois /opsx:ff	/opsx:propose faz os dois. new e ff estão no perfil expandido
O OpenSpec edita o seu AGENTS.md ou CLAUDE.md	Ele escreve skills e comandos, e deixa esses arquivos em paz
/opsx:propose no Codex	$openspec-propose. O Codex só lê skills
Instale o MCP server do OpenSpec	Não existe. É uma CLI mais arquivos gerados

Instale, e depois viva no chat

O OpenSpec exige Node 20.19 ou mais recente.

Instalar o OpenSpec e inicializar um projeto

1. npm

   $ npm install -g @fission-ai/openspec@latest

2. Homebrew

   $ brew install openspec

3. Init, escolhendo os agentes

   $ openspec init

4. Init para Claude Code, sem perguntas

   $ openspec init --tools claude

5. Init para vários agentes

   $ openspec init --tools claude,codex,cursor

Isto é o que o openspec init --tools claude escreveu no meu repo: openspec/config.yaml, as pastas specs/ e changes/archive/ vazias, seis skills em .claude/skills/ e seis comandos em .claude/commands/opsx/. São 2.620 linhas de instrução para o agente. Ele não tocou numa linha do meu código, e não tocou no CLAUDE.md.

O OpenSpec coleta estatísticas de uso anônimas por padrão: nome do comando e versão, mais nada, e nunca em CI. export OPENSPEC_TELEMETRY=0 desliga.

Depois do setup, você divide o tempo entre dois lugares, e confundir os dois é o jeito mais comum de travar. O binário openspec roda no terminal. Os comandos /opsx: rodam no chat do agente, a mesma caixa onde você pede para ele escrever código.

$

Terminal: openspec …

1. 01openspec init: configura um projeto para os seus agentes
2. 02openspec update: atualiza os arquivos gerados depois de um upgrade ou de uma troca de perfil
3. 03openspec list, show, view: mostram mudanças e specs
4. 04openspec validate --strict: confere uma mudança antes de ela ir para produção
5. 05openspec config profile: escolhe quais comandos são instalados

/

Chat do agente: /opsx:…

1. 01/opsx:explore: pensa uma mudança com você, não escreve nada
2. 02/opsx:propose: rascunha o plano inteiro e para
3. 03/opsx:update: revisa uma mudança que você já começou
4. 04/opsx:apply: constrói, task por task
5. 05/opsx:archive: incorpora o delta e arquiva a mudança

O mesmo comando tem cinco grafias

/opsx:propose é o nome na documentação. O seu agente pode querer outra coisa, porque cada ferramenta carrega do seu jeito o arquivo que o OpenSpec escreveu. Uma pasta chamada opsx/ te dá os dois-pontos. Um arquivo chamado opsx-propose te dá o hífen. Ferramentas que só leem skills usam o nome da skill.

Como digitar /opsx:propose em cada agente

Da referência de ferramentas suportadas do OpenSpec para a 1.14. Os prompt files do Copilot funcionam nas extensões de IDE, não no Copilot CLI. O openspec init imprime a forma certa para as ferramentas que você escolheu, então leia a dica no fim do setup.

Agente	Você digita	Onde o OpenSpec escreve
Claude Code	/opsx:propose	.claude/commands/opsx/
Gemini CLI	/opsx:propose	.gemini/commands/opsx/
Cursor	/opsx-propose	.cursor/commands/
GitHub Copilot	/opsx-propose	.github/prompts/
OpenCode	/opsx-propose	.opencode/commands/
Pi	/opsx-propose	.pi/prompts/
Codex	$openspec-propose	.agents/skills/
Amazon Q Developer	@opsx-propose	.amazonq/prompts/
A maioria das ferramentas só de skills (Hermes, Zed)	/openspec-propose	a pasta de skills da ferramenta

Skills e comandos são dois formatos de entrega para os mesmos workflows, e a instalação padrão traz os dois. openspec config profile pode trocar a entrega para só skills ou só comandos. Um detalhe que gostei nas skills geradas: elas foram escritas para lidar com seleção automática. Se o seu agente escolhe uma skill do OpenSpec por conta própria num repo que nunca rodou openspec init, a skill manda ele deixar o OpenSpec de lado e responder normalmente, em vez de criar pastas pelas suas costas.

Uma mudança real, do começo ao fim

O repo de teste é um ledger em memória: transfer(from, to, cents), centavos inteiros, dois testes. O pedido é o bug que mais me importa desde que construí uma fintech cripto de 13 apps: um retry nunca pode movimentar dinheiro duas vezes. Pedi chaves de idempotência. Um retry com a mesma chave e o mesmo payload devolve o resultado original. A mesma chave com um payload diferente é rejeitada.

Uma mudança pelo OpenSpec com o Claude Code

Entrada

Um ledger de 24 linhas e um pedido: um retry nunca pode movimentar dinheiro duas vezes

↓

1. 01/opsx:propose (1 min 14 s)

   Criou a pasta da mudança com os quatro artefatos, rodou openspec validate --strict e parou. Nenhum código tocado. Terminou com as quatro escolhas que eu não tinha especificado, para eu conferir.

   ↓
2. 02Review (eu)

   Li a proposta e o delta. O plano era bom. Uma decisão estava errada para dinheiro: a chave era opcional.

   ↓
3. 03/opsx:update (32 s)

   Propôs edições nos quatro arquivos e esperou eu responder apply all antes de escrever qualquer coisa. Adicionou uma task para corrigir os testes antigos primeiro, para a suíte continuar verde.

   ↓
4. 04/opsx:apply (1 min 18 s)

   Passou por sete tasks em ordem, a maioria entregando os próprios testes, e marcou cada uma no tasks.md. Dez testes passam.

   ↓
5. 05/opsx:archive (19 s)

   Perguntou se devia sincronizar o delta com as specs principais antes. Eu disse que sim. Ele criou specs/ledger-transfers/spec.md e moveu a mudança para changes/archive/2026-10-13-add-idempotent-transfers/.

↓

Saída

Uma spec de como as transferências se comportam hoje, um registro datado do porquê e um diff que bate com os dois

O que a execução produziu

136

linhas de planoproposta, delta, design, tasks

84

linhas adicionadas17 no ledger, 67 em testes

10/10

testes passandodois antigos, oito novos

203 s

tempo de agentequatro comandos cronometrados; dois turnos de confirmação fora da conta

O delta é a parte que vale ler devagar. Este é um dos cinco requisitos, como ficou na spec principal depois do archive:

### Requirement: Reusing a key with a different payload is rejected

When a transfer is made with a key that a previous successful transfer used,
and the source, destination, or amount differs from that transfer's, the
system SHALL throw an error identifying the key conflict and SHALL NOT change
any balance.

#### Scenario: Same key, different amount

- **WHEN** a transfer of 2500 cents from `alice` to `bob` with key `k1` has
  succeeded, and a transfer of 3000 cents from `alice` to `bob` with key `k1`
  is made
- **THEN** the call throws an error matching `idempotency key reused` and
  `alice` still has 7500 cents and `bob` still has 2500 cents

Todo requisito é uma frase com SHALL e um cenário que um teste consegue conferir linha a linha. O próprio guia do OpenSpec pede um SHALL por requisito, e o agente colocou quatro no primeiro, o que vale um comentário de review. Ele também escreveu o cenário que eu teria que lembrar sozinho: um retry precisa dar certo mesmo quando uma transferência nova falharia agora por falta de saldo. Isso só funciona se a busca pela chave rodar antes da checagem de saldo, e o design dizia isso numa frase.

O plano era bom. Estava errado no único lugar que importava.

O agente deixou a chave opcional. O design dele deu um motivo: exigir a chave “breaks every existing caller for no gain in a demo ledger” (quebra todos os chamadores existentes sem ganho nenhum num ledger de demo). Justo, para uma demo. Mas o agente tinha decidido em silêncio que esse código continuaria sendo uma demo, e é exatamente esse tipo de chute que um plano expõe. No dia em que esse ledger movimentar dinheiro de verdade, uma chave de idempotência opcional significa que o único chamador que esquecer dela pode cobrar duas vezes, e nada reclama.

Respondi com uma frase: a chave é obrigatória, e uma transferência sem ela lança erro. O /opsx:update levou essa frase pelos quatro arquivos, 21 linhas entrando e 19 saindo, incluindo uma task nova para corrigir os testes antigos primeiro. Em código, a mesma correção é uma breaking change numa API de pagamento, entregue depois que todo mundo já chama do jeito antigo. Essa é a troca inteira que o OpenSpec oferece: a discordância acontece numa proposta de 29 linhas em vez de num pull request.

Leia a lista de escolhas no fim de todo propose antes de ler qualquer outra coisa. Na minha execução ela citou quatro: a chave opcional, transferências que falham não consumirem a chave, um replay devolver o resultado original mesmo depois de o saldo mudar, chaves que nunca expiram. Essa lista é o agente dizendo onde chutou.

Depois, torne o chute improvável da próxima vez. Voltei ao repo recém-inicializado, adicionei duas linhas ao openspec/config.yaml (uma delas: “Every operation that moves money takes an idempotency key. No exceptions.”) e rodei o mesmo /opsx:propose de novo. A chave voltou obrigatória, e o agente citou a config do projeto como motivo. Uma execução não é prova, e context: continua sendo texto num prompt, mas agora o chute precisa argumentar contra uma regra escrita. Uma regra que você pega duas vezes em review pertence ao context:.

A CLI é a máquina de estados. O agente é o digitador.

Leia as skills geradas e o design fica claro. O agente nunca decide sozinho o que vem depois. Ele pergunta à CLI. openspec new change cria a estrutura da pasta. openspec status --change <name> --json informa quais artefatos existem, qual está pronto e quais estão bloqueados. openspec instructions <artifact> --change <name> --json devolve tudo o que o agente precisa para escrever um arquivo:

O que o openspec instructions entrega ao agente para cada artefato

1. 1

   Contexto

   O campo context: do openspec/config.yaml, até 50 KB. Ele entra em todo pedido de planejamento.

   context: | Every operation that moves money takes an idempotency key.

   +
2. 2

   Regras

   Regras por artefato, do mesmo arquivo, aplicadas só àquele artefato.

   rules: { proposal: [State what is out of scope] }

   +
3. 3

   Template e instrução

   Do schema, spec-driven por padrão: a estrutura do arquivo e como preenchê-lo. O agente é instruído a nunca copiar o contexto ou as regras para dentro do artefato.

   +
4. 4

   Dependências

   Os artefatos já escritos em que este se apoia. O agente é instruído a relê-los do disco, mesmo que tenha visto há um minuto. É por isso que o design lê a proposta, as tasks leem as specs e o design, e os quatro arquivos concordam entre si.

Então o workflow mora numa CLI que você pode versionar, automatizar com script e rodar em CI, e o agente faz a escrita. É por isso que o OpenSpec funciona em mais de quarenta agentes sem quarenta implementações.

Isso também explica a linha da skill de propose gerada que mais importa para mim: status “is file-existence only” (só confere se o arquivo existe). Levei isso ao pé da letra e criei uma mudança com quatro arquivos vazios. O openspec status respondeu 4/4 artifacts complete. Os arquivos existem, então o plano está completo. Ninguém leu, porque não havia nada para ler.

O gate mora no prompt, não no disco

O OpenSpec para nos lugares certos. Na minha execução, o propose encerrou o próprio turno depois do plano, porque a skill diz que o pedido “authorizes planning only” (autoriza só o planejamento). O update me mostrou as edições e esperou. O archive perguntou antes de tocar nas specs principais. Numa sessão interativa, com um humano digitando, essas paradas funcionam.

Ainda assim, são instruções para um modelo. Nada em openspec/ registra que um humano aprovou o plano, e o teste dos arquivos vazios mostra quanto vale a checagem de progresso. A única coisa que pegou aqueles arquivos vazios foi o openspec validate --strict, que faz o parse do delta e falhou. Essa é a diferença que vale aprender: algumas garantias ficam a cargo do código, algumas de um prompt, e algumas de ninguém.

Quem segura cada garantia num workflow com OpenSpec

O OpenSpec é fluido de propósito: a documentação chama os artefatos de enablers, não de gates. Um agente em loop, ou você cansado às 23h, passa direto pela linha do meio.

Quem segura	O quê	Vale quando
Código	validate --strict: um delta que passa no parse, requisitos com menos de 500 caracteres desde a 1.14.1. openspec archive no terminal: faz o merge em código e recusa um delta que não consegue ler	Toda vez que você roda. Coloque o validate no CI
O prompt	O propose para depois do plano. Update e archive mostram a edição e esperam. context: orienta toda proposta	O modelo segue as instruções e um humano está lendo
Ninguém	Que alguém leu o plano. Que o apply espera por essa pessoa. Que as specs ainda batem com o código depois de edições à mão: o /opsx:verify reporta lacunas, nunca bloqueia	Só se você construir

É uma escolha de design, não um bug. Se você quer o gate segurado por código, coloque a aprovação no disco, onde uma checagem consegue ler: um arquivo de status por mudança, sem o qual um job de CI ou um hook se recusa a passar. Não dentro do .openspec.yaml: ali o OpenSpec ignora as chaves que não conhece, e o validate --strict aponta elas.

Foi em torno dessa lacuna que construí os meus kits. No Claude Code, o claude-sdd-kit registra a aprovação como um token num arquivo .status, e o agente implementador dele para quando não lê tasks:approved. Essa parada ainda é uma instrução. A diferença é que a aprovação vira um fato em disco, uma linha que um hook ou um job de CI consegue impor, em vez de uma impressão num chat. O pi-sdd-kit faz o mesmo no Pi. A página de comparação explica como empilhar o OpenSpec com outras ferramentas sem perder isso.

Explore primeiro. Ele realmente não escreve nada.

O /opsx:explore é um parceiro para pensar. Ele lê o seu código e as suas specs, apresenta opções e não escreve nada, a menos que você peça. Conferi: depois de uma sessão de 45 segundos sobre adicionar estornos ao ledger, o git status estava limpo.

A resposta foi o melhor resultado da execução inteira. O explore leu a mudança arquivada e achou um acoplamento que eu não tinha visto. O design listava a expiração de chaves como fora do escopo. O explore percebeu que, se os estornos acham uma transferência pela chave, o armazenamento de chaves vira em silêncio o log de transações, e expirar chaves apagaria esse histórico: a transferência nunca mais poderia ser estornada. Terminou com uma pergunta que decide o resto: só estornos integrais, ou reembolsos parciais também?

É o archive fazendo o trabalho dele. A sessão seguinte começou da decisão em vez de começar do zero, que é o que um histórico de chat nunca vai te dar. Use o explore quando a mudança está nebulosa. Vá direto para o propose quando não está.

O core te dá seis comandos. Ligue o verify.

Um perfil decide quais slash commands o openspec init instala. O padrão, core, tem seis. O conjunto expandido adiciona mais seis para um controle mais fino.

Slash commands do OpenSpec na 1.14

O propose é new mais ff num passo só. Use o par expandido só quando quiser aprovar um artefato de cada vez.

Comando	Perfil	O que faz
/opsx:explore	core	Pensa uma mudança com você. Lê código, não escreve nada
/opsx:propose	core	Cria a mudança e rascunha todos os artefatos de planejamento, depois para
/opsx:apply	core	Percorre o tasks.md em ordem e marca as tasks concluídas
/opsx:update	core	Revisa os artefatos de uma mudança, mostra as edições, espera o seu OK
/opsx:sync	core	Incorpora o delta de uma mudança às specs principais sem arquivar
/opsx:archive	core	Oferece o sync, depois move a mudança para changes/archive/
/opsx:new	expanded	Cria a estrutura de uma mudança vazia
/opsx:continue	expanded	Escreve o próximo artefato pronto, um por vez
/opsx:ff	expanded	Escreve todos os artefatos de planejamento de uma vez
/opsx:verify	expanded	Confere o código contra a mudança: completude, correção, coerência
/opsx:bulk-archive	expanded	Arquiva várias mudanças concluídas, com detecção de conflito
/opsx:onboard	expanded	Guia você numa primeira mudança na sua própria codebase

O core não tem o único passo que eu não pularia: /opsx:verify, o review depois do código. Ele lê a mudança, procura no código evidências de cada requisito e reporta o que não bate, classificado como critical, warning ou suggestion. Nunca bloqueia o archive. Só torna a lacuna visível, que é a maior parte da briga.

Ligar os comandos expandidos

1. Escolher os workflows

   $ openspec config profile

2. Aplicar neste projeto

   $ openspec update

A CLI tem a sua própria lista curta que vale conhecer:

Comandos da CLI do OpenSpec que você vai rodar de verdade

Comando	Para que serve
openspec init --tools <ids>	Configurar um projeto para um ou mais agentes
openspec update	Atualizar os arquivos gerados depois de um upgrade ou de uma troca de perfil
openspec list	Mudanças ativas com o progresso das tasks. --specs e --archived também
openspec show <change>	Imprimir uma mudança ou uma spec
openspec status --change <name>	Quais artefatos existem e o que vem depois
openspec validate <change> --strict	Conferir o formato do delta. Coloque no CI
openspec view	Dashboard interativo de mudanças e specs
openspec archive <change>	Arquivar pelo terminal em vez do chat
openspec schema fork spec-driven <name>	Começar um workflow customizado para a sua equipe

O config.yaml é onde você para de se repetir

O openspec/config.yaml substituiu o project.md, e faz um trabalho só: guardar as restrições que o agente não consegue inferir lendo o seu código. O próprio arquivo gerado diz isso nos comentários. A sua stack e a estrutura de pastas o agente descobre sozinho, então deixe de fora. As suas regras sobre dinheiro, não.

schema: spec-driven

context: |
  Money is integer cents. No floats in any money path.
  Every operation that moves money takes an idempotency key. No exceptions.

rules:
  proposal:
    - State what is out of scope
  specs:
    - Every requirement gets a scenario for its failure path
  tasks:
    - Each task lands its own tests

O bloco context: entrou no meu segundo propose e mudou a decisão dele. O bloco rules: funciona por artefato, então uma regra para tasks nunca polui a proposta. Para escrever specs em outro idioma, rode openspec init --language <language> num projeto novo, ou adicione a instrução ao context:.

Numa codebase existente, deixe as specs crescerem a partir do trabalho

O OpenSpec foi feito primeiro para brownfield, e dá para ver. Você não documenta um app de 80.000 linhas antes da primeira mudança. Você propõe a mudança que ia fazer esta semana, e o delta documenta a fatia que ela toca. O meu ledger saiu de nenhuma spec para uma capability com cinco requisitos, nascida de uma mudança que eu precisava fazer de qualquer jeito.

Resista à tentação de documentar o passado. Specs escritas para código que ninguém está mudando ficam velhas, porque nada as obriga a acompanhar a realidade. Se você já tem um PRD, cole a seção relevante no explore e deixe virar um delta. Um openspec/ na raiz cobre um monorepo. Para trabalho que atravessa repositórios de verdade existem os Stores, ainda em beta.

O custo honesto: mais plano que diff

Eu peso toda ferramenta de spec numa balança de dois pratos. Num, as linhas que um revisor precisa ler. No outro, quanto custaria o erro que ele consegue pegar. A minha execução colocou 136 linhas de plano contra 84 linhas de diff, e 67 dessas 84 são testes: o código de produção mexeu 17 linhas. Só pela contagem de linhas, essa mudança foi especificada demais.

O outro prato decidiu. O review pegou uma chave de idempotência opcional num caminho de dinheiro, e esse erro custa mais que qualquer quantidade de Markdown. O OpenSpec se paga quando uma decisão errada sai cara, e te custa quando não sai.

→

Use o OpenSpec quando

1. 01Uma decisão errada custa mais que ler um plano: dinheiro, auth, dados que você não recupera
2. 02A mudança atravessa mais de uma sessão, então o plano precisa sobreviver ao chat
3. 03Outra pessoa revisa ou herda o trabalho
4. 04Você quer que o motivo de um comportamento ainda esteja no repo daqui a seis meses

×

Pule quando

1. 01Um erro de digitação, um bump de versão, um timeout de uma linha
2. 02Uma refatoração sem mudança de comportamento. Ou declare skip_specs: true na mudança
3. 03Você está fazendo um spike para aprender, não para manter
4. 04O plano ficaria mais longo que o diff e nada nele tem risco

A reclamação é real. Na thread do Hacker News sobre o site novo do OpenSpec, em setembro, devs cujas empresas adotaram a ferramenta descreveram exatamente isso: toda mudança, média ou maior, vira vários documentos que ninguém escreveu à mão, cada um precisando de review. Outros disseram que as specs guardadas se afastam do código, e que o valor está no processo de mudança, e não no archive. A mesma thread tem gente chamando de a dose mais sensata de cerimônia que já testou. Os dois lados têm razão em alguma coisa. Mantenha as propostas curtas com uma linha em rules:, revise a proposta e o delta em vez dos quatro arquivos, e rode o /opsx:verify antes de arquivar, para que as specs que você guarda sejam as que foram para produção.

OpenSpec ao lado de Spec Kit, Superpowers e plan mode

A comparação que mais me pedem está em ferramentas de SDD comparadas. A versão curta:

Onde o plano mora, por ferramenta

OpenSpec e Superpowers fazem trabalhos diferentes e se empilham bem. OpenSpec e Spec Kit fazem a mesma aposta com pesos diferentes.

Ferramenta	Onde o plano mora	Peso por mudança	Escolha quando
OpenSpec	Uma pasta de mudança, incorporada às specs no archive	Quatro arquivos, fluido	Você quer specs que acompanham o sistema, em qualquer agente
Spec Kit	Uma pasta de feature em specs/, mais uma constitution	Até nove etapas, sete arquivos por padrão	Toda feature precisa responder aos mesmos princípios
Superpowers	Um design doc e um plano para a feature em andamento	Uma metodologia inteira: TDD, subagents, review	O seu problema é execução, não intenção
Plan mode do Claude Code	A sessão, fora do seu repo	Nenhum	A tarefa cabe numa sessão e ninguém revisa o plano

O plan mode merece mais uma linha, porque ninguém responde isso bem. O plan mode planeja uma sessão. O OpenSpec planeja uma mudança e guarda ela no repo, onde a próxima sessão lê, do jeito que a minha sessão de explore leu o design arquivado. Se a decisão precisa sobreviver ao chat, o plan mode não é o lugar dela. Para a ponta mais pesada, escrevi um guia completo do Spec Kit.

Numa equipe, a spec é revisada no pull request

Faça commit do openspec/. O archive vira o histórico de por que o seu sistema funciona do jeito que funciona, e a pasta da mudança vai no mesmo pull request que o código. Os revisores leem a proposta e o delta primeiro. Se a intenção está errada, eles param antes do diff.

É o momento em que uma spec deixa de ser hábito de um dev e vira o contrato da equipe, o que é um problema à parte, com modos de falha próprios. Escrevi sobre isso em spec-driven development em time. E quando toda mudança passa por uma spec revisada, você está a um passo dos gates de aprovação do AI-DLC, onde o review vira o processo.

Quando o slash command não faz nada

Sete checagens, na ordem que resolve mais rápido

• ✓Obrigatório:
  Você digitou no chat do agente, não no terminal
• ✓Obrigatório:
  Você usou a grafia do seu agenteCursor e OpenCode querem /opsx-propose. Codex quer $openspec-propose. Veja a tabela acima.
• ✓Obrigatório:
  Os arquivos existem para aquele agenteO openspec init configura um agente novo. O openspec update só atualiza arquivos que já estão lá.
• ✓Obrigatório:
  Você reiniciou o agente se ele estava aberto durante o init
• ✓Obrigatório:
  Você rodou openspec update em cada projeto depois de atualizar o pacote
• •Opcional:
  O comando está no seu perfilverify, new, ff e onboard só existem no perfil expandido.
• •Opcional:
  O Node é 20.19 ou mais recenteConfira com node --version e openspec --version.

FAQ

O que é o OpenSpec?+

O OpenSpec é um framework de spec open source para agentes de IA para código, publicado pela Fission AI sob licença MIT. Ele adiciona ao seu repo uma camada fina de arquivos Markdown: specs que descrevem como o seu sistema se comporta, e uma pasta por mudança proposta, com uma proposta, um delta dos requisitos, um design e tasks.

Você instala a CLI openspec, roda openspec init e conduz tudo pelo chat do agente com comandos como /opsx:propose, /opsx:apply e /opsx:archive. Funciona com Claude Code, Codex, Cursor, GitHub Copilot, OpenCode, Gemini CLI e mais de quarenta outros agentes.

O OpenSpec é gratuito?+

Sim. A CLI é open source sob licença MIT, instalada pelo npm ou pelo Homebrew. O seu agente faz a escrita com o modelo e o plano que você já paga.

O OpenSpec é um MCP server? Precisa de API key?+

Não e não. O OpenSpec é uma CLI mais os arquivos que ela gera para o seu agente: skills e slash commands. A CLI nunca chama um modelo. O seu agente lê as instruções, escreve os artefatos e pergunta o estado à CLI.

Como instalar o OpenSpec?+

Você precisa de Node 20.19 ou mais recente. Rode npm install -g @fission-ai/openspec@latest, ou brew install openspec. Depois, dentro do projeto, rode openspec init e escolha os seus agentes, ou openspec init --tools claude para pular as perguntas.

Para fazer upgrade depois, atualize o pacote e rode openspec update em cada projeto, para que as skills e os comandos gerados batam com a versão nova.

Como usar o OpenSpec com Claude Code?+

Rode openspec init --tools claude. Ele escreve seis skills em .claude/skills e seis comandos em .claude/commands/opsx. No Claude Code, digite /opsx:propose seguido do que você quer, leia o plano, depois rode /opsx:apply e /opsx:archive.

Por que o /opsx:propose não funciona no Codex ou no OpenCode?+

Cada agente escreve o comando do seu jeito. O Codex só lê skills, então você digita $openspec-propose. OpenCode, Cursor, GitHub Copilot e Pi leem arquivos de comando chamados opsx-propose, então você digita /opsx-propose. O openspec init imprime a forma certa para os agentes que você escolheu.

Qual a diferença entre /opsx:propose e /opsx:new?+

O /opsx:propose cria a mudança e rascunha todos os artefatos de planejamento num passo só. O /opsx:new, no perfil expandido, só cria a estrutura de uma mudança vazia, e você cria os artefatos um por vez com /opsx:continue ou todos de uma vez com /opsx:ff. Use o propose, a menos que queira aprovar cada artefato separadamente.

Preciso rodar o /opsx:sync?+

Normalmente não. O /opsx:archive oferece sincronizar o delta da mudança com as specs principais antes de arquivar. Rode o sync sozinho só quando quiser as specs atualizadas antes de a mudança terminar, por exemplo numa mudança longa.

Devo fazer commit da pasta openspec no git?+

Sim. As specs, as mudanças ativas e o archive fazem parte do histórico do projeto. O archive é o registro de por que cada comportamento existe, e uma pasta de mudança pertence ao mesmo pull request que o código que ela descreve.

Como desinstalar o OpenSpec?+

Não existe comando de desinstalação. Remova o pacote com npm uninstall -g @fission-ai/openspec, depois apague o diretório openspec e os arquivos gerados para os seus agentes, como .claude/skills/openspec-* e .claude/commands/opsx, se não quiser mais.

OpenSpec vs Spec Kit: qual usar?+

Os dois mantêm a spec como fonte da verdade. O OpenSpec é mais leve e fluido: quatro arquivos por mudança, sem fases fixas, feito para codebases existentes. O Spec Kit é mais pesado e estruturado: uma constitution a que toda feature responde, até nove etapas e um passo de converge que confere o código contra os artefatos. Mudanças pequenas e frequentes ficam mais perto do OpenSpec. Uma equipe que precisa que toda feature siga os mesmos princípios fica mais perto do Spec Kit.

OpenSpec vs plan mode do Claude Code?+

O plan mode planeja uma sessão. O OpenSpec planeja uma mudança e guarda ela no seu repo, onde um revisor lê num pull request e a próxima sessão constrói em cima. Use o plan mode para uma tarefa que cabe numa sentada. Use o OpenSpec quando a decisão precisa sobreviver à conversa.