Vale a pena usar o Claude Code para escrever a documentação do projeto?

Fala aí, beleza? Pedir pro Claude Code escrever a documentação do projeto é uma das coisas mais tentadoras que existem hoje: em um comando você sai da pasta sem doc nenhuma pra um arquivo bonito, com seções, títulos e tudo no lugar

Aí bate o desconforto de dar commit nesse texto sem ter lido linha por linha 😅

Esse post não é um "olha que massa, gerou sozinho". A ideia aqui é separar três coisas: onde a doc feita com apoio do agente rende de verdade, onde ela envelhece rápido e vira texto morto dentro do repo, e o que você precisa checar antes de publicar qualquer coisa que saiu dali

Tem lugar em que vale muito. E tem lugar em que escrever à mão (ou não escrever) continua sendo mais barato…

Onde a documentação gerada com o Claude Code rende de verdade

1. O CLAUDE.md inicial, com o /init:

Esse é o caso mais direto de todos

O Claude Code tem o comando /init, que analisa o codebase e gera um CLAUDE.md inicial com comandos de build, instruções de teste e convenções detectadas

E ele não gera no chute: a análise passa por arquivos de pacote, documentação já existente, arquivos de configuração e a estrutura de código do projeto

/init

Tem um detalhe bem massa: ele também lê regras que você já escreveu pra outras ferramentas e incorpora as partes relevantes. Entram aí as regras do Cursor (.cursor/rules/ ou .cursorrules) e do Copilot (.github/copilot-instructions.md)

E com a variável de ambiente CLAUDE_CODE_NEW_INIT=1 o /init lê ainda outras fontes: AGENTS.md, .devin/rules/, .windsurf/rules/ ou .windsurfrules e .clinerules

Ou seja: se o time já espalhou regra por três ferramentas diferentes, isso vira insumo em vez de trabalho duplicado

E se você já tem um CLAUDE.md no projeto? Relaxa, o /init sugere melhorias em vez de sobrescrever o arquivo

2. Guia de setup e onboarding:

Aqui o agente joga em casa

A página oficial de boas práticas recomenda usar o Claude Code justamente pra aprendizado e exploração quando você entra em um codebase novo

É o mesmo movimento que a gente faz na mão quando chega em um projeto desconhecido: abre pasta, lê config, roda comando pra ver o que quebra. Só que o agente faz isso muiiito mais rápido e ainda escreve o que encontrou

Quando o projeto é antigo e ninguém do time lembra o porquê de metade das coisas, essa mesma exploração serve de base pra refatorar um projeto legado com alguma segurança

3. Explicação de módulo:

Outra recomendação oficial que ajuda demais aqui: separar pesquisa e planejamento da implementação

Quando você pede "me explica esse módulo" sem estar no meio de uma tarefa de código, o agente não está tentando entregar diff nenhum, ele está só lendo e resumindo

O texto que sai dali costuma ser bem melhor do que o resumo apressado que ele escreve enquanto implementa alguma coisa

4. Doc de convenção e armadilha conhecida:

Esse é o conteúdo que a Anthropic explicitamente recomenda colocar no CLAUDE.md:

• convenções: nomenclatura, tratamento de erro, layout de arquivos e decisões do tipo "usamos X, não Y"
• arquitetura em três frases
• restrições duras
• gotchas, aquelas armadilhas que pegam todo mundo que chega novo no projeto

Repara que é tudo conteúdo que muda pouco e que dói caro quando ninguém escreveu

Tipo de documentação: o que o agente entrega e o que envelhece rápido

Nem toda doc tem a mesma validade

Tem texto que descreve intenção (envelhece devagar) e tem texto que descreve estado (envelhece na velocidade do repo). É aí que nasce a documentação que ninguém atualiza, aquele arquivo que todo mundo abre uma vez e nunca mais

A lógica da tabela é simples: quanto mais o texto repete o que já está no código, menos ele merece existir como doc separada

Quando a doc do agente vira texto genérico (e como evitar)

Sintoma: doc bonita que só repete a árvore de arquivos

Você lê e pensa "tá certinho", mas não aprendeu nada. É o texto que diz que a pasta components tem componentes 🙂

Causa: você pediu resumo do óbvio. E "o que já é óbvio pela árvore de arquivos" está na lista oficial do que NÃO colocar no CLAUDE.md

