OpenSpec: Guia Inicial, Instalação, Fluxo de Trabalho e Erros Comuns

Especificações como diferenças, não como um PRD de 40 páginas.

Conteúdo da página

OpenSpec é uma CLI gratuita e de código aberto da Fission AI que faz com que você e seu agente de codificação concordem sobre uma mudança em Markdown puro antes que qualquer código seja escrito, sem a cerimônia de fases de frameworks mais pesados de desenvolvimento orientado por especificação.

A maioria das equipes que tenta o Desenvolvimento Orientado por Especificação (SDD) trava no mesmo dilema: o processo suficiente para impedir que um agente adivinhe, sem tanta estrutura que uma correção de bug de cinquenta linhas exija um documento de proposta. A resposta do OpenSpec é pular completamente o instinto de “documentar todo o sistema primeiro” e escrever especificações apenas para o que a mudança realmente afeta, usando deltas ADDED, MODIFIED e REMOVED em vez de uma reescrita completa a cada vez.

Fluxo de trabalho de desenvolvimento orientado por especificação do OpenSpec com um assistente de codificação de IA

Esse design centrado em mudanças também é a razão pela qual o OpenSpec continua surgindo ao lado do GitHub Spec Kit, Kiro e Superpowers na comparação de categorias de ferramentas SDD – ele costuma ser a escolha quando uma equipe quer especificações revisáveis sem uma fase de planejamento de 800 linhas. Este guia cobre a instalação da CLI, o fluxo de trabalho de quatro comandos que você realmente usa no dia a dia, como uma mudança se parece no disco e as perguntas e reclamações que aparecem com mais frequência no Reddit e no próprio rastreador de problemas do OpenSpec.

O que é o OpenSpec?

O OpenSpec descreve sua própria filosofia em quatro linhas: fluido e não rígido, iterativo e não waterfall, fácil e não complexo, feito para brownfield e não apenas para greenfield. Na prática, isso significa que não há fases bloqueadas – você pode editar uma proposta, uma especificação ou uma lista de tarefas a qualquer ponto em uma mudança, em vez de ser forçado a seguir especificar-então-planejar-então-implementar em ordem estrita, da forma como o fluxo de trabalho SDD neutro para ferramentas descreve.

Uma mudança no OpenSpec produz até quatro artefatos Markdown em sua própria pasta:

Artefato Propósito
proposal.md Por que a mudança existe e o que ela altera, em linguagem simples
specs/ Requisitos e cenários delta – a especificação testável para esta mudança
design.md Abordagem técnica opcional, para mudanças que necessitam de uma
tasks.md A lista de verificação de implementação com a qual o agente trabalha

Quando uma mudança é implementada e arquivada, suas especificações delta são mescladas em openspec/specs/, que se torna a descrição durável e do estado atual do seu sistema – a mesma ideia de “especificação como fonte de verdade” coberta em O que é Desenvolvimento Orientado por Especificação?, apenas escopada uma mudança por vez em vez de tudo escrito de uma vez.

Instalando o OpenSpec

O OpenSpec é uma CLI de Node.js, portanto você precisa do Node 20.19.0 ou mais novo em sua máquina.

node --version

Instale a CLI globalmente com o npm, então verifique se ela está em seu PATH:

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

Deno, pnpm, yarn, bun e nix também são caminhos de instalação suportados, caso se ajuste melhor à sua configuração do que o npm. Uma vez instalado, inicialize-o dentro de um projeto:

cd your-project
openspec init

openspec init pergunta quais ferramentas de IA você usa e escreve os arquivos de habilidade e comando correspondentes – o OpenSpec suporta mais de 30 assistentes, incluindo Claude Code, Cursor, GitHub Copilot, Gemini CLI, Codex, Kiro e OpenCode. Para CI ou configuração por script, pule o seletor completamente:

openspec init --tools claude,cursor   # configura ferramentas específicas
openspec init --tools all             # todas as ferramentas suportadas
openspec init --tools none            # apenas a estrutura openspec/, sem arquivos de ferramentas

