IA implementou diferente da spec: como achar a causa e corrigir a especificação

Fala aí, beleza? Tu escreve a spec, roda o agente, abre o diff e não é aquilo

A feature funciona, o código até que tá bonito, mas ela faz outra coisa

A reação automática é abrir o arquivo e ajustar na mão, resmungando que o modelo é burro

Só que na maioria das vezes que a IA implementa diferente da spec, o modelo fez exatamente o que estava escrito, e o que estava escrito não era o que tu queria

Esse post é um diagnóstico: reverter primeiro, classificar a causa em três famílias, e corrigir a ESPECIFICAÇÃO em vez do código

Porque se tu corrige só o diff, na próxima rodada o mesmo desvio volta, e aí tu corrige de novo, e de novo, e por aí vai

Antes de diagnosticar: desfaça a implementação divergente

Sintoma: o agente já mexeu em vários arquivos, tu tá com o dedo coçando pra sair arrumando linha por linha

Causa: cada correção manual apaga a evidência

Depois que tu ajusta o código na mão, não dá mais pra olhar o resultado e perguntar "que parte do meu texto produziu isso?"

A implementação divergente é a única prova que tu tem de onde a spec falhou, se liga nisso

Solução: volta pro estado anterior antes de qualquer coisa

O Claude Code salva checkpoints do estado do código antes de cada alteração, então dá pra desfazer sem depender de commit

O passo a passo:

1. Pressione Esc duas vezes, ou rode /rewind, pra abrir o menu de rewind
2. Escolha o ponto da conversa pro qual você quer voltar
3. Escolha o que restaurar: Restore code, Restore conversation, Restore code and conversation ou Never mind pra sair sem mudar nada

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

O erro comum deste passo: procurar a opção de restaurar código e não achar

Ela só aparece quando o checkpoint selecionado tem alterações de arquivo rastreadas

Se o checkpoint não mexeu em arquivo nenhum, não tem código pra devolver

Outro detalhe que vale saber antes de confiar cegamente: o checkpointing não reverte symlink nem hard link

Eles são pulados e você recebe um aviso do tipo Restored the code, but skipped N files

Então se o teu projeto tem link simbólico apontando pra fora, confere esses na mão

E tem um efeito colateral MUITO útil aqui: depois de restaurar a conversa, o prompt original daquela mensagem volta pro campo de entrada

Ou seja, o texto que gerou o desvio fica ali na tua frente, pronto pra editar e reenviar

É literalmente a spec com o defeito exposta pra correção 😀

Causa 1: ambiguidade no texto da spec

Sintoma: você lê o que foi entregue e pensa "tá, dá pra entender assim, mas não é isso"

A implementação é uma leitura defensável do teu texto

Só que não a leitura que tu tinha na cabeça

Causa: tem uma frase que aceita duas interpretações e o modelo escolheu uma

Clássico: "o usuário só pode curtir uma vez"

Uma vez por post? Uma vez por dia? Uma vez e não pode descurtir?

Você sabe qual é, o texto não sabe

Solução: reescrever o trecho ambíguo e, melhor ainda, usar clarificação estruturada em vez de confiar na tua releitura

O Spec Kit, toolkit de Spec-Driven Development mantido pelo GitHub, tem um comando só pra isso

O /speckit.clarify existe pra resolver áreas subespecificadas da spec e é recomendado rodar ANTES do /speckit.plan

O que ele faz de bom: as perguntas direcionadas não morrem no chat

As respostas voltam pro arquivo, numa seção de esclarecimentos (Clarifications) dentro de specs/<N>-<feature-name>/spec.md, e propagam pras seções relevantes

A decisão fica no documento, não na tua memória

Se tu quiser testar sem instalar nada permanente, dá pra rodar via uvx apontando pro repositório:

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

E pra escolher o agente na inicialização tem a flag de integração:

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME> --integration claude

Não quer adotar framework nenhum? Beleza, dá pra ficar só no Claude Code

O plan mode faz perguntas de esclarecimento antes de executar, então a ambiguidade aparece na conversa em vez de aparecer no diff