Solução: puxar o texto pra convenção, restrição dura e gotcha. Se a informação some quando alguém abre o projeto no editor, ela não precisava estar escrita

Como prevenir: antes de aceitar o rascunho, pergunte de cada bloco: isso um dev novo descobriria sozinho em dois minutos? Se sim, corta

Sintoma: CLAUDE.md gigante e o agente piorando

O arquivo cresceu, virou enciclopédia, e o Claude começou a errar mais

Causa: a própria página oficial de boas práticas diz que a maioria das práticas parte de uma restrição, a janela de contexto enche rápido e o desempenho degrada conforme ela enche

E tem uma armadilha aqui que pega muita gente: dividir o CLAUDE.md em imports com @caminho organiza, sim, mas não reduz o consumo de contexto, porque os arquivos importados carregam no início

Solução: manter o arquivo enxuto mesmo. Vale por espaço de janela de contexto e por relação sinal e ruído

Como prevenir: tratar cada linha nova como se ela custasse alguma coisa. Porque custa

Sintoma: regra escrita que o time não segue

O doc diz uma coisa, o código faz outra, e todo mundo aprende a ignorar o arquivo

Causa: regra aspiracional. Está lá na lista do que não incluir: regras que o time não segue de fato

Solução: escrever só o que é praticado hoje. Se o time quer mudar a prática, primeiro muda a prática

Como prevenir: na revisão, para cada regra, apontar um arquivo do repo que já a cumpre. Não achou? Sai fora

O que revisar antes de publicar qualquer doc que saiu do agente

Checklist curto, na ordem que eu acho que faz sentido:

1. Revise o rascunho do /init uma vez, pra limpar

Essa é orientação oficial: passar uma vez no rascunho gerado e limpar. O erro comum aqui é tratar o output do /init como versão final e sair commitando

2. Apague o que é óbvio pela árvore de arquivos, o changelog e a doc completa de API

São os três itens explícitos da lista do que não incluir. O erro comum é confundir tamanho com qualidade: doc grande passa sensação de completude e entrega ruído

3. Exija evidência em vez de aceitar afirmação de sucesso

A página de boas práticas recomenda pedir que o Claude mostre evidência: a saída de teste, o comando rodado com o retorno, ou um screenshot. E o argumento é bom, revisar evidência é mais rápido do que refazer a verificação na mão

Aplica isso em TODO comando que aparece na doc, cada tipo do seu jeito. Comando de setup: você roda do zero, em uma cópia limpa do projeto, e só mantém no texto o que funcionou. Comando de teste e de build: você pede a saída junto, não o "rodei e passou". Comando que depende de credencial, banco ou serviço externo: você deixa escrito qual é a dependência, senão o passo funciona só na tua máquina

Comando de setup que ninguém rodou é ficção

O erro comum: aceitar "pronto, documentei o processo de build" sem ver o build rodando

4. Confira onde o arquivo mora e quando ele é lido

Arquivos CLAUDE.md no diretório de trabalho e acima dele são lidos no início da sessão. Já o CLAUDE.md de subdiretório é carregado sob demanda, quando o Claude lê arquivos daquele subdiretório

O erro comum é escrever uma regra crítica lá dentro de um subdiretório e esperar que ela valha na sessão inteira

Vale lembrar também que a auto memória do Claude Code grava em ~/.claude/projects/<project>/memory/, um diretório por raiz de repositório git, separado do ~/.claude/CLAUDE.md e do ./CLAUDE.md, que continuam sendo mantidos à mão

5. Transforme erro repetido em regra

A orientação oficial é tratar o CLAUDE.md como doc vivo de onboarding: quando o Claude erra a mesma coisa duas vezes, é sinal de que falta uma regra, então você adiciona uma linha

O erro comum é corrigir no chat toda vez e nunca escrever

6. Passo avançado (opcional): padronize a checagem

Hooks são configurados via /hooks ou em settings.json, e o hook de projeto fica em .claude/settings.json dentro do repositório, então ele é compartilhável com o time

O evento PostToolUse roda depois que uma chamada de ferramenta é bem sucedida, e o uso típico dele é auto formatação e lint automático

Não vou te entregar receita de hook que atualiza README sozinho, porque isso eu não achei documentado oficialmente. Prefiro te falar o que existe do que te ensinar passo errado

Pra rodar em script e pipeline, o Claude Code tem o modo headless com a flag -p:

claude -p "liste os comandos de setup citados na doc e diga quais não existem mais no projeto"

