Como usar o Claude Code para escrever a documentação que ninguém do time atualiza

Fala aí, beleza? Todo repositório tem aquele README que ninguém abre há meses: fala de uma pasta que já foi renomeada, manda rodar um script que não existe mais, e ninguém tem coragem de apagar

A tese deste post é meio impopular: documentação inventada é pior do que documentação ausente

Quando não tem doc, todo mundo desconfia e vai ler o código

Quando tem doc errada, todo mundo obedece… e o dev novo passa a tarde inteira perseguindo um comando que nunca funcionou

O Claude Code muda a equação porque ele não escreve de memória: ele lê o codebase que está ali na sua frente

Só que isso só vale alguma coisa se você exigir a ORIGEM de cada frase que ele escrever, se liga nisso 🙂

O que você precisa antes de começar:

• Claude Code instalado e aberto na raiz do repositório que vai ser documentado (não numa subpasta qualquer)
• O projeto versionado em git, porque o CLAUDE.md do projeto é um arquivo commitável e vai viver junto com o código
• Uma decisão tomada antes de digitar qualquer coisa: essa documentação é do TIME ou é sua?

Essa última pergunta parece boba, mas ela define onde os arquivos vão parar

O Claude Code lê instruções, configurações, skills, subagentes e memória em dois lugares: o diretório .claude do projeto e o ~/.claude da sua pasta de usuário

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

O que está em .claude/ no repositório é versionado e vale pro time inteiro

O que está em ~/.claude/ é configuração pessoal sua, válida em todos os projetos

E tem um aviso importante: se o seu repo já tem um AGENTS.md, ele não vai ser ignorado

Rodar /init num repositório que já tem AGENTS.md faz o Claude Code ler esse arquivo e incorporar as partes relevantes no CLAUDE.md gerado

Ou seja, trabalho anterior não vai pro lixo =)

Passo a passo: gerar a documentação a partir do código real

1. Rode o /init e entenda o que ele está lendo

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 para aquele repositório

Repara que a matéria prima dele é o SEU projeto, não um template genérico

O erro comum deste passo: aceitar o texto gerado sem checar nada, porque ficou bonitinho e organizado

Texto bem formatado não é texto verdadeiro

2. Escolha o escopo: projeto ou pessoal

Ao escolher a opção pessoal no /init, o Claude Code cria um CLAUDE.local.md na raiz do projeto e adiciona esse arquivo ao .gitignore

Ou seja, sua mania particular fica com você e não polui o repositório do time

O erro comum deste passo: commitar preferência pessoal como se fosse regra do time

"sempre me responda em português e não use emoji" não é convenção de arquitetura, é gosto seu

3. Importe em vez de copiar

O CLAUDE.md aceita importar outros arquivos com a sintaxe @, incluindo README e package.json

Os arquivos importados são expandidos e carregados no contexto junto com o CLAUDE.md que os referencia

# CLAUDE.md

## Visão geral do projeto
@README

## Scripts disponíveis
@package.json

## Convenções de commit
@docs/git-instructions.md

Caminhos relativos e absolutos são aceitos, e aqui mora uma pegadinha boa: o caminho relativo resolve em relação ao arquivo que faz o import, não ao diretório de trabalho

Já me ferrei com esse tipo de detalhe em outras ferramentas, então anota aí

O erro comum deste passo: colar o README inteiro dentro do CLAUDE.md

Aí você cria duas versões da verdade e uma delas vai envelhecer sozinha, adivinha qual

4. Corte para menos de 200 linhas

A documentação oficial recomenda um alvo de menos de 200 linhas por arquivo CLAUDE.md, porque arquivo longo consome mais contexto e reduz a aderência às instruções

Isso é contraintuitivo pra caramba: a gente acha que quanto mais escrever, mais o modelo vai obedecer

É o contrário

O erro comum deste passo: transformar o CLAUDE.md em manual corporativo de 800 linhas

5. Peça a origem de cada afirmação

Esse é o passo que separa documentação de ficção

Depois de gerar, volte e peça, pra cada frase do arquivo, qual arquivo, qual função ou qual script sustenta aquilo