Reinicie sua IDE depois para que ela carregue as habilidades e comandos recém-escritos. Se você prefere que seu assistente faça toda a instalação por você, o OpenSpec fornece um prompt de configuração que você pode colar no Claude Code ou em outro agente, que executa a instalação, roda openspec init e relata o que configurou.

O Fluxo de Trabalho Central: Explorar, Propor, Aplicar, Arquivar

Esta é a única coisa que pega quase todo mundo no primeiro dia: os comandos openspec rodam no seu terminal, mas os comandos /opsx: rodam na janela de chat do seu assistente de IA. Não há um “modo interativo” separado para entrar – digitar o comando com barra no chat é como você começa.

flowchart LR A["/opsx:explore (opcional)"] --> B["/opsx:propose change-name"] B --> C["/opsx:apply"] C --> D["/opsx:archive"] D -->|specs merged| E["openspec/specs/"]
  • /opsx:explore é um parceiro de pensamento sem riscos. Ele lê a parte relevante da sua base de código, expõe as opções e molda um plano antes que qualquer coisa seja escrita no disco – vale a pena formar isso como um hábito especificamente porque impede um agente ansioso de construir com confiança a coisa errada.
  • /opsx:propose <name> cria openspec/changes/<name>/ e rascunha a proposta, especificações delta, design opcional e lista de tarefas em uma etapa. Você revisa o plano aqui, antes que a implementação comece.
  • /opsx:apply trabalha pela lista de tarefas, marcando os itens conforme avança. Como o progresso fica em arquivos e não apenas no histórico do chat, você pode limpar sua janela de contexto ou começar uma sessão nova e retomar exatamente de onde o /opsx:apply parou.
  • /opsx:archive arquiva a mudança concluída em openspec/changes/archive/YYYY-MM-DD-<name>/ e mescla suas especificações delta na árvore canônica openspec/specs/.

O perfil padrão core instala exatamente esses quatro comandos mais update e sync. Um perfil expandido adiciona new, continue, ff, verify, bulk-archive e onboard para equipes que querem criar um artefato por vez em vez de todos de uma vez – mude para ele com openspec config profile seguido por openspec update.

Cada ferramenta escreve o mesmo comando de forma diferente dependendo de como ela carrega instruções personalizadas: /opsx:propose no Claude Code, /opsx-propose no Cursor e GitHub Copilot, @opsx-propose no Amazon Q, ou $openspec-propose no Codex. openspec init imprime a forma exata para as ferramentas que você escolheu, então a correção mais rápida para “nada aconteceu quando digitei o comando” é geralmente reler aquela dica impressa em vez de adivinhar.

Como uma mudança se parece no disco

Uma pasta de mudança sob openspec/changes/add-dark-mode/ tipicamente contém uma proposta, uma especificação delta e uma lista de tarefas como esta:

## ADDED Requirements

### Requirement: Theme selection
The app SHALL let users switch between light and dark themes,
defaulting to the system preference.

#### Scenario: User toggles dark mode
- **WHEN** the user clicks the theme toggle
- **THEN** the app switches to dark mode and persists the choice

Esse formato de delta ADDED/MODIFIED/REMOVED é o mecanismo que permite ao OpenSpec evitar reescrever um arquivo de especificação inteiro para uma mudança de um único campo. É também a razão pela qual o OpenSpec é explicitamente “brownfield-first” em vez de “greenfield-first”: você nunca documenta sua aplicação inteira antes de obter valor, você apenas documenta a fatia que cada mudança real afeta, e openspec/specs/ se preenche naturalmente ao longo de meses de trabalho normal.

Comandos CLI úteis para verificar esse estado sem sair do terminal:

openspec list                 # mudanças ativas
openspec show add-dark-mode   # exibe os artefatos de uma mudança
openspec validate --all       # verifica a formatação de especificação em todo o projeto
openspec view                 # dashboard interativo

