O código saiu diferente da spec: como conferir aderência sem reler tudo?

Fala aí, beleza? Teve entrega, teve verde no CI, e mesmo assim tem uma coisa estranha ali no fundo

O código compila, passa nos testes e o diff parece certinho

Só que o agente resolveu um problema PARECIDO, não o que a spec pediu

Esse é o desvio silencioso: ele não quebra nada, não acusa erro e passa liso na revisão justamente porque tudo funciona. O que não funciona é o requisito

Aí bate a dúvida chata: como conferir aderência à spec sem reler tudo? Reler o diff inteiro não escala, e ler por cima deixa passar exatamente o desvio que não gera exceção nenhuma

A saída é parar de revisar por leitura e começar a revisar por mapeamento: requisito de um lado, trecho de código do outro, e uma pergunta explícita sobre o que ficou de fora. Se você quer entender a raiz do problema antes, dá uma olhada em por que a IA erra

Bora ver na prática?

O que você precisa antes de conferir

Aderência só é verificável contra algo estável

Se a sua "spec" é o prompt inicial que você digitou e foi ajustando no chat ao longo de duas horas, não tem o que comparar: o alvo se mexeu junto com a implementação

Então, o mínimo pra conferência funcionar:

• Uma spec escrita em arquivo, não na sua cabeça e nem no histórico da conversa. Pode ser um markdown simples no repo, o importante é ser um artefato que não muda enquanto o agente codifica
• Claude Code instalado, que é onde a conferência vai rodar
• Um CLAUDE.md no projeto, o arquivo markdown com instruções, convenções e contexto que o Claude Code carrega em toda sessão. É ali que moram as regras do projeto que a spec assume como dadas
• Spec Kit (opcional), se você quiser o fluxo de artefatos completo

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 que é o Spec Kit?

É um toolkit open source do GitHub pra Spec-Driven Development, mantido no repositório github/spec-kit, com uma CLI chamada specify, e funciona com o Claude Code

Se você conhece qualquer scaffolder de projeto, a ideia é semelhante: ele instala um conjunto de comandos e templates no seu repo, e esses comandos organizam spec, plano e tarefas em arquivos separados

A instalação já aponta o agente na inicialização:

specify init meu-projeto --integration claude
specify version

O specify version serve como checagem local de versão e sanidade do runtime, ou seja, se ele responde, o básico tá de pé

Dá pra rodar one-shot também, sem instalar nada permanente:

uvx --from git+https://github.com/github/spec-kit.git specify init meu-projeto --integration claude

Tome cuidado: se a CLI do agente não estiver instalada na máquina, a inicialização pode barrar. Pra esse caso existe a flag --ignore-agent-tools:

specify init meu-projeto --integration claude --ignore-agent-tools

O Spec Kit ainda usa um constitution.md, que guarda os princípios não negociáveis do projeto. É o tipo de regra que você não quer repetir em toda spec

Passo a passo: conferir a entrega item a item

A lógica do fluxo é simples: transformar "revisar" em "cruzar"

Você não lê o código procurando erro, você percorre a lista de requisitos e cobra prova de cada um

1. Quebre a spec em itens numerados e verificáveis, um requisito por linha, cada um com um identificador (SPEC-01, SPEC-02, por aí vai). Requisito que não dá pra apontar num trecho de código não é requisito, é desejo. E feche as ambiguidades ANTES de codar: no Spec Kit, o /speckit.clarify faz até cinco perguntas dirigidas por rodada sobre áreas subespecificadas da spec atual e grava as respostas de volta no spec.md, e você pode rodar quantas vezes precisar antes do planejamento.

O erro comum deste passo: escrever requisito guarda-chuva do tipo "o sistema deve tratar erros corretamente". Não tem como conferir aderência a isso, cada implementação atende e não atende ao mesmo tempo

2. Peça a tabela de rastreio, sem deixar ele escrever mais uma linha de código:

   Para cada item numerado da spec (SPEC-01 até SPEC-12), devolva uma tabela com:
   item | arquivo:linha | trecho que atende | status (atende / parcial / não atende)

   Não implemente nada agora, só o mapeamento
   Se um item não tiver trecho correspondente, marque "não atende" em vez de justificar

O erro comum deste passo: aceitar resposta em prosa. Sem arquivo e linha na tabela, o agente descreve a intenção dele, não o código que existe

3. Peça o inverso, que é onde o desvio silencioso realmente aparece:

   Agora o contrário: liste o que da spec NÃO foi implementado e o que foi
   implementado SEM estar na spec
   Para cada desvio, diga o que você assumiu no lugar e por que desviou

Essa pergunta é a mais importante do fluxo todo. A tabela do passo anterior mostra o que foi feito, e o que foi feito sempre parece razoável. O buraco mora no que ficou de fora e no que apareceu sem pedido. Quando você encontra o desvio, vale corrigir a especificação também, senão ele volta na próxima rodada

O erro comum deste passo: perguntar "tá tudo certo?". Pergunta fechada convida a resposta confirmatória, pergunta pelo que faltou obriga a listar

4. Rode a checagem de consistência cruzada entre os artefatos, se você usa o Spec Kit:

   /speckit.analyze

Ele cruza spec.md, plan.md e tasks.md e reporta conflitos, lacunas e ambiguidades, tipo uma tarefa que não tem requisito correspondente ou uma escolha do plano que contradiz a spec. E o melhor: é estritamente somente leitura, não modifica arquivo nenhum. A saída é um relatório estruturado, com um plano de remediação opcional que só avança com aprovação explícita sua