Como prevenir: nunca aprove uma spec que tem termo aceitando duas leituras

Lê cada requisito perguntando "se eu fosse de má fé, como eu implementaria isso?"

Se existe uma segunda resposta, o texto ainda não tá pronto

Causa 2: contexto faltando (o modelo não sabia da regra do projeto)

Sintoma: a feature tá certa em si, isolada ela passa

Mas ela viola a convenção da casa: usou outra lib, criou pasta fora do padrão, escreveu o teste no estilo errado, ignorou o wrapper que TODO mundo no projeto usa

Causa: essa regra existe na tua cabeça e no código, mas não existe em nenhum texto que o agente lê

E aqui vai a parte chata: o modelo não vai adivinhar convenção implícita

Se a regra nunca foi escrita, ela não é regra, é folclore do time

Solução: instrução persistente em arquivo, não em mensagem de chat

No Claude Code, o CLAUDE.md é o arquivo markdown de instruções persistentes lido no início de cada sessão

E ele vive em três níveis, cada um com um propósito:

Tem também a auto memory, em que o próprio Claude Code grava notas entre sessões

Ela vem ligada por padrão e o toggle fica no comando /memory, gravado como autoMemoryEnabled no ~/.claude/settings.json

Como prevenir: regra simples e que muda o jogo

Toda correção que tu digitou DUAS vezes vira linha no CLAUDE.md

Se tu se pegou escrevendo "usa o nosso client HTTP, não fetch cru" pela segunda vez, para tudo e escreve isso no arquivo

Corrigir no chat conserta uma rodada, corrigir no arquivo conserta todas as próximas

Causa 3: escopo grande demais para uma rodada

Sintoma: os três primeiros itens saíram redondinhos e do quarto em diante degradou

Ou pior: apareceu coisa que tu não pediu, tipo uma tela de admin que ninguém encomendou

Causa: a spec pediu coisa demais de uma vez, sem fatiamento

Quando o pedido é gigante, o modelo preenche os buracos sozinho pra conseguir fechar o pacote

E ele preenche com o que é estatisticamente comum, não com o que o TEU projeto precisa

Solução: três movimentos, na ordem

1. Separe o o quê / por quê das escolhas técnicas

No fluxo do Spec Kit isso é explícito: o /speckit.specify descreve o que a funcionalidade faz e por quê, sem stack, e as escolhas de stack e arquitetura entram no /speckit.plan

O erro comum deste passo: enfiar "usando Postgres e Redis" no meio do requisito de negócio

Aí não dá mais pra saber se o desvio foi de entendimento do problema ou de decisão técnica

2. Quebre em entregas menores, uma rodada por recorte

3. Revise a lista de tarefas ANTES de mandar implementar

Os comandos centrais do Spec Kit são /speckit.constitution, /speckit.specify, /speckit.clarify, /speckit.plan, /speckit.checklist, /speckit.tasks, /speckit.analyze, /speckit.implement e /speckit.converge

Repara que tasks vem antes de implement por um motivo: a lista de tarefas é a última chance barata de discordar

Depois dela, discordar custa código jogado fora

E tem um custo prático que ninguém comenta: rodada grande refeita várias vezes queima teu limite de uso rapidinho

Quem roda com plano gratuito conhece bem essa dor, é o mesmo aperto de saber os limites do plano grátis do Kimi K3 antes de bater a parede

Spec menor não é só qualidade, é economia

Como prevenir: corte o MVP no menor recorte que ainda entrega valor de verdade

Se dá pra tirar uma tela e a coisa continua sendo a coisa, tira

Como saber se a spec corrigida está pronta antes de reimplementar

Sintoma: tu ajustou o texto, mas bateu aquele medo de rodar de novo e ver o MESMO desvio

Causa: correção pontual

Você consertou a frase que causou o problema, mas não checou se o plano e a lista de tarefas ainda concordam com a nova versão da spec

Documento que se contradiz produz implementação que se contradiz

Solução: análise de consistência entre os artefatos antes de implementar

O /speckit.analyze faz análise cross-artefato entre spec.md, plan.md e tasks.md, reportando conflitos, lacunas e ambiguidades

