A 4ª falha de Spec-Driven Development com Claude Code (post-mortem de 6 semanas)

Três meses atrás eu publiquei 3 falhas de Spec-Driven Development com Claude Code e achei que tinha fechado a conta. Ambiguidade no spec. Confiança em código gerado sem revisar. Requisitos que o agente inventa. Três, contadas, catalogadas.

Aí veio uma quarta. Ela não apareceu no primeiro sprint, nem no segundo. Ela apareceu no sexto. Silenciosa, sem log de erro, sem alerta. E derrubou 40% dos PRs de um sprint inteiro antes de eu descobrir que estava acontecendo.

Este post é o post-mortem dessas 6 semanas. Se você está rodando Claude Code em produção há mais de um mês, provavelmente já tem esse bug rodando no seu time. A diferença é que ninguém ainda mediu.

O que estava acontecendo (e como eu não vi)

O time adotou spec-driven de verdade depois do post anterior. Todo endpoint tinha um spec.md versionado no repositório. OpenAPI para o formato, Gherkin para os cenários, uma seção ## Out of scope para amarrar o que o agente não deveria inventar. O CLAUDE.md do projeto crescera para 340 linhas com convenções de código, regras de PR, política de review.

Semana 1: 91% dos PRs gerados pelo Claude Code passaram no CI na primeira tentativa. Achei que tinha resolvido o problema para sempre.

Semana 3: 84%. Ainda bom.

Semana 5: 72%. Comecei a estranhar, mas atribuí a “features novas mais complicadas”.

Semana 6: 51%. Aí eu parei tudo.

A queda não veio de um deploy. Não veio de uma feature mais difícil. Não veio de um bug no Claude Code (embora a Anthropic tenha admitido bugs no mesmo período — mais sobre isso adiante). Veio de uma coisa que ninguém no time estava medindo: o agente parou de ler os specs.

Não integralmente. Só o suficiente para não perceber.

A 4ª falha: spec drift silencioso

As três falhas do post anterior partiam de um pressuposto que hoje eu sei ser ingênuo: se o spec está no repositório, o agente vai olhar para ele. Passa a olhar. Continua olhando. Vai continuar olhando.

Spec drift silencioso é o processo em que o agente vai gradualmente parando de referenciar o spec, mesmo quando o arquivo está lá, o CLAUDE.md aponta para ele, e você acha que o fluxo está estável. O código continua sendo gerado. Os testes continuam sendo escritos. O PR continua tendo boa cara. Só que a fidelidade ao spec vai caindo, semana a semana, sem sinal externo.

A Anthropic documentou três modos concorrentes de drift num relatório recente: regras ignoradas durante a execução, regras esquecidas no meio da sessão à medida que o contexto enche de código, e regras puladas como se fossem “desnecessárias” (Jakub Kontra 2026). Um usuário reportou em março de 2026 que, com um CLAUDE.md de mais de 200 linhas, o próprio agente respondeu, quando confrontado: “eu simplesmente não sigo”.

Simplesmente não segue. Nenhum log. Nenhuma exceção. É o pior tipo de bug que existe, porque parece que está tudo funcionando.

Como o drift se manifestou em cada semana

Voltei aos PRs das 6 semanas e classifiquei cada falha. O padrão apareceu limpo demais para ser coincidência.

Semana	PR pass rate	Modo dominante de drift
1	91%	—
2	88%	ocasional (regra pulada como “desnecessária”)
3	84%	ocasional
4	78%	recorrente (regras esquecidas no meio da sessão)
5	72%	recorrente + estrutural (spec não referenciado)
6	51%	estrutural (o agente para de abrir o spec.md)

Nas semanas 5 e 6, olhei o log das sessões mais degradadas. O padrão era o mesmo: o Claude Code lia o CLAUDE.md, lia o arquivo de código, e pulava direto para escrever. O spec.md correspondente era mencionado no CLAUDE.md como referência obrigatória. O agente concordava por escrito e ignorava na prática.

Por que a semana 6 e não a semana 3

Duas coisas se acumularam.

A primeira é o crescimento do CLAUDE.md. No começo do projeto, o arquivo tinha 90 linhas. Cada aprendizado do time era um add de mais uma regra. Sem que ninguém percebesse, cruzamos as 300 linhas na semana 4. Pesquisas recentes mostram que arquivos CLAUDE.md longos degradam a aderência às instruções (Rick Hightower / Towards AI). O modelo lê tudo, mas o peso relativo de cada regra dilui.

