OpenSpec na prática: revise a especificação antes do código (e por que o detalhe importa)

OpenSpec na prática: revise a especificação antes do código (e por que o detalhe importa)

calendar_today • schedule7 min read

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.

1 Comment

0 votes
🔥 Join developers growing publicly
Share your knowledge, build in public, and grow your developer presence with a global community.

More Posts

I’m a Senior Dev and I’ve Forgotten How to Think Without a Prompt

Karol Modelski - Mar 19

Frameworks Are Institutional Memory

Ken W. Algerverified - Sep 17

A Message From Our Founder: On the Winding Down of LaaSy™

Ken W. Algerverified - Oct 29

Merancang Backend Bisnis ISP: API Pelanggan, Paket Internet, Invoice, dan Tiket Support

Masbadar - Mar 13

TypeScript Complexity Has Finally Reached the Point of Total Absurdity

Karol Modelski - Apr 23
chevron_left
172 Points • 7 Badges
2Posts
0Comments

Related Jobs

View all jobs →

Commenters (This Week)

3 comments
2 comments

Contribute meaningful comments to climb the leaderboard and earn badges!