Desenvolvimento Orientado por Spec com Claude Code

Problema: A taxa de sucesso na primeira tentativa do Claude Code em PRs de pequeno a médio porte sem orientação detalhada fica em torno de um terço, segundo a própria equipe de RL Engineering da Anthropic. Dois terços das vezes ele perde requisitos, interpreta o escopo de forma muito ampla ou escolhe o caminho de implementação errado. A solução não é mais prompting no meio da sessão. É escrever uma spec antes da sessão começar.

A matemática é brutal. Suponha que o Claude faça a escolha certa 80% das vezes em qualquer decisão individual. Uma funcionalidade típica envolve 20 decisões. Probabilidade de acertar todas as 20 sem orientação: 0,8^20, que é cerca de 1%. Uma spec revisada leva cada decisão perto da certeza porque você já fez a escolha. A spec não guia o Claude. Ela remove as decisões que ele não deveria estar tomando em primeiro lugar.

O Padrão em Quatro Fases

O desenvolvimento orientado por spec (SDD) roda em quatro fases: Requisitos, Design, Tarefas e Execução. As três primeiras acontecem em uma sessão. A quarta acontece em uma sessão separada.

Requisitos captura o que a funcionalidade deve fazer do ponto de vista do usuário. Histórias de usuário, critérios de aceitação, casos de borda. Não como. O quê.

Design captura a arquitetura: modelos de dados, contratos de API, quais arquivos mudam, quais ficam, qual é a decisão de stack para essa funcionalidade.

Tarefas é o plano de implementação ordenado com dependências explícitas. O passo 3 não pode começar antes do passo 2 estar concluído. Essa ordem importa quando o Claude está fundo numa cadeia de chamadas de ferramentas.

Execução roda em uma sessão completamente separada. Isso não é opcional.

Por que a Sessão Separada Importa

O Claude fica apegado ao próprio plano dentro da mesma sessão. Ele já raciocinou sobre os requisitos e o design, então carrega essas suposições implicitamente em vez de ler a spec como está escrita. Uma sessão separada força o Claude a ler a spec como um engenheiro novo faria: do começo, literalmente.

O consenso da comunidade sobre isso é unânime. Pimzino, cujo pacote claude-code-spec-workflow (3.700+ estrelas, 258 forks) formalizou essa abordagem depois de estudar a IDE spec-driven Amazon Kiro, descreve a sessão separada como não negociável. A sessão de spec usa Claude Opus para raciocínio profundo sobre os requisitos. A sessão de implementação usa Claude Sonnet para executar um plano claro. Trabalhos diferentes, modelos diferentes, sessões diferentes.

O Fluxo de Entrevista Recomendado pela Anthropic

A documentação oficial da Anthropic descreve a forma mais rápida de produzir uma boa spec: modo entrevista. Inicie uma sessão nova e rode:

I want to build [brief description]. Interview me in detail using 
the AskUserQuestion tool.

Ask about technical implementation, UI/UX, edge cases, concerns, 
and tradeoffs. Don't ask obvious questions, dig into the hard parts 
I might not have considered.

Keep interviewing until we've covered everything, then write a 
complete spec to SPEC.md.

O Claude faz perguntas até cobrir implementação, UX, casos de borda e trade-offs. Quando estiver satisfeito, escreve a spec em SPEC.md. Então você fecha a sessão. A próxima sessão abre a spec e constrói.

Essa transição é onde mora a maior parte do valor.

A Estrutura de Pastas

Para funcionalidades pequenas ou projetos solo, um único SPEC.md funciona bem. Para funcionalidades maiores com múltiplas partes em movimento, a comunidade chegou a um consenso de três arquivos dentro de uma pasta nomeada:

.claude/
├── commands/       # 14 slash commands
├── steering/       # product.md, tech.md, structure.md
├── specs/
│   └── {feature-name}/
│       ├── requirements.md
│       ├── design.md
│       └── tasks.md
├── bugs/           # bug fix workflows
└── agents/