A segunda é o histórico compactado. À medida que as sessões ficam mais longas, o Claude Code aplica compactação de contexto. Regras muito citadas na fase inicial acabam resumidas ou omitidas nas fases finais. Se você abre uma nova sessão por PR, esse problema é menor. Se você tem uma sessão longa acompanhando toda a feature, o drift compõe.

Eu tinha os dois: CLAUDE.md engordado e sessões de 4h+ por feature. Era só questão de tempo.

Alguém no time me perguntou, quando expliquei o padrão: “então basicamente o Claude ficou de saco cheio das nossas regras”. A frase é injusta com o modelo, mas descreve o efeito exatamente.

O que a Anthropic mudou (e por que ainda não basta)

Entre março e abril de 2026, a Anthropic rodou de fato três modos de degradação concorrentes no Claude Code. Um deles foi bug, dois foram decisões deliberadas de reduzir o esforço de raciocínio padrão de “high” para “medium” com o release do Opus 4.6 (TECHMANIACS 2026). Em julho de 2026 saiu o fix da quadratic slowdown que compunha nas sessões mais longas do auto mode (TechTimes 2026).

Essas mudanças ajudam. Mas nenhuma delas resolve o drift causado por CLAUDE.md longo + sessão longa. Isso é sua responsabilidade, não do modelo. O modelo é o motor. Você é quem dirige, e você é quem tem que parar para checar o pneu.

Como estou parando o drift agora

Depois das 6 semanas, mudei o fluxo em quatro pontos.

1. Auditoria semanal de CLAUDE.md. Toda segunda-feira, alguém do time abre o CLAUDE.md, lê linha por linha, e move para docs/decisions/ tudo que virou “decisão histórica” (não precisa mais entrar em toda sessão). O objetivo é manter o arquivo abaixo de 150 linhas, com regras vivas e acionáveis. Escolhi 150 baseado no que vi funcionar; não tem número mágico.

2. Sessão nova por PR. Cortei sessões longas. Cada PR abre uma sessão nova do Claude Code, com /clear explícito no começo. O custo em contexto é maior, mas o drift zera a cada PR. Vale.

3. Spec check obrigatório no prompt inicial. O primeiro prompt de toda sessão agora inclui, literal: “Antes de escrever qualquer código, leia spec.md e me confirme, em bullet points, quais requisitos você vai atender”. Se o agente pular esse passo, eu paro a sessão. Isso força o spec para dentro do contexto ativo, não só como referência.

4. Métrica de fidelidade ao spec no CI. Adicionei um script que, para cada PR, extrai as menções ao spec no diff (número de referências, testes que cobrem cenários listados no spec) e falha se cair abaixo de um piso. Não é sofisticado. É uma linha de defesa que grita antes de a fidelidade cair 40 pontos.

Duas semanas depois dessas mudanças, o PR pass rate voltou para 89%. Não é 91% da semana 1, mas está claramente longe dos 51%. Vou seguir medindo.

O que eu diria pro engenheiro que ainda não passou pela semana 6

Você provavelmente vai passar. O spec-driven funciona no começo. Ele continua funcionando, mas só se você tratar o CLAUDE.md como código com custo de manutenção, não como documentação que só cresce.

O que eu me arrependo profundamente é de não ter medido o PR pass rate desde a semana 1. Se eu tivesse o gráfico, teria visto a queda começando na semana 3 e agido na 4. Sem métrica, você só descobre quando o time inteiro começa a reclamar. Aí já são 6 semanas de dívida técnica silenciosa.

Se você adotou spec-driven no seu time, adiciona hoje uma métrica de aderência ao spec no seu CI. Duas linhas de shell. Vale mais do que qualquer skill nova.

E não confie em “está funcionando” como métrica. O drift funciona por parecer que está funcionando. Essa é justamente a característica que o torna caro.

Nota metodológica: os números vieram de um único time em um único projeto (backend de checkout, Flask + Postgres, 4 engenheiros). Não são benchmark. Se você reproduzir com times/stacks diferentes, me manda o gráfico — quero comparar a curva.

---

ken imoto · WebRTC & Voice AI engineer · kenimoto.dev · TabNews