O que é o OpenSpec? Instalação e fluxos de trabalho

O OpenSpec é um framework leve de desenvolvimento orientado por especificações (Spec-Driven Development). Ele adiciona uma camada de acordo entre você e o seu assistente de programação com IA: escreva o que deve ser construído, revise o plano e só então escreva o código, em vez de deixar os requisitos existirem apenas no histórico do chat. Tem licença MIT, é compatível com mais de 30 ferramentas de programação com IA e o próprio fluxo de trabalho do HagiCode é construído sobre ele. Esta página é o caminho mais curto para instalá-lo e executar uma primeira mudança completa; os guias completos ficam em um site dedicado.

Conceitos principais

O OpenSpec se baseia em cinco ideias:

1. As especificações (specs) são a fonte da verdade. Elas descrevem como o sistema se comporta agora, ficam em openspec/specs/, são organizadas por domínio e compostas de requisitos e cenários.
2. Uma mudança (change) é uma unidade de trabalho. Para adicionar, modificar ou remover um comportamento, você cria uma pasta em openspec/changes/ que reúne a proposta, o design, a lista de tarefas e as alterações das especificações desse trabalho.
3. As especificações delta descrevem apenas o que muda. Dentro de uma mudança você não reescreve a especificação inteira; escreve ADDED, MODIFIED e REMOVED, e é isso que o torna bom para editar sistemas existentes.
4. Os artefatos se apoiam uns nos outros. proposal (por quê) → specs (o quê) → design (como) → tasks (passos) → implementação. São facilitadores, não barreiras, e você pode voltar a qualquer um deles.
5. Arquivar devolve a mudança à fonte da verdade. Quando o trabalho termina, as especificações delta são incorporadas às principais e a pasta da mudança vai para changes/archive/ com a data.

Instalação

Você precisa do Node.js 20.19.0 ou superior (os outros componentes do HagiCode recomendam a versão 24 ou superior; veja Instalar o Node.js).

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

No macOS e no Linux também é possível usar o Homebrew: brew install openspec. pnpm, yarn (1.x) e bun também instalam globalmente, mas o OpenSpec continua rodando no Node.js.

Depois, vá até o diretório do seu projeto e inicialize:

cd your-project
openspec init

A inicialização pergunta quais ferramentas de IA você usa e gera arquivos de skills ou comandos para elas. Para pular as perguntas, use openspec init --tools claude,cursor; os IDs das ferramentas estão em Ferramentas compatíveis.

Sua primeira mudança completa

Os comandos com barra vão no chat do seu assistente de IA, não no terminal:

/opsx:explore            # ainda não tem certeza? deixe a IA ler o código e avaliar as opções
/opsx:propose add-dark-mode   # cria a pasta da mudança: proposal, specs, design, tasks
/opsx:apply              # implementa a lista de tarefas
/opsx:archive            # arquiva; as specs delta são incorporadas às principais

/opsx:propose cria openspec/changes/add-dark-mode/ com proposal.md, specs/, design.md e tasks.md. As especificações são Markdown simples, sem sintaxe especial:

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

A IA escreve isso e você revisa o plano antes de qualquer código ser escrito. O perfil padrão inclui propose, explore, apply, update, sync e archive. Para o fluxo expandido (new, continue, ff, verify, bulk-archive e outros), escolha-o com openspec config profile e aplique com openspec update.

Os nomes dos comandos variam um pouco entre assistentes

/opsx:propose é a grafia canônica. No Cursor e no GitHub Copilot é /opsx-propose, no Amazon Q é @opsx-propose e no Codex é $openspec-propose. O openspec init mostra a forma correta para as ferramentas que você escolheu.

Atualização

npm install -g @fission-ai/openspec@latest   # atualiza o pacote
openspec update                              # atualiza os arquivos de instruções de IA em cada projeto

Se você instalou com o Homebrew, use brew upgrade openspec.

Problemas comuns

• openspec: command not found: o diretório global do npm não está no seu PATH. Execute npm prefix -g; no macOS e no Linux, adicione o bin/ desse diretório ao PATH, e no Windows adicione o próprio diretório.
• “Requires Node.js 20.19.0 or higher”: verifique com node --version e atualize.
• /opsx:propose não aparece no chat: confirme que você digitou no assistente e não no terminal, execute openspec update para gerar os arquivos novamente e reinicie o assistente. Ferramentas que só usam skills, como o Codex, precisam do formato $openspec-propose.
• A inicialização não configurou a sua ferramenta: execute openspec init novamente ou passe --tools.

Documentação completa

Abrir a documentação do OpenSpec em português

• Instalar o OpenSpec
• Primeiros passos
• Fluxos de trabalho
• Solução de problemas

Leitura complementar

• Para decidir entre ele e o Spec Kit do GitHub, leia Spec Kit vs OpenSpec.
• A prática do HagiCode sobre o OpenSpec: Otimizando a eficácia de cada etapa do OpenSpec com diferentes Agentes: resumo da prática do HagiCode e O que é MonoSpecs: por que é uma atualização e extensão do OpenSpec.