Commit a pasta inteira openspec/ no git. As mudanças ativas e o arquivo são destinados a se tornarem um registro durável e versionado do que seu sistema faz e por que mudou – não um bloco de notas que você apaga após mesclar.

Adotando o OpenSpec em uma Base de Código Existente

A preocupação mais comum de equipes avaliando o OpenSpec em um projeto real é alguma versão de “minha aplicação tem 80.000 linhas, eu tenho que especificar tudo primeiro?” Você não precisa. O próprio guia do OpenSpec é direto sobre isso: escolha algo pequeno e real que você já ia construir esta semana, rode /opsx:explore na área que você está prestes a tocar para que o agente mapeie como as coisas realmente funcionam primeiro, então /opsx:propose uma mudança escopada apenas para essa fatia.

Se você já tem PRDs, documentos SRS ou docs de design parados no Notion ou Confluence, trate-os como material de fonte para exploração em vez de algo para converter em massa para especificações. Cole a seção relevante em uma sessão de /opsx:explore e deixe o agente moldar uma delta focada a partir dela; uma conversão mecânica única de um PRD de quarenta páginas tende a produzir uma especificação que ninguém confia seis meses depois. Para equipes que querem uma primeira execução guiada e narrada em vez de pular direto para uma mudança real, o comando expandido /opsx:onboard escaneia sua base de código por uma pequena melhoria segura e percorre o loop completo nela.

Perguntas e Problemas Comuns

Estes são os problemas que aparecem repetidamente no Discord do OpenSpec, issues do GitHub e threads no Reddit em subreddits como r/cursor, r/RooCode e r/opencodeCLI.

“Digitei o comando com barra e nada aconteceu.” Quase sempre é um destes: você digitou no terminal em vez do chat do seu assistente, sua IDE não reiniciou desde que openspec init rodou, ou a versão da CLI é antiga o suficiente para que openspec update reporte tudo atualizado sem nunca escrever os arquivos de fluxo de trabalho mais novos. Rode openspec update, reinicie a IDE e confirme que as pastas de habilidades existem (.claude/skills/openspec-* para Claude Code, ou o equivalente da sua ferramenta da lista de ferramentas suportadas).

“A IA gera muito mais especificação do que eu preciso.” Esta é a reclamação mais citada em artigos mais longos: um agente pode transformar uma funcionalidade de trinta minutos em uma especificação de 800 linhas. O OpenSpec limita o campo context: injetado em cada requisição a 50KB especificamente para forçar disciplina, mas as especificações delta em si não têm limite rígido, então cortar as especificações geradas para o que é realmente estruturante é um hábito que você tem que manter sozinho, não algo que a ferramenta impõe por você.

“Duas mudanças tocaram o mesmo requisito e uma silenciosamente descartou o cenário da outra.” Este é um caso de borda real e documentado: o arquivamento aplica uma delta MODIFIED como uma substituição de bloco inteiro chaveada pelo nome do requisito, então se duas mudanças em andamento modificam o mesmo requisito, arquivar a segunda costumava sobrescrever os cenários da primeira sem aviso. Versões atuais adicionam uma verificação de drift que aborta o arquivamento e informa que você deve atualizar a especificação da mudança primeiro – mas ainda vale a pena saber que o modo de falha existe se você executar várias mudanças na mesma área em paralelo.

“Qual modelo de IA eu deveria realmente usar com ele?” Os próprios docs do OpenSpec recomendam modelos de alto raciocínio para ambos planejamento e implementação – modelos de classe Opus e de classe Codex são citados especificamente – e limpar sua janela de contexto antes da implementação, já que um contexto limpo produz resultados mensuravelmente melhores do que uma sessão longa e acumulada.

“Como isso é diferente de Spec Kit, Kiro, Superpowers ou BMAD?” Esta é a pergunta de Reddit mais frequente e a resposta honesta é “peso de processo.” O próprio README do OpenSpec enquadra a comparação diretamente: Spec Kit é minucioso mas mais pesado, com mais Markdown e portões de fase rígidos; Kiro é poderoso mas te prende à IDE da AWS e modelos Claude; OpenSpec troca parte dessa estrutura preliminar pela capacidade de iterar livremente e trabalhar com qualquer assistente que você já tenha aberto. Para a análise completa contra Spec Kit, Kiro, habilidades Claude Code, BMAD-METHOD e Superpowers, veja a comparação de ferramentas SDD dedicada.

