Início Rápido do OpenSpec: Instalação, Fluxo de Trabalho e Armadilhas Comuns

Specs como deltas, 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 permite a você e ao seu agente de codificação concordarem com uma alteração em Markdown simples antes que qualquer código seja escrito, sem a cerimônia faseada das estruturas mais pesadas orientadas por especificação.

A maioria das equipes que tenta o Desenvolvimento Orientado por Especificação (Spec-Driven Development) trava na mesma compensação: processo suficiente para impedir que o agente chute, sem tanta estrutura de apoio que uma correção de bug de cinquenta linhas precise de um documento de proposta. A resposta do OpenSpec é pular completamente o instinto de “documentar o sistema inteiro primeiro” e escrever especificações apenas para o que a alteração realmente toca, usando deltas ADDED, MODIFIED e REMOVED em vez de uma reescrita completa toda vez.

OpenSpec spec-driven development workflow with an AI coding assistant

Esse design centrado na alteração é também o motivo pelo qual o OpenSpec continua aparecendo ao lado do GitHub Spec Kit, Kiro e Superpowers na comparação de categorias de ferramentas SDD – geralmente é 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 alteração se parece no disco e as perguntas e reclamações que aparecem mais frequentemente 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 em cascata, 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 de uma alteração, em vez de ser forçado a seguir especificar-então-planejar-então-implantar em ordem estrita da forma como o fluxo de trabalho SDD neutro em relação a ferramentas descreve.

Uma alteração no OpenSpec produz até quatro artefatos em Markdown em sua própria pasta:

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

Uma vez que uma alteração é implementada e arquivada, suas especificações de delta são mescladas em openspec/specs/, que se torna a descrição duradoura do estado atual do seu sistema – a mesma ideia de “especificação como fonte da verdade” coberta em O que é Desenvolvimento Orientado por Especificação?, apenas com escopo para uma alteração por vez em vez de escrita de uma vez só.

Instalando o OpenSpec

O OpenSpec é uma CLI de Node.js, então você precisa do Node 20.19.0 ou mais novo na sua máquina.

node --version

Instale a CLI globalmente com 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 são também caminhos de instalação suportados, se isso se adequar melhor ao seu ambiente do que 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 skill 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 scriptada, pule o seletor completamente:

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

Reinicie seu IDE depois para que ele perceba os skills e comandos recém-escritos. Se você preferir que seu assistente faça toda a instalação para você, o OpenSpec envia 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 de surpresa 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ê inicia.

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 raciocínio sem riscos. Ele lê a parte relevante da sua base de código, expõe opções e forma 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 confiantemente a coisa errada.
  • /opsx:propose <name> cria openspec/changes/<name>/ e esboça a proposta, especificações de delta, design opcional e lista de tarefas em um único passo. Você revisa o plano aqui, antes de a implementação começar.
  • /opsx:apply percorre a lista de tarefas, marcando itens conforme avança. Como o progresso reside em arquivos e não apenas no histórico de chat, você pode limpar sua janela de contexto ou iniciar uma sessão nova e retomar exatamente onde /opsx:apply deixou.
  • /opsx:archive arquiva a alteração concluída em openspec/changes/archive/YYYY-MM-DD-<name>/ e mescla suas especificações de 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 de cada vez em vez de tudo de uma vez – alterne para ele com openspec config profile seguido por openspec update.

Cada ferramenta escreve o mesmo comando de forma diferente dependendo de como 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 chutar.

Como uma Alteração se Parece no Disco

Uma pasta de alteração sob openspec/changes/add-dark-mode/ tipicamente contém uma proposta, uma especificação de 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 que o OpenSpec evite reescrever um arquivo de especificação inteiro por uma alteração de um campo. É também o motivo pelo qual o OpenSpec é explicitamente priorizando brownfield em vez de greenfield: você nunca documenta sua aplicação inteira antes de obter valor, apenas documenta a fatia que cada alteração real toca, e openspec/specs/ se preenche naturalmente ao longo de meses de trabalho normal.

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

openspec list                 # alterações ativas
openspec show add-dark-mode   # ver os artefatos de uma alteração
openspec validate --all       # verificar formatação de especificação em todo o projeto
openspec view                 # painel interativo