A pasta steering/ funciona como memória do projeto entre sessões. product.md guarda a visão. tech.md guarda decisões de stack. structure.md guarda convenções de arquivos. Qualquer sessão que abre esses três arquivos começa com contexto que, de outra forma, levaria dezenas de mensagens para estabelecer.

Você pode instalar o scaffold completo do Pimzino com um comando:

npx @pimzino/claude-code-spec-workflow

A Regra de Corrigir o Teste

Sem uma spec, o Claude tem dois caminhos para um conjunto de testes verde: corrigir o código quebrado, ou modificar o teste com falha para esperar o comportamento errado. Às vezes ele escolhe o caminho mais fácil. Isso não é um bug. É uma otimização local racional quando não há restrição contra isso.

A restrição vai em SPEC.md ou CLAUDE.md:

## During Testing

**IMPORTANT!** When you find a failure during testing, **NEVER** ignore or remove 
the test to bypass the failure.

**ALWAYS** identify the root cause first.

If the root cause is in the *application's implementation*, then fix the application.
If the root cause is because the *test* was incorrectly made, then fix the test.

Isso é uma adição pequena. Ela fecha um dos modos de falha mais comuns em sessões sem orientação.

O Ponto Cego da Autoconsistência

Quando o Claude Opus escreve uma spec, ele não consegue ver as próprias lacunas. O raciocínio que gerou os requisitos ainda está ativo, então omissões que nunca foram consideradas continuam sem ser consideradas durante a revisão.

Rodar um modelo diferente (GPT ou Codex) para revisar adversarialmente uma spec gerada pelo Claude revela problemas importantes em quase todos os documentos. O padrão que funciona: dois agentes separados, cada um explicitamente encarregado de encontrar lacunas, casos de borda ausentes e conflitos de suposição. Um procura por requisitos ausentes. O outro procura por suposições de implementação embutidas no design que nunca foram apresentadas ao usuário. Ambos rodam antes que a implementação comece.

O Problema do Documento Vivo

No momento em que a spec fica desatualizada em relação ao código, a maior parte do benefício desaparece. Sessões subsequentes podem silenciosamente reverter mudanças não documentadas ou interpretar o escopo com base em um design desatualizado.

A solução vem de Sevak Avakians e corresponde ao que as equipes internas da Anthropic praticam: o último passo de qualquer plano de tarefa deve ser atualizações de documentação. Peça ao Claude para resumir o trabalho concluído e sugerir melhorias para o CLAUDE.md no final de cada sessão. A equipe de Data Science da Anthropic reporta economia de 2-4x em refatorações rotineiras. A equipe de Security Engineering reduziu o debug de infraestrutura de 10-15 minutos para 5 minutos. A equipe de Product Dev viu 70% de uma implementação de modo Vim concluída de forma autônoma. Em todos os casos, bom contexto no início da sessão foi a variável.

Documentação ao final da sessão não é overhead. É como a spec continua sendo útil depois do primeiro build.

Modos de Falha

Seis padrões quebram o SDD na prática:

Escopo excessivamente amplo. "Construa um sistema de gerenciamento de usuários" sem definir quais usuários, quais ações ou quais permissões faz o Claude interpretar ao máximo. A janela de contexto enche com trabalho que você não pediu.

Spec desatualizada. Alguém prompta uma mudança diretamente sem atualizar a spec. A próxima sessão lê a spec e silenciosamente reverte a mudança.

Tudo junto. Duas funcionalidades não relacionadas em uma spec. O Claude introduz contaminação cruzada entre elas. Mantenha specs em uma unidade coerente de trabalho.

Deriva de contexto. Uma spec na janela de contexto fica efetivamente "perdida" conforme a conversa cresce além de 15-20 chamadas de ferramentas. Sessões separadas para implementação previnem isso.

Spec gerada por LLM substituindo o pensamento. Um estudo da ETH Zurich descobriu que arquivos de agente gerados por LLM prejudicam o desempenho custando 20% mais tokens. Specs escritas por humanos ajudaram 4%. A spec só funciona se um humano a revisou e tomou decisões reais. Uma spec aprovada sem reflexão é ruído.

Sangramento de sessão. Rodar criação de spec e implementação na mesma sessão. O problema de apego se reinstala. A spec vira uma sugestão, não uma restrição.

