Documentação desatualizada: dá para o Claude Code arrumar a partir do código?

Fala aí, beleza? Todo projeto com mais de um ano tem aquele README que descreve um software que não existe mais

O comando de setup mudou de nome, o módulo auth virou identity, tem um passo de configuração que ninguém roda desde sabe-se lá quando

E aí bate a pergunta: o agente lê o código inteiro, então ele consegue arrumar o texto sozinho, né?

A resposta honesta é: sim pra uma parte, não pra outra

Ele é MUITO bom em descrever o que está escrito no repositório

E é péssimo (ou pior: convincente e errado) naquilo que só vive na cabeça de quem tomou a decisão

Bora separar as duas coisas…

O que você precisa antes de pedir a atualização

Antes de sair mandando o agente reescrever arquivo, umas checagens rápidas que evitam dor de cabeça depois

• Abrir o Claude Code na pasta certa: os arquivos CLAUDE.md do diretório atual e dos diretórios acima dele são lidos no início da sessão e entregues logo depois do system prompt. Já o CLAUDE.md de subpasta carrega sob demanda, só quando o Claude lê arquivos daquela subpasta
• Decidir onde o arquivo vai morar: a raiz do repositório (compartilhado com o time), um diretório pai (o caso clássico de monorepo) ou a pasta home do usuário (vale pra todos os seus projetos)
• Windows nativo: a recomendação é instalar o Git for Windows pra que o Claude Code use a ferramenta Bash. Sem ele, o shell usado é o PowerShell, e aí todo comando de setup que ele sugerir vai sair com a sintaxe de outro mundo
• Git funcionando: o Claude Code trabalha direto com git, prepara mudanças no stage, escreve mensagem de commit, cria branch e abre pull request. É isso que te dá o diff pra revisar antes de aceitar qualquer texto

Um aviso que pega gente desprevenida: se o arquivo de memória do projeto tiver um import apontando pra fora do diretório de trabalho (tipo @~/.claude/minhas-instrucoes.md), isso é tratado como import externo

Na primeira vez o Claude Code abre um diálogo de aprovação listando os arquivos

Não é bug, é o comportamento esperado, só aprova e segue 🙂

O que o Claude Code consegue reescrever a partir do código e o que ele não tem como saber

Essa é a parte que decide se o post vira produtivo ou vira retrabalho

A régua é simples: o que está escrito no repositório ele descreve bem, o que não está ele PREENCHE, e preencher lacuna é exatamente onde nasce documentação bonita e falsa

Repara que a coluna da direita tem uma coisa em comum: nada ali está no código

Se o motivo de uma escolha só existe na conversa de um PR fechado há dois anos, e ninguém trouxe aquilo pra dentro de um arquivo do repositório, não tem de onde esse texto sair numa seção de "Decisões de arquitetura"

E o agente não deixa o espaço em branco, ele preenche com o que soa plausível

Quando o que você precisa é justamente digerir material que está FORA do código (documentação de terceiro, artigo, transcrição), aí o jogo é outro e vale usar o NotebookLM para ler documentação em vez de forçar o agente a adivinhar

Na parte das convenções tem uma sutileza: ele descreve o padrão que consegue enxergar lendo os arquivos, e isso é bem diferente de ele seguir esse padrão na hora de escrever código novo. Se o teu caso é fazer o agente respeitar o padrão daquele projeto, o CLAUDE.md é meio caminho, mas o assunto é maior que documentação

Passo a passo para atualizar a documentação com o Claude Code

Fluxo que vai do zero até o commit, com o erro comum de cada passo

1. Rode /init na raiz do projeto

/init

O /init analisa o projeto (arquivos de pacote, documentação existente, arquivos de configuração e estrutura de código) e gera um CLAUDE.md sob medida pra aquele repositório

E ele não serve só pra repo virgem: rodando em projeto que JÁ tem CLAUDE.md, o Claude revisa o arquivo atual e sugere melhorias com base no que descobre explorando o código

O erro comum deste passo: achar que o /init vai reescrever o teu README.md. A documentação oficial descreve o /init gerando CLAUDE.md, não README. Se você quer o README atualizado, isso é um pedido de edição normal que você faz depois, com escopo explícito

2. Entre no modo de planejamento ANTES de deixar ele escrever

Shift+Tab ou prefixando o prompt com /plan

No modo de planejamento as edições ficam bloqueadas até você aprovar o plano, e é exatamente isso que você quer quando o assunto é texto que outras pessoas vão ler como verdade

Ctrl+G abre o plano proposto no teu editor de texto padrão, dá pra editar direto ali

E Shift+Tab de novo sai do modo de planejamento, caso você tenha entrado sem querer

O erro comum deste passo: mandar "atualiza a documentação" no modo normal e voltar do café com dez arquivos alterados e nenhuma ideia de qual frase saiu de onde

3. Escolha como aprovar

Com o plano pronto, o Claude Code pergunta como prosseguir e oferece aprovar usando o modo automático, aprovar revisando cada edição manualmente ou continuar planejando

Pra documentação, revisar cada edição manualmente é o caminho chato e certo

O erro comum deste passo: escolher automático "porque é só texto". É só texto até alguém do time seguir uma instrução de setup inventada

4. Delimite o escopo do arquivo

Não existe formato obrigatório pro CLAUDE.md, a recomendação é mantê-lo conciso e legível por humanos

O conteúdo sugerido é: comandos de shell comuns, estilo de código, instruções de teste, convenções do repositório, setup do ambiente e avisos específicos do projeto

E a recomendação de tamanho é ficar abaixo de 200 linhas por CLAUDE.md, porque arquivo mais longo consome mais contexto e reduz a aderência às instruções

