Aprenda a usar Claude Code para detectar deriva de documentação e manter READMEs, docs de API e runbooks alinhados ao código, gerando diffs e apontando contradições.
Deriva de documentação é a separação gradual entre o que seus docs dizem e o que o código realmente faz. Começa como pequenas discrepâncias e vira aquela confusão de “juramos que isso funcionava mês passado”.
Num time real, a deriva aparece assim: o README diz que você roda um serviço com um comando, mas agora é preciso uma variável de ambiente nova. Os docs da API mostram um endpoint com um campo que foi renomeado. Um runbook manda o on-call reiniciar o “worker-a”, mas o processo agora foi dividido em dois serviços.
A deriva acontece mesmo com boas intenções porque software muda mais rápido que hábitos de documentação. Pessoas fazem correções sob pressão, copiam exemplos antigos ou assumem que outra pessoa atualizará os docs depois. Também cresce quando há muitos lugares que parecem "fonte da verdade": READMEs, referências de API, páginas internas da wiki, tickets e conhecimento tribal.
Os custos são concretos:
Ajustar a escrita não resolve deriva se os fatos estão errados. O que ajuda é tratar docs como algo que você pode verificar: compare-os com o código atual, configs e saídas reais, e então aponte contradições onde o doc promete um comportamento que o código não tem mais.
Deriva costuma aparecer em documentos que as pessoas tratam como “referência rápida”. Eles são atualizados uma vez e o código continua evoluindo. Comece com esses três porque contêm promessas concretas que você pode checar.
READMEs derivam quando comandos do dia a dia mudam. Uma flag nova é adicionada, uma antiga é removida, ou uma variável de ambiente é renomeada, mas a seção de setup ainda mostra a realidade antiga. Novos colegas copiam e colam instruções, encontram erros e assumem que o projeto está quebrado.
A pior versão é “quase certo”. Uma variável de ambiente faltando pode desperdiçar mais tempo do que um README totalmente desatualizado, porque as pessoas continuam tentando pequenas variações em vez de questionar o doc.
Docs de API derivam quando campos de request ou response mudam. Mesmo pequenas mudanças (chaves renomeadas, defaults diferentes, headers agora obrigatórios) podem quebrar clientes. Frequentemente a lista de endpoints está correta enquanto os exemplos estão errados — e é exatamente isso que os usuários copiam.
Sinais típicos:
Runbooks derivam quando passos de deploy, rollback ou operacionais mudam. Um comando desatualizado, nome de serviço errado ou pré-requisito ausente pode transformar um conserto rotineiro em downtime.
Também podem ser “precisos, mas incompletos”: os passos ainda funcionam, mas pulam uma migration nova, um clear de cache ou um toggle de feature flag. É quando os respondedores seguem o runbook perfeitamente e ainda ficam surpresos.
Claude Code para deriva de documentação funciona melhor quando você trata docs como código: proponha um patch pequeno e revisável e explique o porquê. Em vez de pedir para “atualizar o README”, peça que gere um diff contra arquivos específicos. Revisores recebem um claro antes/depois e podem identificar mudanças indesejadas rapidamente.
Uma boa checagem de deriva produz duas coisas:
Quando você manda um prompt, exija prova vinda do repo: caminhos de arquivos e detalhes como rotas, valores de config ou testes que demonstrem o comportamento atual.
Aqui está um padrão de prompt que mantém tudo ancorado:
Check these docs for drift: README.md, docs/api.md, runbooks/deploy.md.
Compare them to the current repo.
Output:
1) Contradictions list (doc claim -> repo evidence with file path and line range)
2) Unified diffs for the smallest safe edits
Rules: do not rewrite sections that are still accurate.
Se Claude disser "a API usa /v2", peça que comprove apontando para o router, spec OpenAPI ou um teste de integração. Se não encontrar evidência, deve dizer isso.
Deriva geralmente começa com uma mudança de código que afeta silenciosamente múltiplos docs. Faça o Claude mapear o impacto primeiro: o que mudou, onde mudou, quais docs provavelmente quebraram e quais ações de usuário são afetadas.
Exemplo: você renomeia uma variável de ambiente de API_KEY para SERVICE_TOKEN. Um relatório útil encontra todos os lugares onde o nome antigo aparece (setup do README, exemplos da API, seção de segredos do runbook) e produz um diff enxuto que corrige apenas essas linhas e quaisquer comandos de exemplo que agora falhariam.
Se você apontar um modelo para “todos os docs” sem regras, frequentemente recebe reescritas que ainda contêm fatos errados. Um workflow simples mantém mudanças pequenas, repetíveis e fáceis de revisar.
Comece com um conjunto de docs: o README, a referência de API ou um runbook que as pessoas realmente usam. Corrigir uma área de ponta a ponta ensina quais sinais confiar antes de escalar.
Escreva, em termos simples, de onde os fatos devem vir para aquele conjunto de docs.
Uma vez nomeadas essas fontes, os prompts ficam mais precisos: "Compare o README com a saída atual do CLI e os defaults de config, então gere um patch."
Concorde um formato antes de rodar a primeira checagem. Misturar formatos dificulta ver o que mudou e por quê.
Uma regra simples:
Um hábito prático: adicione uma pequena nota a cada PR de docs tipo "Fonte da verdade verificada: routes + tests" para que revisores saibam o que foi comparado. Isso transforma atualizações de docs de "parece ok" para "verificado contra algo real".
Trate cada mudança de código como uma investigação curta de docs. O objetivo é pegar contradições cedo e produzir um patch mínimo que os revisores possam confiar.
Comece escolhendo os arquivos exatos a checar e uma pergunta de deriva clara. Por exemplo: "Mudamos alguma variável de ambiente, flag de CLI, rota HTTP ou código de erro que os docs ainda mencionam?" Ser específico evita que o modelo reescreva seções inteiras.
Em seguida, peça que Claude Code extraia fatos concretos do código primeiro. Peça uma lista só com itens concretos: comandos que usuários executam, endpoints e métodos, campos de request e response, chaves de config, variáveis de ambiente obrigatórias e passos operacionais referenciados por scripts ou configs. Se algo não for encontrado no código, deve dizer "not found" em vez de adivinhar.
Depois, peça uma tabela simples de comparação: afirmação do doc, o que o código mostra e um status (match, mismatch, missing, unclear). Isso mantém a discussão ancorada.
Então solicite um diff unificado com edições mínimas. Diga para mudar apenas as linhas necessárias para resolver mismatches, manter o estilo do doc e evitar promessas que não têm suporte no código.
Finalize com um resumo curto para o revisor: o que mudou, por que mudou e o que checar (como uma variável renomeada ou um header novo obrigatório).
Docs de API derivam quando o código muda silenciosamente: uma rota é renomeada, um campo vira obrigatório ou a forma de erro muda. O resultado são integrações quebradas e tempo perdido em debugging.
Com Claude Code para deriva de documentação, a tarefa é provar o que a API faz a partir do repo e então apontar divergências nos docs. Peça para extrair um inventário do routing e handlers (paths, métodos, modelos de request e response) e comparar com o que a referência de API afirma.
Foque no que as pessoas realmente copiam: comandos curl, headers, payloads de exemplo, códigos de status e nomes de campos. Em um único prompt, faça checar:
Quando encontrar um mismatch, aceite apenas diffs que citem evidência do código (a definição exata de rota, comportamento do handler ou schema). Isso mantém patches pequenos e revisáveis.
Exemplo: o código agora retorna 201 em POST /widgets e adicionou um campo name obrigatório. Os docs ainda mostram 200 e omitem name. Uma boa saída aponta as duas contradições e atualiza só o status e o JSON de exemplo daquele endpoint, deixando o resto intacto.
Runbooks falham da forma mais cara: parecem completos, mas os passos não correspondem ao que o sistema faz hoje. Uma pequena mudança como renomear uma variável de ambiente ou um comando de deploy novo pode alongar um incidente porque os respondedores seguem instruções que não funcionam.
Trate runbook como código: peça um diff contra o repo atual e exija chamadas de contradição. Compare com o que o sistema usa agora: scripts, defaults de config e sua ferramenta atual.
Foque nos pontos de falha que mais causam retrabalho em incidentes:
Também adicione pré-checagens rápidas e saídas esperadas para que os respondedores saibam se estão no caminho certo. "Verificar que funciona" não basta; inclua o sinal exato esperado (uma linha de status, uma string de versão ou a resposta de um health check).
Se você builda e deploya apps em plataformas como Koder.ai, isso importa ainda mais porque snapshots e rollback só são úteis quando o runbook aponta a ação correta e reflete o caminho real de recuperação.
A forma mais rápida de criar deriva é tratar docs como "boa redação" em vez de um conjunto de afirmações que devem coincidir com o código.
Um passo em falso comum é pedir primeiro uma reescrita. Quando você pula a checagem de contradições, pode acabar com uma redação mais suave que ainda descreve o comportamento errado. Sempre comece perguntando o que o doc afirma, o que o código faz e onde discordam.
Outro erro é deixar o modelo chutar. Se um comportamento não é visível no código, testes ou configs, trate como desconhecido. "Provavelmente" é como promessas aparecem no README e runbooks viram ficção.
Esses problemas aparecem muito nas atualizações do dia a dia:
Um handler passa de 401 para 403 para tokens expirados, e o nome do header muda de X-Token para Authorization. Se você apenas reescrever a seção de auth, pode perder que o exemplo da API ainda mostra o header antigo, e o runbook ainda pede para on-call olhar picos de 401.
Ao gerar diffs, adicione uma linha de decisão curta tipo: "Falhas de auth agora retornam 403 para distinguir credenciais inválidas de ausentes." Isso evita que a próxima pessoa "conserte" os docs de volta para o comportamento antigo.
Trate toda atualização de docs como uma pequena auditoria. O objetivo é menos surpresas quando alguém seguir as instruções na semana seguinte.
Antes de dar merge, percorra README, docs de API e runbook procurando por afirmações concretas e verifique uma a uma:
Se encontrar duas ou mais afirmações desconhecidas no mesmo doc, pause o merge. Ou adicione evidência (caminhos de arquivo e nomes de funções) ou reduza o doc ao que for certo.
Um time muda a auth: em vez de enviar uma API key como X-API-Key, clientes agora enviam um token de curta duração em Authorization: Bearer <token>. O código é lançado, testes passam e o time segue.
Dois dias depois, um novo desenvolvedor segue o README. Ele ainda diz "defina X-API-Key na sua variável de ambiente" e mostra um curl com o header antigo. Não consegue rodar localmente e assume que o serviço está fora.
Ao mesmo tempo, os docs da API estão desatualizados. Descrevem o header antigo e ainda mostram um campo de resposta user_id, embora a API agora retorne userId. Nada está errado com a escrita, mas contradiz o código, então leitores copiam a coisa errada.
Então vem um incidente. O on-call segue o passo do runbook "rotacione a API key e reinicie os workers". Isso não ajuda porque o problema real é verificação de token após uma mudança de config. O runbook os leva na direção errada por 20 minutos.
É aí que Claude Code para deriva é útil quando produz diffs e chamadas de contradição, não uma reescrita completa. Você pode pedir para comparar o middleware de auth e handlers contra trechos do README, exemplos de API e passos do runbook, e então propor patches mínimos:
- Header: X-API-Key: <key>
+ Header: Authorization: Bearer <token>
- { "user_id": "..." }
+ { "userId": "..." }
A parte importante é que ele marca os mismatches, aponta os locais exatos e muda só o que o repo comprova estar desatualizado.
A documentação permanece precisa quando checá-la é chato e repetível. Escolha uma cadência que combine com o quão arriscadas são suas mudanças. Para código que muda rápido, faça isso em cada PR. Para serviços estáveis, um sweep semanal mais uma checagem pré-release costuma bastar.
Trate deriva de docs como uma falha de teste, não uma tarefa de redação. Use Claude Code para gerar um diff pequeno e uma lista curta de contradições, então corrija o menor ponto que torne os docs verdadeiros novamente.
Uma rotina leve que funcione:
Torne esses resumos de diff fáceis de achar depois. Uma nota curta como "Docs atualizados para refletir novo endpoint /v2, header obsoleto removido, resposta de exemplo atualizada" ajuda quando alguém pergunta meses depois por que um doc mudou.
Aplique o pensamento de "snapshots e rollback" também aos docs. Se uma instrução é incerta, mude-a em um lugar, verifique rápido e então copie a versão confirmada para os outros lugares.
Se você está construindo rápido, pode ajudar gerar o app e uma primeira versão da documentação juntos em Koder.ai (koder.ai), depois exportar o código-fonte e manter as mudanças revisáveis no seu fluxo normal. O objetivo não é prosa perfeita. É manter o que as pessoas fazem (comandos, endpoints, passos) alinhado com o que o código realmente faz.
A deriva de documentação é quando seus docs deixam de corresponder ao que o código realmente faz. Normalmente começa com pequenas mudanças (uma variável de ambiente renomeada, um campo agora obrigatório, um código de status diferente) que nunca são refletidas no README, exemplos de API ou runbooks.
Porque o código muda sob pressão e a documentação não recebe a mesma disciplina.
Causas comuns:
Comece pelos documentos que as pessoas realmente executam, não pelos que são “bons de ter”. Uma ordem prática é:
Corrigir esses primeiro remove as falhas de maior custo.
Porque um texto polido ainda pode estar errado. A deriva é, em grande parte, sobre afirmações incorretas.
Uma abordagem melhor é tratar docs como declarações testáveis: “execute este comando”, “chame este endpoint”, “defina esta variável”, e então verificar essas afirmações contra o repositório atual, configs e saídas reais.
Peça dois resultados:
Também exija: se não encontrar evidência no repo, deve dizer “não encontrado” em vez de chutar.
Porque revisores validam diffs rapidamente. Um diff mostra exatamente o que mudou e desencoraja reescritas “úteis” que introduzem novas promessas.
Um bom padrão é: um arquivo por diff quando possível, e cada mudança tem uma frase curta justificando-a ligada à evidência no repo.
Exija que comprove com evidências.
Regras práticas:
Verifique as partes que as pessoas copiam e colam:
Se a lista de endpoints estiver certa mas os exemplos estiverem errados, os usuários ainda falham — trate exemplos como alta prioridade.
Runbooks derivam quando a realidade operacional muda.
Checagens de alto impacto:
Se os respondedores não conseguem verificar progresso, vão perder tempo durante incidentes.
Use uma regra simples de “fonte de verdade” por tipo de doc:
Depois incorpore ao fluxo: rode checagens de deriva nos docs afetados por PR, e mantenha edições pequenas e revisáveis.