Introdução ao OpenSpec: mantenha o senso de limites no seu framework de colaboração com IA usando especificações

Para iniciantes | Cerca de 15 minutos | Você vai dominar os conceitos centrais do OpenSpec (Delta Specs, grafo de dependências de Artifacts), o processo de inicialização, o fluxo de trabalho OPSX (propose → apply → archive) e o gerenciamento paralelo de múltiplas mudanças

---

Visão geral do projeto

Vamos começar admitindo um fato: ao usar um assistente de programação com IA, você já passou por situações como estas — a IA muda coisas que você não queria alterar; ou troca o contexto da conversa e simplesmente esquece o que tinha sido dito antes; ou então, a cada vez que você pede para a IA escrever uma nova funcionalidade, o resultado não tem nada a ver com o que você realmente queria?

Esses problemas não significam que a IA seja “boba demais”, mas sim que as necessidades nunca foram “assinadas e carimbadas”. Elas existem apenas nos registros da conversa, e a margem para a IA improvisar é enorme.

O que o OpenSpec faz é simples: antes de você colocar a mão no código, alinhar com a IA uma especificação — e então fazer a IA agir de acordo com essa especificação. Desenvolvido pela Fission-AI, ele oferece suporte a 20+ ferramentas de programação com IA (Claude Code, Cursor, Windsurf etc.) e, em essência, adiciona uma camada leve de gerenciamento de especificações ao seu assistente de programação com IA.

---

Perfil de público-alvo

• Desenvolvedores que usam assistentes de programação com IA no dia a dia
• Engenheiros que sofrem na colaboração em equipe com a falta de alinhamento entre humanos e IA sobre entendimento de requisitos
• Gerentes de produto que querem que a IA produza entregáveis com mais controle

Dependências e ambiente essenciais

• Node.js 20.19.0+

Estrutura completa em árvore do projeto

openspec/
├── specs/                    # Especificações do comportamento atual do sistema (por domínio)
│   └── <domain>/spec.md
├── changes/                  # Propostas de mudança (um diretório por mudança)
│   ├── <change-name>/
│   │   ├── proposal.md       # Intenção + Escopo + Abordagem
│   │   ├── specs/             # Delta Specs (ADDED/MODIFIED/REMOVED)
│   │   │   └── <domain>/spec.md
│   │   ├── design.md         # Design técnico
│   │   └── tasks.md          # Checklist de verificação da implementação
│   └── archive/               # Histórico arquivado
└── config.yaml               # Configuração do projeto (opcional)

---

Passo a passo

Etapa 1: Instale o OpenSpec globalmente

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

Depois, valide:

openspec --version
# 1.2.0

Etapa 2: Inicialize o projeto

Entre no diretório do seu projeto e execute o comando de inicialização:

cd your-project
openspec init

Esse comando faz três coisas:

1. Cria a estrutura de diretórios de openspec/
2. Gera os arquivos de habilidades em .claude/ (para que o assistente de IA reconheça os comandos /opsx:*)
3. Pergunta se você deseja criar o arquivo de configuração do projeto config.yaml (opcional, para injetar contexto do projeto)

Quando a inicialização terminar, seu projeto terá esses diretórios:

openspec/
├── specs/       # Especificação do comportamento atual do sistema (diretório vazio, aguardando preenchimento)
├── changes/     # Diretório de proposta de mudança (diretório vazio)
└── config.yaml  # Configuração do projeto (se você optou por criar)

Etapa 3: Ative o fluxo de trabalho da extensão OPSX

O OpenSpec recém-instalado vem por padrão no modo core, com apenas 4 comandos: propose, explore, apply, archive. Se você quiser usar o fluxo completo (incluindo new, continue, ff, verify, bulk-archive etc.), execute:

openspec config profile
# selecione expanded ou full
openspec update

openspec update vai regenerar os arquivos de habilidades de IA com base no profile que você escolheu, para que seja possível usar mais comandos na conversa com a IA.

Etapa 4: Crie a primeira mudança — adicione o modo escuro

Agora faça a IA criar uma mudança para você. Como exemplo, vamos “adicionar modo escuro” ao app. Basta dizer diretamente para a IA:

/opsx:propose add-dark-mode

A IA criará automaticamente quatro arquivos de Artifact em openspec/changes/add-dark-mode/:

openspec/changes/add-dark-mode/
├── proposal.md     # Por que essa mudança existe? Escopo? Abordagem?
├── specs/
│   └── ui/spec.md  # Delta Specs do domínio UI
├── design.md       # Como o design técnico será feito?
└── tasks.md        # O que exatamente precisa ser feito? Liste passo a passo

proposal.md fica assim (gerado automaticamente pela IA; você e a IA podem editar juntos):

# Proposal: Add Dark Mode

## Intent
O usuário solicitou a adição de modo escuro para reduzir o cansaço ocular durante o uso noturno.

## Scope
- Adicionar um botão de alternância de tema nas configurações
- Suportar detecção da preferência do sistema
- Persistir a preferência no localStorage

## Approach
Usar variáveis CSS para o tema e gerenciar o estado com React Context.

specs/ui/spec.md é o Delta Spec principal, com o formato abaixo:

# Delta for UI

## ADDED Requirements

### Requirement: Theme Selection
O sistema SHALL permitir ao usuário alternar entre os temas claro e escuro.

#### Scenario: Manual toggle
- GIVEN o usuário está em qualquer página
- WHEN o usuário clica no botão de alternância de tema
- THEN o tema muda imediatamente e a preferência é persistida entre sessões

#### Scenario: System preference
- GIVEN o usuário não salvou uma preferência
- WHEN o app é carregado
- THEN é usado o esquema de cores preferido do sistema

tasks.md é o checklist de verificação da implementação:

# Tasks

## 1. Theme Infrastructure
- [ ] 1.1 Criar ThemeContext (estado light/dark)
- [ ] 1.2 Adicionar definições de variáveis CSS de cores
- [ ] 1.3 Implementar persistência no localStorage

## 2. UI Components
- [ ] 2.1 Criar componente ThemeToggle
- [ ] 2.2 Adicionar botão de alternância na página de configurações
- [ ] 2.3 Adicionar alternância rápida no Header

## 3. Styling
- [ ] 3.1 Definir paleta de cores do tema escuro
- [ ] 3.2 Fazer os componentes existentes usarem variáveis CSS

Etapa 5: Execute as tarefas de implementação

Depois de confirmar que o documento de especificação está correto, execute a implementação:

/opsx:apply

A IA verifica as tarefas uma a uma em tasks.md; ao concluir cada item, ela marca um visto. Você vai notar que o comportamento da IA muda — ela deixa de improvisar e passa a avançar estritamente de acordo com tasks.md. Se durante a implementação você perceber que o design tem problemas, pode editar diretamente design.md e então continuar com apply; a IA acompanha automaticamente.

Etapa 6: Verifique e arquive a mudança

Verificação (opcional, mas recomendado):

/opsx:verify

A IA checa sua implementação em três dimensões:

Arquivar:

/opsx:archive

O arquivamento faz duas coisas:

1. Mescla os Delta Specs na especificação principal openspec/specs/ui/spec.md
2. Move a pasta da mudança para openspec/changes/archive/2026-04-11-add-dark-mode/

Quando o arquivamento terminar, os arquivos de especificação do sistema serão atualizados e você terá um histórico completo dessa mudança.

Etapa 7: Gerenciamento paralelo de múltiplas mudanças

Na prática, é comum ser interrompido no meio do desenvolvimento para resolver outros problemas. O OpenSpec suporta múltiplas mudanças em paralelo:

# Suponha que você esteja fazendo add-dark-mode e, de repente, precisa corrigir um bug
/opsx:new fix-login-redirect

# Concluir normalmente a correção do bug
/opsx:ff
/opsx:apply
/opsx:archive

# Voltar ao trabalho do modo escuro anterior
/opsx:apply add-dark-mode

Quando você tiver várias mudanças concluídas, arquive tudo junto:

/opsx:bulk-archive

O OpenSpec detecta automaticamente conflitos de especificação (quando duas mudanças alteram specs/ui/) e mescla na ordem cronológica.

Etapa 8: Personalize o Schema

O fluxo de trabalho OPSX do OpenSpec é definido com base em Schema, e você pode customizar completamente o tipo de Artifact e suas relações de dependência. Por exemplo, se você quer um fluxo “pesquise primeiro, depois proponha”:

# Derive um novo schema do schema padrão
openspec schema fork spec-driven research-first

A estrutura do Schema gerado fica assim:

openspec/schemas/research-first/
├── schema.yaml
└── templates/
    ├── research.md
    ├── proposal.md
    └── tasks.md

E o grafo de dependências correspondente vira:

research ──► proposal ──► tasks