O erro comum deste passo: deixar o pedido aberto ("documenta o projeto") e receber um calhamaço que ninguém lê e que o próprio agente segue mal

5. Jogue a varredura longa pra um subagente

Subagentes customizados são arquivos markdown com frontmatter YAML em .claude/agents/ (do projeto, compartilhado com o time) ou ~/.claude/agents/ (do usuário)

O ponto forte aqui: o subagente roda em uma janela de contexto própria e só a mensagem final dele volta pra sessão principal, junto com metadados

Ou seja, ele pode ler meio repositório atrás de comandos reais e te devolver só o resumo, sem entupir a tua sessão

O erro comum deste passo: esperar que a sessão principal "lembre" do que o subagente leu no meio do caminho. Não lembra, só a mensagem final volta

6. Se o pedido é recorrente, vira skill

Skills ficam em ~/.claude/skills/ (pessoais, valem em todos os projetos) ou em .claude/skills/<nome>/SKILL.md (do projeto)

Todo SKILL.md precisa de frontmatter YAML entre marcadores --- com os campos obrigatórios name e description

---
name: revisar-docs
description: Revisa a documentação do projeto usando só o que está escrito no repositório
---

E aqui o detalhe que confunde bastante gente: .claude/commands/ é o formato legado. O recomendado hoje é .claude/skills/<nome>/SKILL.md, que suporta a mesma invocação por barra e ainda pode ser acionado pelo próprio Claude

Os arquivos que você já tem em .claude/commands/ continuam funcionando, ninguém precisa sair migrando às pressas

O erro comum deste passo: esquecer o frontmatter e ficar procurando por que a skill não aparece

7. Revise, commite e abra o pull request

Esse é o passo que fecha o fluxo, e ele é do Claude Code também: a integração nativa com git prepara as mudanças no stage, escreve a mensagem de commit, cria branch e abre pull request

Na prática: pede pra ele criar uma branch só de documentação, lê o diff linha por linha, e só então manda commitar e abrir o PR pro time revisar

Use isso a teu favor, branch separada deixa o diff limpo e a revisão honesta

O erro comum deste passo: misturar a atualização de docs com mudança de código no mesmo commit e perder a chance de ler o texto com calma

Erros que aparecem quando o agente escreve a documentação sozinho

Apareceu um parágrafo explicando "o porquê" de uma escolha:

Sintoma: o texto gerado tem uma seção elegante explicando a motivação por trás de uma decisão técnica, e ninguém do time reconhece aquilo

Causa: o motivo não está no código. O agente encontrou o resultado da decisão e preencheu a lacuna com uma explicação plausível

Solução: corta o parágrafo, ou vai atrás de quem sabe e traz o motivo por escrito pro repositório

Como prevenir: peça explicitamente que ele descreva o QUE existe e marque o que não conseguiu confirmar no código, em vez de completar

O agente parou de seguir o CLAUDE.md:

Sintoma: as instruções estão lá, escritas, e ele ignora metade

Causa: arquivo inchado. A recomendação é ficar abaixo de 200 linhas justamente porque arquivo mais longo consome mais contexto e reduz a aderência

Solução: enxugar de verdade, cortando o que é óbvio ou duplicado

Como prevenir: e aqui vai o detalhe importante, dividir a memória em imports @caminho ajuda na ORGANIZAÇÃO mas não reduz o consumo de contexto, porque os arquivos importados também são carregados na abertura da sessão. Quebrar em cinco arquivos não emagrece nada, só arruma a gaveta

A instrução da subpasta parece que não existe:

Sintoma: você escreveu uma regra no CLAUDE.md de packages/api/ e o agente age como se nunca tivesse visto

Causa: CLAUDE.md de subpasta é carregado sob demanda, quando o Claude lê arquivos daquela subpasta. Se a conversa nem encostou naqueles arquivos, a instrução não entrou

Solução: ou você toca em arquivos da pasta, ou a regra sobe pra um nível que carrega no início da sessão

Como prevenir: regra que vale pro projeto inteiro fica na raiz, regra local fica na subpasta, e você aceita que ela só aparece quando for relevante

Sessão longa, contexto perdido:

Sintoma: depois de horas de trabalho, o agente parece ter esquecido as convenções do projeto

Causa: sessão comprimida

Solução: nesse ponto tem uma boa notícia, o CLAUDE.md da raiz do projeto sobrevive à compactação. Depois do /compact, o Claude Code relê o arquivo do disco e reinjeta o conteúdo na sessão

Como prevenir: o que é regra dura mora no CLAUDE.md da raiz, não numa mensagem que você mandou no início da conversa e sumiu no meio do caminho

Conclusão: o critério de revisão antes de aceitar qualquer texto gerado

A régua que eu usaria é curta e cabe em três linhas

Toda frase da documentação precisa ter fonte no repositório: um comando, um arquivo, uma pasta, uma configuração que você consegue apontar com o dedo

O que não é verificável no código sai do texto, ou vira pergunta pra uma pessoa que estava lá quando aquilo foi decidido

E o texto gerado é rascunho, não versão final. Isso não é implicância minha, é o posicionamento da própria documentação da Anthropic: a saída do /init é ponto de partida, captura os padrões óbvios mas pode perder nuances do fluxo de trabalho, então precisa ser revisada e refinada

Próximo passo prático? Escolhe um repositório pequeno, roda o /init no modo de planejamento e compara o rascunho com o que está no README hoje, linha por linha, antes de commitar

É o teste mais barato que existe pra descobrir o quanto o teu projeto documenta a si mesmo e o quanto ele depende da memória de alguém

Até o próximo post! 😀