Commite a pasta inteira openspec/ para git. As alterações ativas e o arquivo são destinados a se tornarem um registro duradouro e versionado do que seu sistema faz e por que ele mudou – não um rascunho que você deleta 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 “meu app tem 80.000 linhas antigas, eu tenho que especificar tudo primeiro?” Você não tem. A própria orientação do OpenSpec é franca sobre isso: escolha algo pequeno e real que você já ia construir nesta 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 alteração com escopo apenas para aquela fatia.

Se você já tem PRDs, documentos SRS ou designs documentados 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 formar um delta focado 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 alteração real, o comando expandido /opsx:onboard varre sua base de código por uma melhoria pequena e segura e percorre o loop completo nela.

Perguntas Comuns e Problemas

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

“Eu digitei o comando com barra e nada aconteceu.” Quase sempre uma destas: você digitou no terminal em vez do chat do seu assistente, seu IDE não reiniciou desde que openspec init rodou, ou a versão da CLI é antiga o suficiente para que openspec update reporte tudo atual sem nunca escrever os arquivos de fluxo de trabalho mais novos. Rode openspec update, reinicie o IDE e confirme que as pastas de skills 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 textos mais longos: um agente pode transformar um recurso de trinta minutos em uma especificação de 800 linhas. O OpenSpec limita o campo context: injetado em cada pedido a 50KB especificamente para forçar disciplina, mas as especificações de delta em si não têm limite rígido, então aparar especificações geradas para o que é realmente sustentáculo é um hábito que você tem que manter por si mesmo, não algo que a ferramenta impõe por você.

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

“Qual modelo de IA eu deveria realmente usar com isso?” Os próprios docs do OpenSpec recomendam modelos de alto raciocínio para ambos planejamento e implementação – modelos classe Opus e 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 do Spec Kit, Kiro, Superpowers ou BMAD?” Esta é a única pergunta mais frequente no Reddit, e a resposta honesta é “peso do processo”. O próprio README do OpenSpec enquadra a comparação diretamente: Spec Kit é minucioso mas mais pesado, com mais Markdown e fases rígidas; Kiro é poderoso mas te trava no IDE da AWS e modelos Claude; OpenSpec troca um pouco dessa estrutura inicial pela habilidade de iterar livremente e trabalhar com qualquer assistente que você já tenha aberto. Para a quebra completa contra Spec Kit, Kiro, skills do Claude Code, BMAD-METHOD e Superpowers, veja a comparação de ferramentas SDD.

“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 exclusivo do OpenSpec – uma janela de contexto grande não significa que o agente atenda igualmente a cada parte dela. O comando /opsx:verify existe especificamente para pegar código gerado que contradiz sua própria especificação, e vale a pena rodar em qualquer coisa não trivial em vez de confiar na implementação cegamente.

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

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 o sistema inteiro antecipadamente.
  • Desenvolvedores solitários e pequenas equipes que querem cerimônia mais leve do que Spec Kit mas ainda obtêm 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 querería um documento de design curto.
  • Equipes já comprometidas a revisar planos em pull requests – especificações de delta diferenciam limpo porque descrevem apenas o que mudou.

Encaixe mais fraco:

  • Correções de bug de uma linha e protótipos descartáveis, onde o passo de proposta-revisão custa mais do que economiza.
  • Equipes que precisam da estrutura mais pesada e prescritiva do Spec Kit ou uma experiência nativa da AWS e integrada ao IDE como Kiro – veja o quadro de decisão na comparação de ferramentas para onde cada ferramenta vence.
  • Recursos multi-repositório 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 várias bases de código e agentes possam ler o mesmo plano.
  • Qualquer pessoa ainda decidindo se um recurso específico merece uma especificação ou não – leia Desenvolvimento Orientado por Especificação vs Vibe Coding primeiro, já que o OpenSpec só ajuda depois que você já decidiu que estrutura vale o sobrepeso.

Conclusão

A aposta do OpenSpec é que a maioria 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 priorizando brownfield tornam notavelmente mais leve do que Spec Kit ou Kiro para adotar em uma base de código que você não construiu do zero. As compensações são reais também – o inchaço de especificação é um risco genuíno sem disciplina, o tratamento de conflito em torno de alterações simultâneas a um requisito ainda está amadurecendo, e o ecossistema é mais jovem do que as ferramentas próprias da GitHub. Instale em um projeto real, rode uma pequena alteração através de explorar-propor-aplicar-arquivar de ponta a ponta, e decida a partir daí se a cerimônia mais leve compensa seu trabalho real.

Subscrever

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