Ele executa um comando único, sem UI interativa, lê stdin e permite redirecionar a saída

E em CI existe a flag --bare, que inicia o Claude Code sem carregar hooks, plugins, auto memória e CLAUDE.md do host. É o modo determinístico, indicado justamente pra rodar dentro de pipeline com saída repetível

O que aparece quando o agente documenta e executa um projeto inteiro

Aqui eu falo do que eu vi na prática

No vídeo eu começo um projeto do zero, em uma pasta vazia, usando uma skill de brainstorm que faz o Claude Code me entrevistar antes de escrever qualquer documento

As perguntas vieram encadeadas e bem específicas: usuário único ou múltiplos, tipo de autenticação, categorias fixas ou customizáveis, escolha de stack. E aqui vai o conselho: responda com sinceridade, porque o documento sai da qualidade das suas respostas

Ele ainda ofereceu montar mockups e diagramas no navegador durante a conversa, avisando que ia consumir mais tokens. Eu recusei pra ir direto pra implementação

No fim do questionário, saiu uma documentação de especificações do projeto e o próprio Claude Code pediu revisão antes de seguir. E é isso que eu reforço no vídeo: essa doc precisa ser LIDA e conferida por quem pediu, pra ver se é mesmo o que você quer ou se ficou faltando ajuste

Depois eu pedi pra transformar o documento de design aprovado em um plano de implementação, com tarefas em ordem, dependências e critérios de aceitação pra cada uma. Saiu um plano com 14 tarefas

Na hora de mandar executar, referencie o arquivo do plano com @. Assim você garante que ele vai usar o documento certo, em vez de confiar só no contexto da sessão

Executei pedindo subagents e TDD (teste antes, implementação depois). Uma das etapas, a configuração de sessão, ficou rodando por quase 10 minutos. No fim, as 14 tarefas concluídas com testes e o projeto no ar em localhost 3000

E aí a parte honesta: mesmo com toda a documentação e o plano, o app deu erro no cadastro e no login no primeiro teste no navegador. Colei o erro, pedi análise e correção

O fluxo documentado garantiu arquitetura e funcionamento, mas entregou interface genérica, o que exigiu uma etapa separada de design

A leitura disso pro tema do post: documento de design e plano de implementação são o tipo de doc que o agente escreve bem, porque descrevem intenção e estado atual do que se quer construir. O que pede olho humano é o texto que vira permanente dentro do repositório

Minha avaliação: vale a pena, porque a documentação inicial faz o Claude Code cobrir pontos que eu talvez não pensasse de início, mesmo demorando mais e gastando mais token. Mas nada disso é bala de prata, é o que funciona no meu uso diário

No vídeo abaixo eu mostro esse fluxo inteiro rodando. E vale reparar que skills e comandos de projeto são justamente a forma de padronizar isso entre as pessoas do time: um arquivo em .claude/commands/deploy.md e uma skill em .claude/skills/deploy/SKILL.md criam o /deploy e funcionam do mesmo jeito, e subagents customizados ficam em .claude/agents/

Veredito: quando usar e quando escrever à mão

Bora fechar a conta

Usar sem medo: rascunho de CLAUDE.md com o /init, guia de setup e exploração de codebase novo. São os casos em que o agente lê mais rápido que você e o custo do erro é baixo, porque você vai conferir rodando

Usar com revisão pesada: README público e explicação de arquitetura. O agente monta a estrutura, você garante que aquilo descreve o projeto real e não uma versão idealizada dele

Escrever à mão ou não escrever: regra de time, decisão de produto e qualquer doc que o time não vai manter. Regra aspiracional está na lista oficial do que não incluir, e doc abandonada é pior que doc inexistente, porque ela mente com cara de verdade

A doc gerada é ponto de partida e doc vivo de onboarding

Não é entrega final. Nunca foi

Conclusão

Se você chegou até aqui, o próximo passo é simples e leva pouco tempo

Abra um projeto que já existe, rode o /init, e revise o rascunho uma vez cortando tudo que é óbvio pela árvore de arquivos, changelog e doc completa de API. Depois, cada vez que o Claude errar a mesma coisa duas vezes, adicione UMA linha

Aí compara: o que saiu dali descreve melhor o teu projeto do que a doc que está no repo hoje?

Essa resposta vale mais que qualquer opinião minha 😀

Até o próximo post!