OpenSpec na prática: revise a especificação antes do código
Assistentes de IA escrevem código rápido. O problema é que escrevem código errado na mesma velocidade quando a especificação está errada ou incompleta.
Quando você pede "implemente a recuperação de senha", o modelo precisa decidir sozinho: o link expira? Pode ser reutilizado? O que acontece se o e-mail não existe? Cada lacuna vira uma suposição plausível, escrita com confiança, dentro de um diff de 800 linhas que você vai revisar com pressa.
O OpenSpec ataca esse problema colocando a especificação como artefato de primeira classe: arquivos Markdown no repositório, revisáveis como código. Este artigo é sobre a parte do fluxo que mais rende e mais se pula: revisar e detalhar a spec antes de mandar implementar.
TL;DR
- 🧭 A spec é o lugar mais barato para achar um erro: revisar 40 linhas custa minutos, revisar um diff errado custa o dia.
- 🕳️ Toda lacuna na spec é uma decisão que o modelo toma sem você ver.
- ✅ Spec com a estrutura certa pode ser inútil. Validação confere formato, não significado.
- 🚦 O portão de revisão humana entre propor e implementar não vem pronto: você precisa impô-lo.
O que é o OpenSpec (em um parágrafo)
O OpenSpec é um framework de desenvolvimento guiado por especificação para assistentes de IA. Você descreve a mudança, ele gera artefatos de planejamento, o assistente implementa a partir deles, e no fim as mudanças viram parte das specs "oficiais" do projeto. Ele funciona com dezenas de ferramentas de IA para código, incluindo Claude, Cursor e GitHub Copilot.
Para começar:
npm install -g @fission-ai/openspec@latest
openspec init
O init cria uma pasta openspec/ com:
openspec/
├── specs/ # comportamento atual do sistema (fonte da verdade)
├── changes/ # mudanças em andamento
└── archive/ # mudanças concluídas
Cada mudança em andamento ganha sua própria pasta com proposal.md, design.md, tasks.md e os delta specs, que descrevem o que foi adicionado, modificado ou removido em relação às specs atuais.
O fluxo recomendado hoje usa estes comandos no seu assistente:
/opsx:explore → /opsx:propose → /opsx:apply → /opsx:verify → /opsx:archive
Os nomes dos comandos mudaram entre versões do OpenSpec. Os acima são os da documentação atual (outubro de 2026). Confira a documentação da versão que você instalou.
Repare no que não está nessa lista: um passo de "alguém lê a spec". Esse passo é seu.
Por que a spec é o lugar mais barato para achar erros
1. O modelo preenche lacunas com suposições.
Uma spec incompleta não gera erro, gera código plausível. Você não vê a decisão sendo tomada, só o resultado, que parece razoável. É o pior tipo de bug: o que passa na revisão por parecer certo.
2. Revisar intenção é mais barato que revisar implementação.
Ler 40 linhas de requisitos e cenários exige discutir comportamento. Ler 800 linhas de diff exige reconstruir o comportamento a partir do código, e é aí que a atenção cai.
3. A spec fica no git.
Os delta specs (ADDED, MODIFIED, REMOVED) mostram exatamente o que muda no comportamento do sistema. Dá para abrir um pull request só da spec, discutir antes de existir código e ter histórico das decisões.
Spec vaga vs. spec detalhada
Veja um requisito que tem a estrutura certa e mesmo assim não ajuda. (O formato usa palavras-chave em inglês, SHALL, GIVEN/WHEN/THEN, então os exemplos de spec ficam em inglês.)
### Requirement: Password reset
The system SHALL allow users to reset their password.
#### Scenario: User resets password
- WHEN the user requests a reset
- THEN the user receives a link and can set a new password
Requisito, cenário, WHEN/THEN. Estruturalmente está correto. Mas deixa em aberto:
- O link expira? Em quanto tempo?
- Pode ser usado duas vezes?
- Se o e-mail não existe, a resposta é diferente? (Isso vaza quais e-mails têm conta.)
- Existe limite de pedidos?
- Pedir um novo link invalida o anterior?
Agora uma versão em que alguém decidiu essas coisas. (Os valores, 30 minutos e 5 pedidos por hora, são ilustrativos. O importante é que alguém escolheu.)
### Requirement: Password reset by email
The system SHALL send a single-use reset link that expires 30 minutes after it is issued.
#### Scenario: Valid reset request
- GIVEN a registered email address
- WHEN the user requests a password reset
- THEN an email with a reset link is sent
- AND any previously issued link for that account is invalidated
#### Scenario: Unknown email
- GIVEN an email address that is not registered
- WHEN the user requests a password reset
- THEN the response is identical to the valid case
- AND no email is sent
#### Scenario: Expired link
- GIVEN a reset link issued more than 30 minutes ago
- WHEN the user opens it
- THEN the system shows an "expired link" message and offers to request a new one
#### Scenario: Reused link
- GIVEN a reset link that was already used
- WHEN the user opens it again
- THEN the system rejects it and does not change the password
#### Scenario: Too many requests
- GIVEN 5 reset requests for the same email within 1 hour
- WHEN another request arrives
- THEN the system does not send another email
- AND the response does not reveal that a limit was hit
Cada cenário agora é observável e testável. Quem implementa, humano ou IA, não precisa adivinhar. E quem revisa consegue discordar de algo específico ("30 minutos é pouco para o nosso público").
A revisão ainda acha lacunas
Mesmo a versão detalhada tem um buraco, e foi a revisão que o encontrou: "e as sessões que já estavam abertas quando a senha foi trocada?"
Essa pergunta vira uma adição à spec antes de existir qualquer código:
## ADDED Requirements
### Requirement: Session revocation after reset
The system SHALL revoke all active sessions of an account when its password is reset.
#### Scenario: Sessions revoked
- GIVEN a user with two active sessions
- WHEN the password is reset through a reset link
- THEN both sessions are revoked
Custo da descoberta: uma conversa de dois minutos. Se tivesse aparecido em produção, seria um incidente de segurança.
Checklist de revisão de spec
Use na hora de ler a proposta, antes de rodar /opsx:apply:
Requisitos e cenários
- [ ] Todo requisito tem pelo menos um cenário?
- [ ] O
THEN de cada cenário é verificável (teste, comando ou resultado observável)?
- [ ] Os caminhos de erro estão cobertos: entrada vazia, duplicada, expirada, sem permissão, falha de rede?
- [ ] Limites e valores estão definidos (tempos, tamanhos, quantidades) em vez de adjetivos?
Linguagem
- [ ] Não há "rápido", "seguro", "amigável" sem um critério mensurável?
- [ ] O mesmo conceito tem sempre o mesmo nome?
- [ ] A spec descreve comportamento, não implementação? ("a resposta é idêntica", não "usar a tabela X")
Escopo
- [ ] O
proposal.md diz o que está fora do escopo?
- [ ] O que muda em specs existentes está explícito nos
MODIFIED, com o valor anterior anotado?
Segurança e privacidade
- [ ] A spec diz o que não deve ser revelado ou registrado?
- [ ] Permissões e autenticação estão explícitas por cenário?
Design e tarefas
- [ ] O
design.md registra decisões e alternativas descartadas?
- [ ] Cada tarefa do
tasks.md é pequena e termina em algo verificável?
Um exemplo de tarefa verificável:
## 1. Reset flow
- [ ] 1.1 Generate single-use token with 30-minute expiry (test: expired token is rejected)
- [ ] 1.2 Invalidate previous tokens on new request (test: old link fails after new request)
O que a validação automática pega, e o que não pega
O OpenSpec tem openspec validate (com opções como --strict) para checar changes e specs, e openspec show para inspecioná-las. Útil para garantir que a estrutura está consistente.
Mas validação confere forma, não significado. A spec vaga do exemplo acima tem forma perfeita. Ambiguidade, lacuna de caso de borda e termo inconsistente só um leitor atento acha. É por isso que o portão de revisão é humano.
A spec não é um contrato congelado
Revisar bem antes não significa nunca mais mexer. A própria documentação do OpenSpec prevê atualizar os artefatos (/opsx:update) quando a implementação revela algo novo. A regra prática:
- Descobriu um caso novo durante a implementação? Atualize a spec primeiro, depois o código.
- Mudou uma decisão? Registre no
design.md.
- No fim,
/opsx:verify confere a implementação contra a spec e /opsx:archive sincroniza os deltas com as specs principais.
Se o código muda e a spec não, a spec vira documentação mentirosa, e perde o motivo de existir.
Armadilhas comuns
- Aprovar sem ler porque "a IA escreveu". A IA escreveu rápido. Isso não diz nada sobre estar certo.
- Spec que descreve a solução em vez do problema. "Criar a tabela
reset_tokens" é implementação. "O link é de uso único" é comportamento.
- Spec gigante que ninguém lê. Se a proposta tem 40 cenários, a mudança provavelmente é grande demais. Quebre em mais de uma.
- Detalhar demais mudança trivial. Trocar uma cor de botão não precisa de cinco cenários. Calibre o esforço pelo risco.
- Pular o
explore. Quando o problema ainda é nebuloso, /opsx:explore ajuda a pensar antes de gerar artefatos.
Fechando
O ganho do desenvolvimento guiado por spec não está em gerar arquivos Markdown. Está em mover a conversa difícil para antes do código, quando discordar custa minutos e ainda é possível mudar de ideia sem refatorar nada.
O OpenSpec dá o lugar e o formato. A revisão, a que acha a lacuna das sessões abertas, continua sendo trabalho de gente.
Você revisa a spec antes de mandar a IA implementar, ou só olha o código depois? E o que já te salvou na revisão?
Referências: repositório do OpenSpec
Trabalho como Flutter Sênior remoto, com Go como segunda stack. Se quiser trocar ideia sobre desenvolvimento com IA e arquitetura, me encontra no GitHub ou no LinkedIn.