Antes de cada missão, Morpheus reúne a tripulação. Diz onde estão, qual o objetivo, o que evitar. Nenhum agente entra na Matrix sem briefing.
O que é o CLAUDE.md?
Quatro características que transformam um arquivo Markdown no briefing permanente do agente.
Carregado em toda sessão
Toda nova conversa começa lendo o arquivo. Você nunca re-explica convenções.
Hierárquico
Três níveis empilhados: global do usuário, raiz do projeto, subdiretório.
Markdown puro
Sem frontmatter, sem sintaxe especial. Texto humano que o agente também lê.
Convenções do projeto
Regras de estilo, comandos comuns, arquivos críticos. O contrato do time.
CLAUDE.md · Memory · Skill
Três escalas, três responsabilidades. Cada um cobre uma camada do conhecimento do agente.
A hierarquia de carga
Três camadas empilhadas. Cada uma adiciona contexto sobre a anterior, do mais geral para o mais específico.
Nível global
~/.claude/CLAUDE.md
Vale para todos os projetos do seu usuário. Aqui ficam suas preferências de estilo, idioma, regras pessoais que não dependem do código.
Raiz do projeto
./CLAUDE.md
As regras deste projeto específico. Comandos de build, padrão de commits, arquivos que ninguém pode editar. Vai junto com o código, no Git.
Subdiretório
./subdir/CLAUDE.md
Só carregado quando o agente trabalha naquela pasta. Útil em monorepos: cada pacote tem suas próprias regras sem poluir o resto.
Regra de ouro: nível mais específico vence o mais geral. Uma regra em ./CLAUDE.md sobrescreve a mesma regra em ~/.claude/CLAUDE.md.
Carregamento
A sessão começa lendo o briefing
Você abre o Claude Code. Antes de qualquer prompt, o sistema lê os três níveis, empilha e injeta no contexto. O agente já sabe das regras antes da primeira palavra.
Dez linhas, briefing pronto
Não precisa ser extenso. Um CLAUDE.md útil cabe em uma tela. O segredo é regra direta, sem rodeios.
Linguagem direta, regra por linha
Comandos de build no topo
Sempre/nunca, sem ambiguidade
# Projeto Loja API ## Comandos - Build: npm run build - Testes: npm test - Lint: npm run lint ## Regras - Sempre rode lint antes de commit - Nunca edite db/migrations/ - Portugues nas mensagens de commit
Dez linhas. Toda nova sessão do Claude Code já chega com isso no contexto.
Versão completa em ~50 linhas
Quando o projeto cresce, o briefing cresce com ele. O ponto de virada é mais ou menos aqui.
# Loja API API REST de e-commerce em Node 20 + Fastify + Postgres. ## Comandos comuns - Dev: npm run dev (sobe na porta 3000) - Build: npm run build - Testes: npm test - Testes E2E: npm run test:e2e - Lint: npm run lint - Migration: npm run db:migrate ## Estrutura - src/routes/ rotas HTTP - src/services/ regras de negocio - src/db/ acesso a dados - tests/ espelha a estrutura de src ## Convencoes de codigo - TypeScript estrito, sem any - Funcoes puras sempre que possivel - async/await, nunca callbacks - Nomes em ingles, comentarios em portugues ## Arquivos protegidos - NUNCA edite db/migrations/ ja aplicadas - NUNCA edite .env.production - Sempre peca confirmacao antes de mudar schema.sql ## Commits - Padrao Conventional Commits - Tipos: feat, fix, chore, docs, refactor - Body em portugues, explicando o porque ## Deploy - Staging: npm run deploy:staging (auto via tag) - Producao: PR aprovado + tag v* + manual approval ## Glossario - SKU: codigo unico de produto (formato XXX-000) - Cart: carrinho ativo em sessao - Order: compra confirmada, imutavel
Comandos
Build, test, lint, db
Estrutura
Pastas e papéis
Regras
Estilo, proteções, commit
Domínio
Glossário do negócio
O que colocar no CLAUDE.md
Informação que muda a forma como o agente age no dia a dia. Curta, acionável, regra direta.
Comandos comuns
Build, test, lint, deploy. O agente não precisa adivinhar como rodar nada.
Convenções de estilo
Idioma, formatação, padrão de nomes. Tudo o que o linter não pega sozinho.
Estrutura do projeto
Mapa de pastas e o papel de cada uma. O agente navega sem perder tempo.
Arquivos protegidos
Aquilo que ninguém pode mexer sem confirmação. Migrations, segredos, schemas.
Dependências críticas
Versão de Node, banco, libs com pegadinha. Evita o agente sugerir update fatal.
Glossário do domínio
Termos que só fazem sentido no seu negócio. SKU, Cart, Order, Lead, Pipeline.
O que NÃO colocar no CLAUDE.md
Informação que já vive em outro lugar. Tudo isso só polui o contexto e degrada a resposta do agente.
Histórico de mudanças
Isso é trabalho do git log. Não duplique informação que já tem fonte de verdade.
Código real
Não cole funções. Use @caminho/arquivo para linkar. Código muda, briefing fica.
Documentação de API
Endpoints, schemas longos, exemplos de payload. Isso vive em OpenAPI, Swagger ou README.
Segredos e tokens
Nunca. O CLAUDE.md vai no Git. Variáveis sensíveis ficam em .env e cofre.
Tutorial extenso
Não escreva um livro. Arquivos enormes degradam o contexto e atrasam toda sessão.
Conteúdo desatualizado
Pior do que não ter regra é ter regra errada. Briefing morto confunde o agente todo dia.
Regra prática: tamanho ideal é entre 50 e 200 linhas. Acima disso, comece a quebrar em subdiretórios ou linkar arquivos com @caminho.
/init escreve o primeiro briefing
Não sabe por onde começar? O Claude Code analisa seu projeto e gera o CLAUDE.md inicial sozinho.
Leitura do projeto
O agente abre package.json, configs, README e scripts para entender o terreno.
Inferência de convenções
Detecta linguagem, frameworks, padrões de pasta. Monta um esqueleto de briefing.
Revisão humana
Você lê, corrige, adiciona o que falta. O /init dá o ponto de partida, não a palavra final.
Seu primeiro CLAUDE.md
Um arquivo na raiz. Quatro seções. Toda sessão futura sabe das regras antes de você abrir a boca.
# Meu Projeto API em Python + FastAPI. ## Comandos - Dev: uvicorn app.main:app --reload - Testes: pytest - Lint: ruff check . ## Regras - Sempre rode pytest antes de commit - Mensagens de commit em portugues - Nunca edite alembic/versions/
Salve na raiz. Da próxima vez que abrir o Claude Code, ele já chega sabendo de tudo.
O agente já sabe o comando e ainda lembra da regra. Zero re-explicação a cada sessão.
Crie o arquivo
CLAUDE.md na raiz do projeto. Pode também rodar /init.
Escreva as regras
Comandos comuns, convenções, arquivos protegidos. Tudo em formato de regra direta.
Commit no Git
Vai junto com o código. O time inteiro herda o mesmo briefing automaticamente.
# Projeto API REST de e-commerce. ## Estilo de codigo Siga o guia detalhado em: @docs/code-style.md ## Padrao de testes Veja exemplos completos em: @docs/testing-guide.md ## Esquema do banco Schema atual: @db/schema.sql
No CLAUDE.md
@docs/code-style.md
O agente lê
conteúdo do arquivo
Linke com @caminho
Em vez de inflar o briefing, divida em arquivos menores e referencie. O CLAUDE.md vira o índice; o detalhe mora ao lado.
Mantém o CLAUDE.md curto e legível
Cada arquivo tem dono e versionamento próprio
Conteúdo só entra no contexto se referenciado
Cinco padrões que vale incluir
Os blocos que aparecem em todo briefing maduro. Você escreve uma vez, o time inteiro colhe.
Padrão 1 · Comandos comuns
Build, test, lint, tudo num lugar
O agente nunca deveria adivinhar como rodar testes. Liste os comandos do dia a dia logo no início do CLAUDE.md, com a sintaxe exata.
## Comandos comuns - Dev local: npm run dev - Build: npm run build - Testes unitarios: npm test - Testes E2E: npm run test:e2e - Lint: npm run lint - Type check: npm run typecheck - Format: npm run format # Ordem obrigatoria antes de PR: # lint > typecheck > test
1. Rodar npm run lint
2. Rodar npm run typecheck
3. Rodar npm test
Se tudo passar, sigo para o commit.
Se algum falhar, paro e te aviso.
Por que funciona: os comandos viram parte do contrato. O agente segue a ordem certa toda vez, sem você precisar lembrar.
Padrão 2 · Convenções de estilo
O que o linter não pega
Idioma de comentário, padrão de nomes, formato de log. Tudo que é convenção subjetiva do time vira regra escrita aqui.
## Convencoes de estilo - TypeScript estrito, sem any - Nomes de funcao em ingles - Comentarios em portugues - async/await, nunca callbacks - Funcoes < 30 linhas - Sem abreviacoes (user, nao usr) - Logs estruturados em JSON - Erros lancam AppError, nunca Error cru
- nome em ingles ✓
- tipos explicitos ✓
- comentario em pt ✓
- erro lanca AppError ✓
Função pronta em src/users/find.ts.
Por que funciona: o estilo deixa de ser folclore oral. Está escrito, o agente cobra, novos devs aprendem sem perguntar.
Padrão 3 · Arquivos protegidos
O que o agente nunca toca sem pedir
Migrations aplicadas, schema do banco, arquivos de configuração de produção. Lista de arquivos que exigem confirmação humana antes de qualquer edição.
## Arquivos protegidos NUNCA edite sem confirmacao explicita: - db/migrations/ (ja aplicadas em prod) - .env.production - infra/terraform/ - schema.sql - Qualquer arquivo em legacy/ Se eu pedir para mexer em algo dessa lista, **pare e pergunte** antes de executar a edicao.
A migration 042 já foi aplicada em produção.
Regra do CLAUDE.md: nunca editar migrations aplicadas.
Sugestão: crio uma nova migration 043_add_deleted_at?
Por que funciona: blindagem por convenção, não por permissão técnica. O agente vê a regra, respeita o limite, evita o desastre.
Padrão 4 · Deploy e release
O caminho da esteira ao usuário
Como vai para staging, como vai para produção, quem aprova. Quanto mais explícito, menos chance de alguém (humano ou agente) fazer deploy errado.
## Deploy e release ### Staging - Push para main dispara CI - Se verde, deploy auto via GitHub Actions - URL: staging.loja.dev ### Producao - PR aprovado por 2 reviewers - Tag v[major].[minor].[patch] - Aprovacao manual no GitHub - Smoke test pos-deploy obrigatorio NUNCA pule etapas. Se algo travar, pare e me chame.
- PR aprovado por 2 reviewers ?
- Tag semântica ?
- Approval manual ?
Confirma cada etapa antes de eu seguir?
Posso começar abrindo o PR e pedindo review.
Por que funciona: deploy descrito no briefing vira processo, não improviso. O agente respeita o fluxo, o time confia no resultado.
Padrão 5 · Glossário
Os termos do negócio
Cada domínio tem seu vocabulário. SKU, Cart, Pipeline, Lead, Tenant. Definir os termos no CLAUDE.md alinha o agente com o negócio, não só com a tecnologia.
## Glossario do dominio - SKU: codigo unico de produto. Formato: XXX-000. - Cart: carrinho ativo na sessao. Tem TTL de 30 minutos. - Order: compra confirmada. Imutavel apos pagamento. - Fulfillment: separacao e envio do pedido pelo CD. - CD: centro de distribuicao. Hoje temos 3 (RJ, SP, PE).
- SKU → código produto XXX-000
- CD de SP → centro SP
Vou criar GET /skus?cd=SP retornando lista de SKUs com estoque > 0 no CD informado.
Validando o formato XXX-000 na resposta.
Por que funciona: o agente para de inventar terminologia. Fala a língua do negócio, não a média da internet.
Os cinco padrões lado a lado
Resumo dos blocos essenciais de um CLAUDE.md maduro.
| Padrão | O que cobre | Ganho | |
|---|---|---|---|
| Comandos comuns | Build, test, lint, deploy com sintaxe exata | Agente sabe rodar tudo | |
| Convenções de estilo | Idioma, nomes, padrões que o linter não pega | Estilo escrito, não folclore | |
| Arquivos protegidos | Migrations, schema, infra, segredos | Blindagem contra acidente | |
| Deploy e release | Caminho para staging e produção, gates de aprovação | Deploy vira processo | |
| Glossário do domínio | Termos do negócio, jargão, abreviações próprias | Agente fala a língua certa |
Cinco blocos, um arquivo, todo o time alinhado. CLAUDE.md não é documentação: é o contrato vivo entre você, o agente e o projeto.
Quer dominar cada camada?
O livro Engenharia de Software para Agentes Inteligentes destrincha CLAUDE.md, commands, hooks, skills, MCP, subagents e tudo que faz o agente trabalhar a seu favor.
·
@canalsandeco
Tank disca, Trinity pilota, Smith vigia. Mas todos partem do mesmo briefing.
Sem CLAUDE.md, cada sessão recomeça do zero. Com ele, o agente já chega sabendo onde está, o que evitar, qual o objetivo. Briefing é a base; o resto é execução.