No schema.yaml, defina:

# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
  - id: research
    generates: research.md
    requires: []

  - id: proposal
    generates: proposal.md
    requires: [research]

  - id: tasks
    generates: tasks.md
    requires: [proposal]

Etapa 9: Consulta rápida dos comandos mais usados no CLI

# Inicializar
openspec init

# Atualizar arquivos de habilidades de IA (é necessário rodar a cada upgrade ou após mudar o profile)
openspec update

# Ver a configuração atual
openspec config show

# Alternar o profile do fluxo de trabalho
openspec config profile

# Ver mudanças ativas
openspec list

# Ver detalhes de uma mudança
openspec show add-dark-mode

# Validar formato
openspec validate add-dark-mode

# Dashboard interativo
openspec view

# Gerenciamento de Schema
openspec schemas              # listar schemas disponíveis
openspec schema which --all   # ver de onde vêm os schemas
openspec schema validate my-schema  # validar schema

---

Solução de problemas comuns

1. A IA não encontra o comando /opsx:propose

Esse é o problema mais comum. Depois de executar openspec init, o assistente de IA precisa recarregar os arquivos de habilidades. Execute:

openspec update

Em seguida, reabra a conversa. Se a IA ainda não reconhecer, verifique manualmente se o diretório .claude/ existe.

2. openspec init acusa erro de versão do Node.js

node --version
# confirme que é >= 20.19.0

# se a versão estiver baixa, atualize com nvm
nvm install 20 && nvm use 20

3. Conflito ao mesclar Delta Specs

No /opsx:bulk-archive, se duas mudanças alterarem o mesmo arquivo de especificação, o OpenSpec vai detectar e te avisar. A mesclagem por padrão é feita na ordem do tempo. Se precisar fazer manualmente:

# Primeiro, arquive uma mudança isoladamente
/opsx:archive fix-login-redirect

# Depois, arquive a outra
/opsx:archive add-dark-mode

4. Falha ao carregar um Schema customizado

Geralmente é porque há um erro de sintaxe no schema.yaml. Verifique:

openspec schema validate my-schema

Erros comuns: indentação incorreta em YAML, e o campo requires de um artifact referenciando um ID que não existe (dependência circular).

5. O formato das especificações geradas pela IA não atende aos requisitos

Você pode adicionar regras no openspec/config.yaml:

rules:
  specs:
    - Use o formato GIVEN/WHEN/THEN para descrever cada cenário
    - Cada Requirement deve ter pelo menos um Scenario

Essas regras são injetadas nas instruções para a IA ao gerar especificações.

6. No processo /opsx:apply, a IA pula algumas tarefas

Diga diretamente para a IA:

Por favor, execute na ordem de tasks.md. A tarefa 1.3 ainda não foi concluída, não a pule.

A característica fluid do OpenSpec permite editar o Artifact a qualquer momento — depois de modificar tasks.md, faça apply novamente; a IA continuará de onde parou.

---

Leitura adicional / Direções de aprimoramento

Aprofunde-se no formato Delta Specs: ADDED/MODIFIED/REMOVED são três tipos de mudança com semânticas próprias — ADDED adiciona requisitos, MODIFIED substitui requisitos existentes e REMOVED remove requisitos obsoletos. Entender as regras de mesclagem entre eles é a chave para usar bem o OpenSpec.

Comparação entre OPSX e o fluxo Legacy: o OpenSpec v1.x usa o fluxo Legacy (/openspec:proposal), e a partir do v1.2+ o foco é OPSX. A diferença central entre os dois é: Legacy é phase-locked (ou tudo, ou nada), enquanto OPSX é fluid (qualquer Artifact pode ser editado a qualquer momento).

Guia de integração com 20+ ferramentas de IA: o OpenSpec gera arquivos de habilidades a partir do diretório .claude/skills/, compatível com ferramentas populares como Claude Code, Cursor, Windsurf e Copilot. Veja docs/supported-tools.md.

Integração do Slack para times: times corporativos podem contatar [email protected] para obter suporte em um canal do Slack dedicado, adequado para fluxos de gerenciamento e revisão de especificações em cenários de colaboração entre várias pessoas.

Customização profunda da configuração do projeto: além de context e rules, também é possível definir Schema padrão via config.yaml e injetar informações do stack técnico do projeto (por exemplo, framework de testes e padrões de estilo de código), para que as especificações geradas pela IA fiquem mais alinhadas ao seu projeto real.