“A IA realmente segue a especificação que acabou de escrever?” Nem sempre, e este é um problema documentado em ferramentas SDD em geral, não único do OpenSpec – uma grande janela de contexto não significa que o agente atenda igualmente a cada parte dela. O comando /opsx:verify existe especificamente para capturar código gerado que contradiz sua própria especificação, e vale a pena executá-lo em qualquer coisa não trivial em vez de confiar cegamente na implementação.

“Eu preciso disso para uma correção de uma linha?” Não. A própria FAQ do OpenSpec diz isso: use-o onde o acordo importa, que é a maioria do trabalho não trivial de múltiplos arquivos, e pule-o para uma correção de erro ortográfico ou um protótipo descartável que você vai apagar em uma semana.

“Como eu faço para impedir um agente de repropor algo que já rejeitamos?” /opsx:archive não tem um status dedicado para uma mudança rejeitada, então nada informa uma proposta futura que uma ideia já foi investigada e recusada. Veja Propostas Rejeitadas no OpenSpec: Uma Convenção de Memória de Decisão para o padrão decision.md e a regra de configuração que faz um agente procurar o arquivo antes de propor novamente.

Quando o OpenSpec Cabe e Quando Não Cabe

Bom encaixe:

  • Bases de código brownfield onde você quer especificações revisáveis sem documentar todo o sistema antecipadamente.
  • Desenvolvedores solitários e pequenas equipes que querem uma cerimônia mais leve do que o Spec Kit, mas ainda querem um plano escrito antes do código.
  • Trabalho que abrange vários arquivos, uma mudança de esquema ou qualquer coisa que um engenheiro júnior razoavelmente gostaria de ter uma doc de design curta.
  • Equipes já comprometidas a revisar planos em pull requests – especificações delta diferenciam limpo já que descrevem apenas o que mudou.

Encaixe mais fraco:

  • Correções de bug de uma linha e protótipos descartáveis, onde o passo de revisão da proposta custa mais do que salva.
  • Equipes que precisam da estrutura mais pesada e prescritiva do Spec Kit ou de uma experiência nativa da AWS, integrada à IDE como o Kiro – veja a estrutura de decisão na comparação de ferramentas para onde cada ferramenta vence.
  • Funcionalidades entre repositórios hoje, a menos que você esteja disposto a tentar o recurso beta stores do OpenSpec, que move o planejamento para seu próprio repositório compartilhado para que múltiplas bases de código e agentes possam ler o mesmo plano.
  • Qualquer pessoa ainda decidindo se uma funcionalidade específica merece uma especificação – leia Desenvolvimento Orientado por Especificação vs Vibe Coding primeiro, já que o OpenSpec apenas ajuda quando você já decidiu que a estrutura vale o sobrecusto.

Conclusão

A aposta do OpenSpec é que a maior parte da dor do Desenvolvimento Orientado por Especificação vem da cerimônia, não da ideia subjacente de concordar com um plano antes que o código exista. Deltas em vez de reescritas completas, sem fases bloqueadas e um fluxo de trabalho brownfield-first o tornam notavelmente mais leve de adotar em uma base de código que você não construiu do zero. Os trade-offs são reais também – o inchaço de especificação é um risco genuíno sem disciplina, o tratamento de conflito em torno de mudanças simultâneas a um único requisito ainda está maturando, e o ecossistema é mais jovem que as próprias ferramentas do GitHub. Instale-o em um projeto real, execute uma pequena mudança de explorar-propor-aplicar-arquivar de ponta a ponta, e decida dali se a cerimônia mais leve justifica seu custo contra sua carga de trabalho real.

Subscrever

Receba novos artigos sobre sistemas, infraestrutura e engenharia de IA.