O que não tiver origem apontável, você apaga

Sem dó

É a mesma disciplina de debugar a partir do log de erro em vez de descrever o bug com as suas palavras: você entrega a prova, não a sua interpretação da prova

O erro comum deste passo: aceitar frase plausível

"o projeto usa cache em memória para acelerar as consultas" soa ótimo… e pode não ter uma linha de código por trás

6. Use o subagente Explore antes de escrever

O Claude Code traz subagentes embutidos, e entre eles está o Explore, acionado quando é preciso buscar ou entender o codebase sem fazer alterações

Você especifica o nível de profundidade na chamada: quick, medium ou very thorough

Pra levantar o que existe num repo grande antes de escrever qualquer linha de doc, ele é o cara

Detalhe que importa: Explore e Plan são os únicos subagentes que não recebem o CLAUDE.md nem o git status

Isso mantém a pesquisa rápida e barata, mas significa que a leitura dele é crua, sem as suas regras por cima

O erro comum deste passo: esperar que o Explore já saiba das convenções que você acabou de escrever no CLAUDE.md

Ele não recebeu esse arquivo, beleza?

7. Distribua em camadas se for monorepo

Dá pra ter CLAUDE.md em camadas: ~/.claude/CLAUDE.md com preferências pessoais válidas em todos os projetos, ./CLAUDE.md na raiz do projeto compartilhado com o time via git, e CLAUDE.md em subdiretórios pra sobrescrever regras

Se você conhece a ideia de config global e config local, é exatamente isso

O erro comum deste passo: enfiar as regras de cinco pacotes diferentes num CLAUDE.md só na raiz

O arquivo estoura, o contexto estoura, e volta o problema do passo 4

Como transformar a atualização da documentação em rotina

Gerar é a parte fácil

O drama da documentação nunca foi nascer, foi envelhecer

1. Transforme a checagem numa skill

Cada skill do Claude Code é um diretório que tem o SKILL.md como ponto de entrada, com frontmatter YAML contendo os campos obrigatórios name e description

O corpo da skill só é carregado quando ela é usada, então ela não fica pesando no seu contexto o tempo todo

---
name: doc-check
description: Compara o CLAUDE.md e o README com o código atual e aponta cada afirmação sem arquivo de origem
---

Para cada afirmação do CLAUDE.md e do README:

1. Aponte o arquivo (e a função ou script) que sustenta a afirmação
2. Marque como SEM ORIGEM tudo que não tiver arquivo apontável
3. Não reescreva nada nesta etapa, só liste

O arquivo mora em .claude/skills/doc-check/SKILL.md e vira o comando /doc-check

O erro comum deste passo: usar o .claude/commands/

Um arquivo em .claude/commands/deploy.md e uma skill em .claude/skills/deploy/SKILL.md criam o mesmo comando /deploy e funcionam da mesma forma, só que o .claude/commands/ é o formato legado

O recomendado é o .claude/skills/<nome>/SKILL.md, que suporta a mesma invocação por barra e ainda permite a invocação autônoma pelo Claude

2. Em monorepo, deixe cada pacote com a skill dele

O Claude Code descobre automaticamente skills em diretórios .claude/skills aninhados

Então packages/frontend/.claude/skills/ funciona sem você registrar nada em lugar nenhum

O erro comum deste passo: centralizar tudo na raiz e criar uma skill gigante cheia de "se for o pacote X, faça assim"

3. Dispare a checagem com hook

Hooks são comandos de shell, endpoints HTTP ou prompts de LLM definidos por você, que rodam automaticamente em pontos específicos do ciclo de vida do Claude Code

Dois eventos servem bem aqui: o PostToolUse, que dispara depois que uma chamada de ferramenta é concluída, e o Stop, que dispara quando o Claude termina de responder

O Stop costuma ser o mais tranquilo pra documentação, porque você checa uma vez no fim em vez de a cada arquivo tocado

O erro comum deste passo: pendurar uma checagem pesada no PostToolUse e transformar cada edição de arquivo numa espera

4. Escolha o escopo do hook com cuidado

