CLAUDE.md é o arquivo que define como o Claude entende seu projeto. Um arquivo bem escrito significa menos correções, código melhor e agentes que realmente sabem no que estão trabalhando.
Este guia percorre cada seção de um arquivo CLAUDE.md, desde declarações de stack técnico até instruções específicas por agente. Acompanhe passo a passo e construa o seu.
CLAUDE.md é um arquivo markdown que você coloca na raiz do seu projeto. Quando o Claude Code inicia uma sessão, ele lê esse arquivo primeiro. Tudo que está nele se torna parte do contexto do Claude: seu stack técnico, sua estrutura de arquivos, as convenções da sua equipe e qualquer instrução que você queira que cada agente siga.
Pense nele como um documento de briefing. Sem ele, o Claude precisa adivinhar como seu projeto está organizado. Com um bom CLAUDE.md, o Claude já sabe onde as coisas ficam, quais padrões seguir e o que evitar. A diferença na qualidade dos resultados é significativa.
“Investir 10 minutos no CLAUDE.md economiza horas corrigindo código gerado por IA que não corresponde aos padrões do seu projeto.”
Observado em centenas de projetos Claude Code
A estrutura e a especificidade do seu CLAUDE.md impactam diretamente na qualidade do trabalho do Claude na sua codebase.
Um CLAUDE.md bem estruturado cobre essas seis áreas. Cada uma fornece ao Claude informações concretas que ele pode usar imediatamente.
Liste seus frameworks, bibliotecas e versões de forma explícita. Inclua seu gerenciador de pacotes, versão do Node e quaisquer requisitos de execução. O Claude usa isso para gerar código compatível sem adivinhar.
Descreva seus diretórios principais e o que cada um contém. Componentes, stores, serviços, rotas de API, tipos. Um diagrama de árvore curto com uma linha de descrição por pasta funciona bem.
Documente seus padrões de nomenclatura (camelCase para arquivos, PascalCase para componentes), sua abordagem de tratamento de erros, a ordem dos imports e qualquer regra específica do projeto. Isso mantém a saída do Claude consistente com seu código existente.
Inclua seus comandos de dev, build, test e lint. Quando o Claude precisar verificar que algo funciona ou sugerir um script, ele usará exatamente os comandos que seu projeto espera.
Se você usa vários agentes (QA, frontend, backend, DevOps), adicione uma seção descrevendo o foco de cada papel. Isso é especialmente útil com a configuração multi-agente do AgentsRoom.
Diga ao Claude o que NÃO fazer. Não modificar arquivos de configuração, não mexer no sistema de autenticação, não refatorar a camada de banco de dados. Limites explícitos impedem que os agentes façam mudanças indesejadas.
Não precisa escrever tudo de uma vez. Comece pelo básico e expanda conforme você descobre o que o Claude precisa saber.
Abra seu package.json e liste cada framework, biblioteca e ferramenta que seu projeto usa. Anote as versões. Verifique os requisitos de execução (versão do Node, versão do Python, banco de dados). Isso se torna sua seção de stack técnico.
package.json + versões runtime + banco de dados
Execute um tree rápido do seu diretório src. Identifique as pastas de primeiro nível e escreva uma descrição de uma linha para cada uma. Foque em onde ficam os componentes, stores, serviços, tipos e rotas de API.
Árvore src/ com anotações de propósito
Observe seu código existente e anote os padrões: como você nomeia arquivos, como trata erros, como estrutura imports, se usa exports padrão ou nomeados. Escreva-os como regras curtas.
Nomenclatura, imports, tratamento de erros, exports
Se você trabalha com agentes especializados, adicione áreas de foco para cada papel. O agente frontend deve conhecer sua biblioteca de componentes. O agente DevOps deve conhecer seu pipeline de deploy. O agente QA deve conhecer seu framework de testes.
Áreas de foco + áreas a evitar por papel
AgentsRoom foi construído com o CLAUDE.md como conceito central, não como algo secundário.
Edite seu CLAUDE.md diretamente no AgentsRoom com destaque de sintaxe e salvamento em tempo real. Sem precisar trocar para seu editor de texto ou IDE.
Veja como cada agente interpreta seu CLAUDE.md em tempo real. Observe a saída do terminal para verificar que os agentes seguem suas convenções e respeitam suas áreas a evitar.
Cada projeto no AgentsRoom tem seu próprio CLAUDE.md. Alterne entre projetos e cada agente carrega automaticamente o arquivo de contexto correto para aquela codebase.
Os 14 papéis de agentes do AgentsRoom se combinam diretamente com as seções do CLAUDE.md. Defina áreas de foco e áreas a evitar por papel, e cada agente pega exatamente as instruções destinadas a ele.
CLAUDE.md is prepended to every Claude turn. A bloated CLAUDE.md silently inflates Claude Code token usage on every message. AgentsRoom puts a per-session token meter on each agent so you can see exactly how much your CLAUDE.md is costing you, with a live cache hit rate to confirm it stays cached.
See the Claude Code token usage trackerAGENTS.md é o arquivo de instruções portátil que seus agentes de código leem antes de tocar no seu código. O que colocar nele, como ele se diferencia do CLAUDE.md e como manter um único contexto entre Codex, Antigravity e Claude.
O código já não é o gargalo, a comunicação é. Veja como falar com os seus agentes de IA Claude, Codex, Antigravity e Grok Build para entregar mais rápido, com mais precisão e gastando menos tokens.
Sua assinatura do Claude não é medida em tokens, então nenhuma tela mostra um saldo de tokens. Veja o que ela realmente mede, as duas telas que de fato mostram isso, por que ela se esgota mesmo quando você não está digitando, e o que a mudança da janela semanal de setembro de 2026 faz com a sua semana.
Baixe o AgentsRoom e use o editor CLAUDE.md integrado para dar aos seus agentes o contexto que precisam. Melhores instruções, código melhor.
App complementar: acompanhe seus agentes em qualquer lugar
Use Claude, Codex, Antigravity CLI ou outro provedor de IA.
Envie bugs e pedidos direto para o seu backlog público.