O erro comum deste passo: rodar cedo demais. O /speckit.analyze só deve rodar depois que o /speckit.tasks produziu um tasks.md completo, e antes do /speckit.implement

5. Delegue a conferência a um subagente, pra leitura pesada não entupir a sessão principal. Cada subagente do Claude Code roda na própria janela de contexto, com system prompt próprio, ferramentas específicas e permissões independentes: as chamadas intermediárias ficam lá dentro e só a mensagem final volta pro agente pai. Ou seja, o veredito chega limpo, sem os quarenta Read no meio. Subagente é arquivo Markdown com frontmatter YAML em .claude/agents/ (projeto) ou ~/.claude/agents/ (pessoal):

   ---
   name: conferente-de-spec
   description: Cruza a entrega com a spec item a item e devolve só o veredito
   tools: Read, Grep, Glob
   ---

   Você confere aderência à spec, não escreve código

   Para cada item numerado da spec, aponte arquivo e linha do trecho que atende
   Marque "não atende" sempre que não encontrar trecho correspondente
   Feche com duas listas: itens da spec sem implementação, e implementações sem item na spec

O Claude Code observa essas pastas e detecta a criação ou edição do arquivo em poucos segundos, sem reiniciar nada: a próxima delegação já usa a definição atualizada. Massa demais

O erro comum deste passo: procurar painel interativo pra criar o subagente. A partir da versão v2.1.198 do Claude Code, o /agents não abre mais o assistente de criação, ele só imprime um aviso apontando os locais dos arquivos. A criação hoje é pedindo ao Claude ou editando o arquivo direto

6. Use o plan mode antes de mandar corrigir, porque corrigir desvio sem ver a proposta é trocar um problema por outro. No plan mode o Claude pesquisa e propõe as mudanças sem executar: as edições ficam bloqueadas até o plano ser aprovado (exceto em sessões com bypass de permissões). Ele ativa de três jeitos:

   # 1) Shift+Tab até a status bar mostrar "⏸ plan mode on"
   # 2) prefixando um único prompt com /plan
   # 3) já na abertura da sessão:
   claude --permission-mode plan

Quando o plano fica pronto, ele apresenta e pergunta como prosseguir: aprovar e executar, continuar planejando com feedback, ou sair do plan mode. Esse gate é a sua chance de perceber que a "correção" ia refatorar meio módulo

O erro comum deste passo: aprovar no automático porque o plano é longo. O gate só vale se você ler

7. Se a correção piorar, volte pelo checkpoint. O Claude Code cria um checkpoint a cada prompt enviado, e o menu de rewind abre com Esc duas vezes ou com o comando /rewind. Lá dá pra restaurar só a conversa, só o código, ou os dois. As opções de restaurar código só aparecem quando o checkpoint selecionado tem mudanças de arquivo rastreadas. E como os checkpoints são salvos junto com a conversa, você pode fechar o terminal, retomar a sessão depois e ainda assim voltar atrás

O erro comum deste passo: achar que o checkpoint cobre tudo. Ele só rastreia mudanças feitas pelas ferramentas de edição de arquivo do Claude: o que saiu de comando Bash ou de processo externo (migration rodada na mão, script de codemod, os rm -rf da vida) NÃO é capturado. Já viu o filme, né?

Os tipos de desvio silencioso que essa conferência pega

Todo desvio silencioso tem a mesma assinatura: o código roda

Por isso teste verde não é prova de aderência, é prova de que nada explodiu

Os quatro que mais aparecem:

• Requisito resolvido em outro lugar do sistema. A regra existe, mas foi parar numa camada diferente da que a spec definiu. Funciona hoje, e quebra a arquitetura amanhã
• Semântica parecida, mas diferente. A spec pedia "bloquear", o código faz "ocultar". A spec pedia "por usuário", o código faz "por sessão". O comportamento visível é quase igual… até o caso de borda aparecer
• Item difícil descartado no silêncio. O agente encontrou um requisito espinhoso, seguiu o resto e simplesmente não voltou. Ninguém é avisado, porque ele não falhou, ele pulou
• Trabalho extra que ninguém pediu. Cache, retry, abstração, um helper genérico lindão. Não estava na spec, e agora é código que você mantém sem ter decidido manter

Cada um cai numa peneira diferente do fluxo:

Repara numa coisa: nenhuma dessas peneiras é "ler o diff com atenção" 🙂

Atenção é recurso escasso e o desvio silencioso foi desenhado (sem querer) pra escapar dela

Conclusão

Aderência não se confere relendo, se confere por artefato e mapeamento

Spec escrita em itens numerados, tabela de rastreio item por item, a pergunta explícita pelo que ficou de fora e pelo que veio a mais, e a checagem cruzada entre os artefatos quando o fluxo permite

O próximo passo é bem concreto: no seu próximo recorte de trabalho, escreva a spec em itens numerados antes de abrir o Claude Code

Depois transforme a conferência em rotina, pra não depender de você lembrar o prompt certo às onze da noite. Dá pra guardar como skill em .claude/skills/<nome>/SKILL.md, que é o formato recomendado hoje e ainda pode ser acionado sozinho pelo Claude, ou no formato legado em .claude/commands/, que continua funcionando (um .claude/commands/deploy.md cria o /deploy igualzinho a uma skill em .claude/skills/deploy/SKILL.md)

Ou, se você já foi de Spec-Driven Development, deixa o fluxo do Spec Kit fazer esse trabalho por você

O agente vai continuar desviando de vez em quando… a diferença é que agora ele te conta onde

até o próximo post!