O escopo depende de onde ele é declarado:

Uma boa notícia: o Claude Code observa os arquivos de configuração e os recarrega quando eles mudam, sem precisar reiniciar a sessão, inclusive pra permissões e hooks

O erro comum deste passo: colocar em ~/.claude/settings.json um hook que só faz sentido num projeto, e aí ele começa a rodar em TODO repositório que você abre

A mesma lógica de escopo vale pra outras rotinas chatas do dia a dia, tipo atualizar dependências do projeto, que também pedem regra por projeto e não regra global

Três formas de a documentação gerada sair errada (e como prevenir)

Sintoma: o arquivo descreve um script ou uma pasta que não existe

Causa: o pedido foi genérico

"documente esse projeto" abre espaço pro texto plausível, aquele que descreve o projeto que a maioria dos projetos parecidos seria

Solução: exigir arquivo e origem pra cada afirmação, e apagar tudo que não tiver

Prevenção: nunca aceite a primeira versão como final, ela é rascunho de matéria prima

Sintoma: o Claude ignora as regras que você escreveu no CLAUDE.md

Causa: arquivo longo demais consumindo contexto

Lembra do alvo de menos de 200 linhas? Ele existe justamente porque arquivos longos reduzem a aderência às instruções

Solução: cortar o arquivo, mover o detalhamento pra imports com @ e transformar procedimento em skill, que só carrega o corpo quando é usada

Regra na cabeça: CLAUDE.md é índice, não enciclopédia

Sintoma: você fica escrevendo à mão a mesma correção pela décima vez

Causa: existe um sistema que já grava isso e você não olhou

O Claude Code tem dois sistemas de memória complementares: os arquivos CLAUDE.md, que VOCÊ escreve, e a auto memory, que são notas que o próprio Claude grava a partir de correções e preferências

Solução: use o /memory pra navegar pela pasta de auto memory e ver o que ele salvou

O conteúdo é markdown simples, dá pra ler, editar ou apagar na mão

A auto memory vem ligada por padrão e pode ser desligada pelo próprio /memory, que grava a chave autoMemoryEnabled nas configurações do usuário, em ~/.claude/settings.json

Antes de escrever regra nova, vale abrir o /memory e ver se ela já não está lá 😀

Onde esse fluxo compensa mais:

Repositório herdado sem README utilizável. Aquele projeto que caiu no seu colo com um README de duas linhas de 2021, e o único jeito de entender era ler tudo

Monorepo. Cada pacote com regra própria via CLAUDE.md por subdiretório, e as skills aninhadas descobertas automaticamente em .claude/skills dentro de cada pacote

Onboarding de pessoa nova. O CLAUDE.md commitado deixa de ser "arquivo da IA" e vira o texto que o time inteiro lê, porque é o único que fica perto do código

Projeto que já tem AGENTS.md. O /init lê esse arquivo e aproveita as partes relevantes, então não é começar do zero

Separar convenção de preferência. Convenção do time vai pro ./CLAUDE.md versionado, preferência sua vai pro CLAUDE.local.md (que o próprio /init já joga no .gitignore) ou pro ~/.claude/CLAUDE.md

E vale saber o mapa completo antes de sair inventando: a Anthropic descreve sete formas de instruir o comportamento do Claude Code (arquivos CLAUDE.md, rules, skills, subagentes, hooks, output styles e append ao system prompt), e a recomendação é começar pelo CLAUDE.md com as convenções do projeto

Começa simples, depois você complica se precisar

Conclusão

Documentação boa não é a mais completa, é a que aponta origem

Um arquivo de 40 linhas em que cada frase tem um caminho de arquivo por trás vale mais que um manual de 500 linhas cheio de frase bonita que ninguém consegue conferir

O próximo passo é bem direto: abra o terminal na raiz do projeto, rode o /init, leia o que voltou com desconfiança, apague tudo que não tiver arquivo por trás e commite o CLAUDE.md junto com o código

Se ele viaja com o código, ele envelhece junto com o código, e não sozinho num canto

Bora fazer o teste no seu repo mais bagunçado? 😀

até o próximo post!