Vários projetos, uma IA: onde cada regra mora

Você mexe em mais de um projeto. E toda vez que abre a IA, explica de novo em qual deles vocês estão, qual é o padrão, qual comando roda o teste.

Pior que o retrabalho é o erro silencioso: às vezes ela aplica a regra de um projeto no outro, e você só descobre quando o resultado sai errado.

A correção não é lembrar melhor. É deixar escrito — e no lugar certo, porque existe mais de um lugar e eles se comportam de um jeito que quase todo mundo entende ao contrário.

O arquivo

O CLAUDE.md é um arquivo de texto comum na raiz do projeto. Ela lê sozinha toda vez que abre uma sessão ali, sem você pedir nada.

Não tem sintaxe especial. É markdown: título, lista, parágrafo. Se você consegue escrever um README, você consegue escrever este arquivo.

São dois lugares, não um

Aqui começa a parte que resolve o problema de vários projetos.

No pessoal vai o que é seu e não muda de projeto para projeto: responda em português, não use emoji em código, sempre rode o lint antes de dizer que terminou, pergunte antes de apagar arquivo.

No do projeto vai o que é do projeto e vale para quem mais mexer nele: o comando que roda os testes, a estrutura de pastas, a regra de estilo que foge do padrão da linguagem, o que nunca deve ser tocado.

E tem uma consequência prática que costuma passar batido: o arquivo do projeto fica no Git. Quem entrar no time depois recebe as regras junto com o código, sem ninguém precisar explicar nada. O pessoal não vai — ele é seu e fica só na sua máquina.

Se você quiser uma preferência sua só naquele projeto, sem impor ao time, existe o CLAUDE.local.md — mesma pasta, e vai para o .gitignore.

Um não apaga o outro

Este é o mal-entendido que mais custa caro.

A leitura natural é "o arquivo mais específico ganha, então o do projeto substitui o pessoal". Não é isso. Eles somam. Ela carrega todos, e o mais específico serve para detalhar ou contradizer um ponto — não para desligar o resto.

Na prática:

• Seu arquivo pessoal diz "responda em português". O projeto não repete isso. Ela responde em português nesse projeto do mesmo jeito.
• Seu pessoal diz "sempre rode o lint". O projeto diz "o lint aqui é npm run check, não npm run lint". As duas valem: ela roda o lint, e roda o comando certo.

Escrever partindo da soma economiza texto: no arquivo do projeto você só põe o que é diferente dali, e não a lista inteira de regras de novo.

Ela lê as pastas acima também

Se você guarda seus repositórios dentro de uma pasta que junta vários — algo como ~/código/cliente-x/projeto-a e ~/código/cliente-x/projeto-b — a regra comum aos dois não precisa ser copiada nos dois.

Um CLAUDE.md em ~/código/cliente-x/ vale para tudo que está abaixo dele. É o lugar do que é verdade para o cliente inteiro: o padrão de commit, o ambiente, a convenção de nomes. Cada projeto abaixo guarda só o que é dele.

Isso importa porque regra duplicada é regra que sai de sincronia. Copiada em cinco projetos, você corrige em três, esquece dois, e volta a ter comportamento diferente sem entender por quê.

Não escreva um livro

A recomendação oficial é manter o arquivo abaixo de 200 linhas, e o motivo está escrito junto: arquivo mais longo consome mais contexto e reduz a adesão às instruções.

Ou seja: escrever mais não faz ela obedecer mais. Faz obedecer menos, porque a regra que importava se perde no meio do barulho.

O critério para decidir linha por linha é uma pergunta só:

Tirar isso faria ela errar?

Se a resposta for não, corta. Aplicando essa pergunta:

Fica:

• Comando que ela não tem como adivinhar (npm run check, não npm run lint)
• Regra de estilo que foge do padrão da linguagem
• O que nunca deve ser tocado, e por quê
• Como rodar os testes

Sai:

• O que ela descobre lendo o código (as dependências estão no package.json)
• Convenção padrão da linguagem, que ela já conhece
• Documentação detalhada de API
• História do projeto

O que sobrou e ainda é útil não se perde: vira uma skill, que ela carrega só quando precisa em vez de pesar em toda conversa.

Um exemplo curto que funciona

# Projeto: API de cobrança

## Comandos
- Testes: `make test` (não use `pytest` direto — falta variável de ambiente)
- Lint: `make check`

## Regras
- Migração de banco nunca é editada depois de commitada. Crie uma nova.
- Toda rota nova precisa de teste de permissão, não só de resposta 200.
- `legado/` está em processo de remoção. Não acrescente nada lá.

Doze linhas. Todas passam no teste do "tirar isso faria ela errar?".

Como começar hoje

1. Abra o projeto em que você mais trabalha e crie o CLAUDE.md na raiz.
2. Escreva só o que você já explicou mais de uma vez para a IA nesta semana.
3. Crie o ~/.claude/CLAUDE.md e mova para lá o que não é daquele projeto.
4. Da próxima vez que se pegar explicando algo de novo, acrescente uma linha — no arquivo certo.

O arquivo nasce pequeno e cresce por uso, não por planejamento. É assim que ele fica abaixo das 200 linhas sem esforço.