E ele é estritamente somente leitura: não edita arquivo nenhum, só produz o relatório e pode sugerir correções pra você aprovar

Isso é ótimo, porque a ferramenta não "resolve" o problema escondendo ele de você

A resposta prática pra pergunta do título é essa: a spec tá pronta pra reimplementar quando o relatório do analyze sai limpo, sem conflito, lacuna nem ambiguidade sobrando

Enquanto sobrar item no relatório, a recomendação oficial é rodar o analyze antes de implementar e, quando ele apontar problema, voltar no comando DONO daquele problema:

• problema de requisito, volta pro /speckit.specify ou /speckit.clarify
• problema de design, volta pro /speckit.plan
• problema na lista de tarefas, volta pro /speckit.tasks

Depois roda o /speckit.analyze de novo, e repete até o relatório sair limpo

Não tá usando Spec Kit? O Claude Code sozinho já te dá o essencial disso com o plan mode

Pra entrar nele, aperta Shift+Tab até a barra de status mostrar ⏸ plan mode on, ou já começa a sessão assim:

claude --permission-mode plan

Nesse modo o modelo lê arquivos e responde perguntas sem fazer alterações, e você sai aprovando o plano ou apertando Shift+Tab de novo

Ele faz perguntas de clarificação antes de executar e gera um plan.md que você pode editar antes da execução começar

E se ler no terminal te incomoda, Ctrl+G abre o plano no editor de texto pra edição direta

O erro comum deste passo: bater Enter no plano porque "pareceu ok"

Plano de 40 linhas lido na diagonal é plano não lido

Como prevenir: aprove o plano só depois de ler ele inteiro, do começo ao fim

Essa é a etapa mais barata do processo todo e é justamente a que todo mundo pula

O que aconteceu quando revisei o plano em vez do código

No vídeo eu montei um projeto de teste com um fluxo de spec-driven, e a parte mais reveladora não teve nada a ver com código

O fluxo me deu uma nota pro plano antes da revisão de escopo

Se não me engano foi 7, e a meta era chegar em 10

Aí veio a discussão de reduzir o escopo do MVP

A sugestão era manter 4 telas, com a alternativa oferecida de cortar pra 2 ou menos

Eu decidi manter as 4

Repara no que aconteceu ali: eu discuti nota, escopo e quantidade de tela ANTES de existir uma linha de código

O ponto de intervenção foi o documento, não o diff

Se eu tivesse deixado construir as 4 telas e só depois achasse que era muita coisa, o custo do corte seria código pronto indo pro lixo

E tem a parte que eu preciso confessar, porque é a mais importante: em várias aprovações eu fui clicando sem ler tudo, pra não travar o vídeo

Esse é EXATAMENTE o erro que anula o método inteiro

O valor só aparece se você lê e aprova de verdade o que foi planejado, não no automático

Se aprovar no automático, tu só trocou de lugar o problema: em vez de código zoado feito no modo 100% vibe coder, tu tem plano zoado aprovado no modo 100% vibe coder 😛

No vídeo acima dá pra ver a revisão do plano e a conversa de corte de escopo acontecendo ao vivo, com o interrogatório que o fluxo faz antes de deixar construir qualquer coisa

Conclusão

Quando a IA implementa diferente da spec, o diff é o sintoma, a spec é o paciente

Recapitulando o diagnóstico:

Na próxima vez que o diff não bater, faz nessa ordem

Primeiro Esc Esc ou /rewind pra desfazer e preservar a evidência

Depois classifica em qual das três caixas o desvio cai

Depois edita a spec, não o código

E só então roda de novo, de preferência com o plan mode ligado e o plano lido inteiro

Esse raciocínio de separar sintoma de causa vale pra praticamente qualquer ferramenta de IA, é o mesmo jeito de pensar que a gente usa quando o ChatGPT começa a travar do nada: tratar o que aparece na tela como pista, nunca como o problema em si

O modelo raramente é o gargalo

O gargalo quase sempre é a frase que tu escreveu achando que estava clara…

Até o próximo post!