Codebase Context Docs (Documentação de Contexto do Código-fonte)

O que Codebase Context Docs (Documentação de Contexto do Código-fonte) faz?

Gere um CLAUDE.md compacto na raiz do repositório, além de um conjunto de arquivos de aprofundamento em .claude/docs/.

O objetivo não é "documentar o projeto." É: tornar um agente futuro eficaz já na primeira interação, gastando o mínimo possível de tokens. CLAUDE.md é carregado no contexto a cada interação, para sempre. Cada linha nele é um custo. Uma linha só merece seu lugar se ela muda o que um agente faz em uma tarefa que ele ainda não viu. Todo o resto pertence a .claude/docs/, carregado apenas quando relevante.

Essa troca de custo-benefício direciona todas as regras abaixo.

Fluxo de Trabalho

Siga esta ordem. Escrever CLAUDE.md primeiro é a falha mais comum — produz um arquivo com aparência plausível, mas cheio de suposições, e os documentos acabam sendo escritos para corresponder às suposições, em vez do código.

1. Pesquise o repositório mecanicamente (comandos abaixo).
2. Leia os pontos de entrada, a configuração e uma fatia representativa do código-fonte.
3. Escreva .claude/docs/*.md — os detalhes ficam aqui.
4. Escreva CLAUDE.md por último — ele é um índice sobre o que você acabou de aprender.
5. Verifique — contagem de linhas, cada comando, cada arquivo:linha.

Passo 1 — Pesquise

Execute estes comandos antes de ler qualquer coisa. Eles custam pouco e evitam suposições erradas sobre tamanho, mix de linguagens e ferramentas.

# Forma e escala
git ls-files | wc -l
git ls-files | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -40
git ls-files | grep -oE '\.[a-z0-9]+$' | sort | uniq -c | sort -rn | head -20

# Ferramentas e pontos de entrada (leia cada arquivo que estes comandos encontrarem)
ls -a
git ls-files | grep -iE '(package\.json|pyproject\.toml|setup\.py|requirements.*\.txt|Cargo\.toml|go\.mod|pom\.xml|build\.gradle|Gemfile|composer\.json|pubspec\.yaml|Makefile|justfile|Taskfile|docker-compose|Dockerfile)'
git ls-files '.github/workflows/*' '.gitlab-ci.yml' '.circleci/*'

# Documentos existentes — leia-os, eles codificam intenções que você não pode inferir do código
git ls-files | grep -iE '(readme|contributing|architecture|adr|docs/)' | head -30

# Atividade recente mostra quais partes do repositório estão realmente vivas
git log --oneline -15
git log --pretty=format: --name-only -n 200 | sort | uniq -c | sort -rn | head -20

Observe qualquer coisa que a pesquisa deixe de encontrar. Um repositório sem configuração de CI e sem diretório de teste é um achado real, não uma lacuna a ser ignorada.

Passo 2 — Leia

Leia, nesta ordem:

• Arquivos de manifesto (package.json, pyproject.toml, …) — do início ao fim, incluindo a seção de scripts/tarefas. É aqui que os comandos reais estão.
• Arquivos de fluxo de trabalho de CI — os comandos que a CI executa são os comandos que realmente funcionam.
• README.md e quaisquer CONTRIBUTING.md / docs/ — para o porquê, que o código não pode lhe dizer.
• O(s) ponto(s) de entrada da aplicação, e então 5 a 15 arquivos-fonte representativos distribuídos pelos diretórios principais.

Use subagentes paralelos para a passagem de leitura de código-fonte quando o repositório for grande e subagentes estiverem disponíveis — um por diretório principal, cada um reportando o que aquele diretório faz, quais padrões usa e as âncoras arquivo:linha desses padrões. Isso é mais rápido e mantém despejos crus de arquivo fora do contexto principal.

Durante a leitura, mantenha uma lista atualizada de padrões candidatos com o caminho/para/arquivo.ts:142 exato onde você viu cada um. Você precisará dessas âncoras depois, e voltar para encontrá-las é caro.

Passo 3 — Escreva .claude/docs/

Crie apenas os arquivos que o código-fonte realmente suporta. Um documento vazio ou preenchido artificialmente é pior do que um ausente, porque ensina o agente a desconfiar de todo o conjunto.

Arquivo	Crie quando	Contém
architectural_patterns.md	Sempre (a menos que o repositório seja trivialmente pequeno)	Decisões estruturais recorrentes: injeção de dependência, gerenciamento de estado, tratamento de erros, limites de módulos, convenções de design de API, regras de camadas
testing_strategy.md	Testes existirem	Frameworks, onde os testes vivem, convenções de fixtures/fábricas, como executar um único teste vs. a suíte, o que é simulado vs. real
build_and_deploy.md	Ferramentas de build ou CI não forem óbvias	Pipeline de build, variáveis de ambiente e onde são declaradas, artefatos, fluxo de release/deploy, pegadinhas de configuração local de desenvolvimento
data_model.md	Dados persistentes, esquemas ou migrações existirem	Entidades e relacionamentos principais, localização e fluxo de trabalho de esquemas/migrações, camada de validação
api_reference.md	O projeto expõe ou consome uma API significativa	Organização de rotas/endpoints, convenções de requisição/resposta, autenticação, versionamento, formato de erros

Você pode adicionar um arquivo específico do domínio quando um código-fonte tiver um grande subsistema que não se encaixa nestes (realtime_sync.md, billing.md). Prefira um número pequeno de arquivos substanciais a muitos arquivos finos.

A regra de evidência multi-arquivo

Esta é a regra que separa um documento de padrões útil de um alucinado.

Documente um padrão apenas se você o viu em pelo menos três arquivos separados e cite pelo menos dois deles. Uma única abstração inteligente é trivia. Uma convenção repetida em todo o código-fonte é o que um novo agente deve seguir para escrever código que se encaixe.

Quando você encontrar algo que parece um padrão, mas aparece apenas uma vez, ou descarte-o ou use grep para confirmar se ele se generaliza:

rg -n 'useAppDispatch' --stats           # quão difundido é?
rg -l 'implements Repository' | head     # quais arquivos compartilham essa forma?

Se uma convenção é aplicada de forma inconsistente — metade do código-fonte faz de um jeito, metade de outro — diga isso explicitamente e observe qual é a mais nova (git log nos arquivos lhe diz). Um agente que sabe que um código-fonte está no meio de uma migração escreve código melhor do que um que assume uniformidade.

Referencie por âncora, não por snippet

Escreva Veja src/services/base.py:34 em vez de colar a classe. Snippets ficam obsoletos no momento em que alguém edita o arquivo, e um snippet desatualizado engana ativamente — enquanto um número de linha desatualizado é obviamente digno de ser re-verificado. Também mantém os documentos curtos o suficiente para serem lidos.

Inclua o nome do símbolo junto com a linha para que a âncora sobreviva a pequenas edições: PaymentProcessor.execute — src/billing/processor.py:88.

Deixe o estilo de código de lado

O usuário executa linters e formatadores. Não documente indentação, estilo de aspas, comprimento de linha, ordenação de importações ou convenções de nomenclatura. Isso é aplicado mecanicamente; reafirmá-los em um arquivo sempre carregado gasta contexto para duplicar uma ferramenta. Documente convenções que um linter não pode aplicar — qual camada pode importar qual, quando adicionar uma migração, onde uma nova rota se registra.

Passo 4 — Escreva CLAUDE.md

Abaixo de 150 linhas, rigorosamente. Use esta estrutura:

# <Nome do Projeto>

<2-4 frases: o que é este projeto e para quem/serve. O PORQUÊ —
o problema que ele resolve. Esta é a parte que não pode ser inferida do código,
portanto é a parte que mais vale a pena escrever cuidadosamente.>

## Pilha Tecnológica

<Lista compacta: linguagem + versão, framework, banco de dados, infraestrutura chave.
Apenas o que muda como o código é escrito. Pule o despejo de dependências transitivas.>

## Estrutura do Projeto

<Tabela ou lista de diretórios de nível superior, uma linha cada, dizendo o que pertence
ali e — quando não for óbvio — o que não pertence.>

## Comandos

<Apenas comandos verificados e universalmente úteis: instalar, dev, build, test,
testar-um-arquivo, lint, typecheck. Observe o gerenciador de pacotes se não for
o padrão para o ecossistema.>

## Convenções

<3-8 linhas, apenas regras que se aplicam em todo o repositório e que um linter não
pode pegar. Se uma regra é específica de um subsistema, ela pertence a um arquivo de docs.>

## Documentação Adicional

Leia estes quando a tarefa exigir — não os carregue preventivamente.

- `.claude/docs/architectural_patterns.md` — <quando ler>
- `.claude/docs/testing_strategy.md` — <quando ler>

Duas coisas fazem a seção "Documentação Adicional" funcionar ou falhar:

• Cada entrada diz quando ler, não o que contém. "Leia antes de adicionar um endpoint ou alterar uma forma de resposta" direciona um agente corretamente; "documenta a API" não.
• A lista é o único lugar onde detalhes especializados são referenciados. Se você se pegar explicando a configuração de teste em CLAUDE.md e em testing_strategy.md, delete-o de CLAUDE.md.

Veja references/templates.md para um exemplo preenchido de CLAUDE.md e de cada arquivo de docs.

Passo 5 — Verifique

Não pule esta etapa. Cada modo de falha desta tarefa é uma falsidade com aparência de confiança, e cada uma é barata de detectar.

wc -l CLAUDE.md                          # deve ser < 150

Depois:

• Execute cada comando que você escreveu, ou no mínimo confirme que cada um existe no manifesto / configuração de CI. Um npm test em CLAUDE.md que não está em package.json desperdiçará o tempo de um agente em toda sessão futura. Se você não puder executar um comando, marque-o como lido-da-fonte em vez de verificado.
• Verifique aleatoriamente cada arquivo:linha — abra alguns e confirme se o símbolo citado está lá.
• Releia CLAUDE.md a frio, como um agente vendo este repositório pela primeira vez. Delete qualquer linha que não mude o que você faria. Conselhos genéricos ("escreva código limpo", "trate erros adequadamente") são o agressor usual.
• Reporte a contagem final de linhas e a lista de arquivos criados.

Se CLAUDE.md estiver acima de 150 linhas, corte em vez de comprimir — mova uma seção inteira para um arquivo de docs e deixe uma linha de índice para trás. Apertar prosa para caber produz um arquivo denso que ninguém analisa.

Trabalhando com um CLAUDE.md existente

Se já existir um, não sobrescreva às cegas. Leia-o primeiro, depois verifique-o contra o código atual: comandos que não existem mais, diretórios que foram renomeados, padrões dos quais se migrou. Preserve qualquer instrução escrita à mão que codifique uma preferência humana que você não pode derivar do código ("nunca toque no SDK fornecido", "pergunte antes de adicionar uma dependência") — essas são as linhas de maior valor no arquivo e as mais fáceis de destruir. Mostre ao usuário o que você está removendo e por que antes de cortar algo substancial.