TL;DR
O problema com o Claude Code não é a qualidade do código é quando você pula a spec e vai direto para a implementação
Com o workflow Spec → PR: loop de revisão de 3 iterações caiu para 1 | retrabalho de implementação reduziu ~80%
Template de spec copiável em 6 campos o artefato principal desta edição
Workflow em 5 etapas: Escrever → Validar → Implementar → Testar → PR
Quando NÃO usar spec - porque processo pesado para tarefa simples é desperdício
O Problema
Durante meses fiz a mesma coisa que a maioria faz.
Abria o Claude Code, colava um contexto rápido do que precisava, e mandava implementar. O código vinha. Funcionava. E mesmo assim eu sempre acabava pedindo mudanças.
"Coloca validação no campo X."
"Ah, o erro precisa aparecer de forma diferente."
"Na verdade o comportamento esperado quando o usuário faz Y é Z."
Três iterações de revisão para uma feature que deveria ter levado uma.
Por um tempo atribuí isso à ferramenta. Depois percebi que era eu.
O Claude entregava código correto para o problema que eu descrevi. O problema era que eu descrevia o problema de forma incompleta. Sem edge cases. Sem comportamento esperado de erros. Sem deixar claro o que era obrigatório versus o que era detalhe de UX.
Código perfeito para a spec errada ainda é retrabalho.
A Mudança
A solução não foi um prompt melhor. Foi mudar a ordem das coisas.
Antes de mandar qualquer instrução de implementação, eu passo por um ciclo de 5 etapas:
Escrevo a spec
Valido a spec com o Claude antes de qualquer código
Implemento com escopo delimitado
Gero testes alinhados com a spec
Gero a PR description com o contexto
O resultado em números: loop de revisão de 3 iterações → 1. Retrabalho de implementação caindo ~80%. PR descriptions que o revisor aprova sem pedir explicação adicional.
O motivo técnico é simples: o Claude tem muito mais capacidade de ajudar quando o problema está bem definido. Uma spec completa é contexto. E contexto é o insumo principal do modelo.
Tutorial Passo-a-Passo
Etapa 1: Escrever a Spec
A spec não é um documento longo. São 6 campos preenchidos antes de qualquer implementação começar.
Template copiável:
# Spec: [Nome da Feature]
## Problema
[O que está errado ou faltando hoje? 2-3 frases. Comportamento atual vs comportamento esperado.]
## Solução proposta
[O que será implementado. Sem detalhes técnicos ainda — foque no comportamento do usuário/sistema.]
## Comportamento esperado
[Descreva os fluxos principais:]
- Fluxo feliz: [o que acontece quando tudo funciona]
- Erro esperado: [o que acontece quando X falha]
- Edge case: [o que acontece quando Y é inválido ou inesperado]
## Fora de escopo
[O que explicitamente NÃO será implementado nesta iteração. Esse campo é tão importante quanto o anterior.]
## Critérios de aceite
- [ ] [Comportamento verificável 1]
- [ ] [Comportamento verificável 2]
- [ ] [Comportamento verificável 3]
## Contexto técnico
[Stack relevante, arquivos afetados, dependências existentes que a implementação precisa respeitar.]
Exemplo preenchido: feature de reset de senha:
# Spec: Reset de Senha via Email
## Problema
Usuários que esquecem a senha não conseguem recuperar acesso sem contato com suporte.
Suporte recebe ~20 tickets/semana de reset manual. Comportamento atual: sem mecanismo de
auto-serviço. Comportamento esperado: usuário consegue redefinir senha sem intervenção humana.
## Solução proposta
Fluxo de reset em 2 etapas: (1) usuário solicita email com link, (2) usuário acessa link
e define nova senha. Link expira em 1 hora.
## Comportamento esperado
- Fluxo feliz: usuário informa email → recebe link → clica → define nova senha → login funciona
- Erro esperado: email não cadastrado → mensagem genérica (não revelar se email existe)
- Edge case: link expirado → mensagem clara + botão para solicitar novo link
- Edge case: link já usado → mensagem informando que link é de uso único
## Fora de escopo
- Reset via SMS
- Perguntas de segurança
- Histórico de senhas anteriores
## Critérios de aceite
- [ ] Email chega em até 2 minutos após solicitação
- [ ] Link expira após 1 hora
- [ ] Link não funciona após primeiro uso
- [ ] Página de nova senha valida: mínimo 8 chars, 1 número, 1 letra maiúscula
- [ ] Email inválido não revela se endereço existe na base
## Contexto técnico
Stack: Next.js 14, Prisma, SendGrid. Tabela users no Postgres.
Criar tabela password_reset_tokens (userId, token, expiresAt, usedAt).
Respeitar middleware de rate limiting existente em /api/auth/*.
Por que funciona: O Claude para de inferir intenção. O campo "Fora de escopo" é especialmente importante, elimina a tendência natural de adicionar funcionalidade que pareceria útil mas está fora do problema atual.
Resultado esperado: uma spec que você consegue mostrar para qualquer membro do time e receber a mesma interpretação.
Etapa 2: Validar a Spec com Claude Antes de Implementar
Com a spec escrita, o próximo passo é entregá-la ao Claude para revisão, não para implementação.
Prompt de validação:
Revise esta spec antes de qualquer implementação.
Identifique:
1. Ambiguidades — comportamentos que estão abertos para interpretação
2. Edge cases faltando — situações que a spec não cobre
3. Contradições internas — campos que conflitam entre si
4. Dependências ocultas — algo que parece simples mas exige X que não está especificado
NÃO comece a implementar. Só valide.
Liste os problemas encontrados em ordem de severidade.
O que acontece na prática:
Na spec de reset de senha acima, o Claude apontou dois problemas reais que eu não tinha visto:
O critério de aceite diz "mínimo 8 chars" mas a spec de solução não menciona onde fica a validação no frontend, no backend, ou nos dois. Ambiguidade.
O edge case de "link já usado" tem mensagem, mas o fluxo não especifica se o usuário é redirecionado para solicitar novo link automaticamente ou precisa navegar manualmente. Comportamento aberto.
Encontrar isso na revisão da spec leva 2 minutos. Encontrar isso na revisão de código leva um ciclo inteiro de retrabalho.
Prompt de ajuste após validação:
Corrija os itens [1] e [2] da revisão anterior.
Não altere os outros campos — apenas os pontos sinalizados.
Resultado esperado: spec sem ambiguidades que o Claude possa usar como referência durante toda a implementação.
Etapa 3 — Implementação com Escopo Delimitado
Com a spec validada, a implementação segue um formato específico.
Prompt de implementação:
Implemente a feature descrita nesta spec.
[colar spec completa]
Regras:
1. Implemente APENAS o que está em "Solução proposta" e "Comportamento esperado"
2. Não implemente nada que está em "Fora de escopo"
3. Se encontrar uma decisão não coberta pela spec, PARE e pergunte — não infira
4. Antes de começar, liste os arquivos que serão criados ou modificados
Comece pelo plano. Só depois implemente.
A instrução "se encontrar uma decisão não coberta, PARE e pergunte" é a mais importante.
Sem ela, o Claude completa lacunas por inferência. A inferência pode estar correta. Mas você não sabe e o revisor também não sabe que foi uma decisão implícita, não explícita. Isso cria PRs que parecem completos mas carregam decisões silenciosas.
Resultado esperado: implementação que cobre exatamente os critérios de aceite sem mais, sem menos.
Etapa 4: Testes Alinhados com a Spec
A maioria dos desenvolvedores pede testes depois que o código está pronto.
O problema é que testes gerados a partir do código tendem a testar o que o código faz não o que deveria fazer. Se o código tem um bug, o teste vai documentar o bug como comportamento esperado.
Prompt de testes:
Crie testes para esta feature. Use a spec abaixo como fonte de verdade —
não o código que foi implementado.
[colar spec completa]
Regras:
1. Cada critério de aceite deve ter pelo menos um teste
2. Cada edge case descrito na spec deve ter um teste
3. Se o comportamento implementado divergir da spec, aponte a divergência —
não crie um teste que valide o comportamento errado
4. Testes de integração para os fluxos principais, unitários para validações
Na prática, o Claude identificou uma divergência na feature de reset de senha: o código implementado não redirecionava automaticamente ao usar link expirado, mas a spec (após o ajuste da Etapa 2) especificava esse redirecionamento. Pegou em testes, não em produção.
Resultado esperado: cobertura de todos os critérios de aceite, com testes que validam comportamento esperado, não comportamento implementado.
Etapa 5: PR Description Automática com Contexto
PR descriptions geradas a partir de diff de código são genéricas. Geradas a partir da spec, têm contexto.
Prompt de PR description:
Crie a PR description para esta feature usando a spec abaixo como base.
[colar spec completa]
Formato da description:
## O que muda
[1-3 bullets com o comportamento novo — perspectiva de usuário, não de código]
## Por que muda
[O problema que estava sendo resolvido — campo "Problema" da spec]
## O que NÃO muda
[Campo "Fora de escopo" formatado como contexto para o revisor]
## Como testar
[Passos concretos para o revisor verificar os critérios de aceite — não "rode os testes"]
## Decisões e trade-offs
[Qualquer decisão de implementação que não estava na spec + justificativa]
O resultado na prática:
A PR description gerada cobre exatamente o que o revisor precisa saber. O campo "O que NÃO muda" é especialmente útil: elimina comentários de revisão do tipo "por que você não adicionou X?" quando X estava explicitamente fora de escopo.
Resultado esperado: PR aprovada sem pedido de contexto adicional.
Antes e Depois
Métrica | Sem spec | Com spec |
|---|---|---|
Iterações de revisão (média) | 3 | 1 |
Decisões implícitas por PR | 4-6 | 0-1 |
Testes que documentam bugs | Comum | Raro |
Tempo de review por PR | ~45 min | ~15 min |
Retrabalho pós-review | ~2h | ~20 min |
Os números são da minha experiência em features de complexidade média formulários, fluxos de auth, integrações de API. Features triviais tendem a não precisar de spec. Features muito complexas podem precisar de mais iterações mesmo com spec.
Quando NÃO Usar Spec
Processo tem custo. Spec para tarefa errada é desperdício.
Não precisa de spec quando:
A tarefa é uma mudança de texto, cor, ou ajuste visual pequeno
É um bug fix com causa e solução claros
É um refactoring interno sem mudança de comportamento
A tarefa leva menos de 30 minutos para implementar manualmente
Regra prática: se você consegue descrever a tarefa em uma frase e não existe nenhum edge case que você precisaria tratar diferente, não precisa de spec. Vai direto.
Precisa de spec quando:
A feature tem mais de um fluxo de usuário
Existem estados de erro que precisam de comportamento específico
A tarefa vai tocar em mais de 3 arquivos
Outro desenvolvedor vai revisar e precisará entender a intenção
A heurística mais simples: se você já pediu uma implementação, recebeu o código, e teve que pedir mudanças, aquela feature precisava de spec.
Referência Rápida
Tudo que você precisa para começar, inline e copiável ;)
Template de Spec (Etapa 1)
# Spec: [nome da feature]
## Problema
[Comportamento atual vs esperado — 2-3 frases]
## Solução proposta
[O que será implementado — foco no comportamento, não em detalhes técnicos]
## Comportamento esperado
- Fluxo feliz: [o que acontece quando tudo funciona]
- Erro esperado: [o que acontece quando X falha]
- Edge case: [o que acontece quando Y é inválido ou inesperado]
## Fora de escopo
[O que explicitamente NÃO será implementado nessa iteração]
## Critérios de aceite
- [ ] [Comportamento verificável 1]
- [ ] [Comportamento verificável 2]
- [ ] [Comportamento verificável 3]
## Contexto técnico
[Stack relevante, arquivos afetados, dependências existentes]
Prompts do Workflow (Etapas 2 a 5)
Etapa 2: Validar spec antes de implementar
Revise esta spec antes de qualquer código.
Identifique:
1. Ambiguidades — comportamentos abertos para interpretação
2. Edge cases faltando
3. Contradições internas
4. Dependências que a spec não menciona
NÃO comece a implementar. Só liste os problemas.
Etapa 3: Implementação com escopo delimitado
Implemente a feature desta spec.
[colar spec completa]
Regras:
1. Implemente APENAS o que está em "Solução" e "Comportamento esperado"
2. Não implemente nada em "Fora de escopo"
3. Se encontrar decisão não coberta pela spec, PARE e pergunte
4. Liste os arquivos que serão modificados antes de começar
Etapa 4: Testes a partir da spec
Crie testes usando a spec como fonte de verdade — não o código implementado.
Se o comportamento implementado divergir da spec, aponte a divergência.
Não crie teste que valide comportamento errado.
Etapa 5: PR description
Crie a PR description usando a spec abaixo.
## O que muda
[perspectiva de usuário, não de código]
## Por que muda
[o problema que estava sendo resolvido]
## O que NÃO muda
[campo "Fora de escopo" formatado para o revisor]
## Como testar
[passos para verificar os critérios de aceite]
## Decisões e trade-offs
[o que não estava na spec + justificativa]
Checklist Spec → PR
Antes de qualquer feature nova:
[ ] Spec escrita com os 6 campos preenchidos
[ ] Campo "Fora de escopo" preenchido explicitamente
[ ] Spec validada pelo Claude antes de implementar
[ ] Ambiguidades resolvidas antes de começar
[ ] Prompt de implementação inclui a spec completa
[ ] Prompt de testes referencia a spec, não o código
[ ] PR description gerada a partir da spec
[ ] Decisões implícitas listadas antes de abrir o PR
Próximos Passos
Hoje: Pegue a próxima feature que você vai implementar e preencha os 6 campos do template antes de abrir o Claude Code. Não precisa ser perfeito, o objetivo é ver onde as lacunas aparecem.
Esta semana: Use o prompt de validação (Etapa 2) em uma spec que você já escreveu. Compare o que o Claude aponta com o que você acabaria descobrindo durante a revisão de código.
Na próxima PR: Use o prompt de PR description a partir da spec. Observe se o revisor pede menos contexto.
Daqui a duas semanas: Meça quantas iterações de revisão você teve nas features com spec versus sem spec. A diferença vai ser visível ;)
Adriano Viana
Master Architect | AI-Native Content Creator