Quando Usar Qual Padrão

Três opções cobrem toda a gama de tamanhos de projeto:

Os Architecture Decision Records vão em docs/adr/ com um prefixo numérico sequencial. Um arquivo por decisão. Eles capturam o que foi decidido, quais alternativas foram consideradas e por que essa opção venceu. Não são arquivos de spec. São registros permanentes de escolhas que, de outra forma, desapareceriam no histórico de chat.

Para a maioria das funcionalidades em um projeto solo, SPEC.md na raiz do repositório é suficiente. Alcance a estrutura de três arquivos quando uma funcionalidade toca a camada de banco de dados, um contrato de API e um componente de UI no mesmo build. Alcance os ADRs quando uma escolha é arquitetural e consequente: seleção de fila de eventos, estratégia de autenticação, camada de cache, esquema de versionamento de API.

O que Isso Muda

A taxa de 33% na primeira tentativa sem orientação não é uma limitação do modelo. Reflete o tamanho do espaço de decisão que o Claude navega sem restrições. Uma spec não torna o Claude mais inteligente. Torna o problema menor. Você toma as 20 decisões antecipadamente. O Claude executa contra um plano onde as decisões já estão resolvidas.

Spec primeiro. Sessão separada. Documento vivo. Esse é o padrão.

Perguntas Frequentes

O que é desenvolvimento orientado por spec com Claude Code?

Desenvolvimento orientado por spec é um fluxo de trabalho em quatro fases onde você escreve requisitos, design e uma lista de tarefas ordenada antes de o Claude escrever uma única linha de código. A spec remove as 20 ou mais decisões que o Claude, de outra forma, tomaria por conta própria. Você as toma antecipadamente. O Claude executa contra um plano que já está resolvido.

Como eu escrevo uma spec para Claude Code?

Abra uma sessão nova e peça ao Claude para te entrevistar usando a ferramenta AskUserQuestion até cobrir implementação, UX, casos de borda e trade-offs. Quando a entrevista terminar, peça para escrever o resultado em SPEC.md. Feche a sessão. A próxima sessão abre a spec e constrói. A transição entre sessões é onde mora a maior parte do valor.

Por que devo iniciar uma sessão nova depois de escrever uma spec?

O Claude carrega o raciocínio da sessão de criação da spec como suposições implícitas. Ele para de ler a spec literalmente e começa a preencher lacunas a partir da memória. Uma sessão nova o força a ler a spec como um engenheiro novo faria: do início, palavra por palavra, sem contexto herdado da conversa anterior.

O que vai em um arquivo de spec do Claude Code?

Uma spec mínima tem três partes: requisitos (o que a funcionalidade deve fazer, escrito como histórias de usuário e critérios de aceitação), design (modelos de dados, contratos de API, quais arquivos mudam) e tarefas (um plano de implementação ordenado onde cada passo lista suas dependências). Para funcionalidades pequenas, um único SPEC.md funciona. Funcionalidades maiores usam três arquivos separados dentro de uma pasta nomeada em .claude/specs/.

Qual é a diferença entre desenvolvimento orientado por spec e vibe coding?

Vibe coding significa promtar o Claude iterativamente e aceitar para onde a conversa levar. É rápido para exploração, mas imprevisível em escala. O desenvolvimento orientado por spec antecipa a tomada de decisão em um documento escrito antes de qualquer código rodar. A spec troca uma pequena quantidade de tempo inicial por uma grande redução em retrabalho, deriva de escopo e perda de contexto entre sessões.

Qual é a regra de corrigir o teste no desenvolvimento orientado por spec?

Sem uma restrição escrita, o Claude às vezes faz um teste com falha passar mudando o teste em vez de corrigir o código quebrado. A regra de corrigir o teste vai em SPEC.md ou CLAUDE.md: sempre encontre a causa raiz primeiro, corrija a aplicação se a aplicação estiver errada, corrija o teste apenas se o teste em si foi escrito incorretamente. Essa única regra fecha um dos modos de falha mais comuns em sessões sem orientação.