Source: https://claudetutorial.com/guides/pt-br/claude-md-explicado-ensine-seu-projeto-ao-claude-code-uma-vez [Voltar para Guias](https://claudetutorial.com/guides/pt-br) Builders # CLAUDE.md explicado: ensine o seu projeto ao Claude Code uma vez só 27 de outubro de 2026 13 min de leitura --- Toda sessão nova do Claude Code começa com a cabeça vazia. Você diz que é para usar pnpm, não npm. Diz onde ficam os testes. Diz para não mexer na pasta gerada. Amanhã você diz tudo isso de novo. > O CLAUDE.md é o lugar onde você escreve o que, de outro modo, teria de explicar outra vez. É um arquivo de texto simples, em Markdown. O Claude Code o lê no início de cada sessão, então tudo o que está nele já é conhecido antes do seu primeiro prompt. Este guia mostra onde o arquivo fica, como escrever um que o Claude siga e o que deixar de fora. ## O que o CLAUDE.md é, e o que ele não é Cada sessão do Claude Code começa com uma janela de contexto nova. Dois mecanismos levam conhecimento de uma sessão para a seguinte: | | CLAUDE.md | Memória automática | | --- | --- | --- | | Quem escreve | Você | O Claude | | O que entra | Instruções e regras | Aprendizados e padrões que ele percebe | | Carregamento | Toda sessão | Toda sessão (primeiras 200 linhas ou 25 KB) | | Melhor para | Padrões de código, fluxos de trabalho, estrutura | Suas correções e preferências | Os dois são carregados como contexto. Essa palavra importa: o Claude lê o CLAUDE.md e tenta segui-lo, mas ele não é uma configuração imposta. Uma linha vaga ou contraditória pode ser ignorada. Voltamos a isso na parte de solução de problemas, porque é isso que define como o arquivo deve ser escrito. Já tem um AGENTS.md? Se o seu repositório tem um AGENTS.md escrito para outros agentes de código, o Claude Code pode lê-lo no lugar de um CLAUDE.md, desde que não haja CLAUDE.md nem CLAUDE.local.md no seu diretório de trabalho ou acima dele. Se os dois existirem, o Claude lê só os arquivos CLAUDE.md. Para usar os dois, importe o AGENTS.md a partir do seu CLAUDE.md. Ler o AGENTS.md diretamente exige o Claude Code 2.1.277 ou posterior. ## Onde o arquivo fica São quatro lugares, e eles se somam. O Claude os carrega do escopo mais amplo ao mais específico, então o que está mais perto do seu projeto é lido por último. Organização Só você, neste projeto 1. Política gerenciada Definida pelo TI para todos da organização 2. Usuário ~/.claude/CLAUDE.md, suas preferências em todo projeto 3. Projeto ./CLAUDE.md ou ./.claude/CLAUDE.md, compartilhado com a equipe pelo git 4. Local ./CLAUDE.local.md, pessoal deste projeto, fora do git Os arquivos são somados, não trocados. Nada sobrescreve nada, então contradições entre camadas confundem o Claude. Os dois que você vai usar são o arquivo do **projeto** e o do **usuário**. - **Arquivo do projeto.** Coloque o `CLAUDE.md` na raiz do projeto, ou numa pasta `.claude` na raiz. Faça o commit, para que todos que trabalham no projeto recebam as mesmas instruções. Escreva o que vale para qualquer pessoa: comandos de build, convenções, estrutura do projeto. - **Arquivo do usuário.** O `~/.claude/CLAUDE.md` acompanha você em todos os projetos. Use-o para hábitos pessoais, como o jeito que você prefere que as explicações sejam escritas. - **Arquivo local.** O `CLAUDE.local.md` serve para anotações suas e específicas de um projeto, como a URL de um ambiente de testes. Adicione-o ao `.gitignore` para que não entre no commit. O Claude também procura na pasta em que você o abriu e em todas as pastas acima dela. Se você começa em `foo/bar/`, ele carrega `foo/bar/CLAUDE.md` e `foo/CLAUDE.md`. Os arquivos de pastas abaixo de você são carregados depois, sob demanda, na primeira vez que o Claude lê ou edita um arquivo naquela subpasta. ## Comece com o /init Você não precisa escrever a primeira versão à mão. Dentro de uma sessão, rode: my-website ``` > /initAnalisando seu código...CLAUDE.md criado com os comandos de build, as instruções de teste e as convenções encontradas. ``` Ilustração do fluxo. A saída exata depende da sua versão e do seu projeto. O Claude Code lê o seu projeto e escreve um CLAUDE.md com os comandos de build e de teste e as convenções que descobre. Se já existir um CLAUDE.md, o `/init` sugere melhorias em vez de sobrescrevê-lo. Trate o resultado como um primeiro rascunho. Seu trabalho é acrescentar o que o Claude não teria como descobrir sozinho. Para confirmar que o arquivo foi carregado, rode `/context` numa sessão e olhe em **Memory files**. ## O que deve entrar no arquivo Um bom teste, antes de escrever qualquer linha, tem duas perguntas: 1. O Claude acharia isso lendo o código? Estrutura de pastas, o framework de testes, o jeito como os componentes existentes são feitos: o Claude lê isso em segundos. Escrever só acrescenta peso e nenhum valor. 2. Ele realmente iria procurar? Alguns fatos estão no repositório, mas levam minutos para ser encontrados, e o Claude os procuraria de novo a cada sessão. Esses merecem uma linha. Se as duas respostas forem sim, deixe a linha de fora. O que sobra é informação que nunca esteve no código, ou que custa tempo de verdade para ser redescoberta: - Os comandos exatos para build, teste e lint, com as flags que você usa - Uma decisão que sua equipe tomou numa reunião e que o código não mostra - A variável de ambiente ou o serviço local de que seus testes precisam - Uma convenção diferente do padrão da ferramenta, e por quê - Coisas em que nunca mexer, como uma pasta gerada Acrescente uma linha quando o Claude errar a mesma coisa pela segunda vez, quando uma revisão de código pegar algo que ele deveria saber, ou quando você digitar a mesma correção da sessão passada. Esse é o sinal de que o fato pertence ao arquivo. ### Um exemplo que vale copiar Aqui está um arquivo de projeto curto. Repare que cada linha é algo que dá para verificar e que pouca coisa descreve a arquitetura. ``` # Project notes ## Commands - Install: pnpm install (never npm or yarn) - Dev server: pnpm dev (port 3000) - Tests: pnpm test -- --run, run before every commit - Typecheck: pnpm typecheck, must pass before a pull request ## Conventions - 2-space indentation, double quotes - API handlers live in src/api/handlers/ - Do not edit anything in src/gen/, it is generated by pnpm codegen ## Gotchas - Integration tests need a local Redis: docker compose up redis - Dates are stored in UTC, formatted only in the UI layer ``` São 15 linhas, e cada uma merece estar ali. ## Como escrever linhas que o Claude segue Como o CLAUDE.md é contexto e não configuração, o jeito de redigir cada linha decide se ela será seguida. Escreva instruções concretas o bastante para serem conferidas. | Vago | Concreto | | --- | --- | | Formate o código direito | Use indentação de 2 espaços | | Teste suas mudanças | Rode `npm test` antes de fazer o commit | | Mantenha os arquivos em ordem | Os handlers da API ficam em `src/api/handlers/` | | Cuidado com o banco de dados | Nunca rode migrações em produção, use a URL de staging em `.env.staging` | Depois, mantenha o arquivo em boa forma: - **Curto.** Mire em menos de 200 linhas por arquivo. Arquivos mais longos usam mais contexto e o Claude os segue com menos confiabilidade. - **Organizado.** Agrupe linhas relacionadas sob títulos e tópicos em Markdown. O Claude segue melhor a estrutura do que parágrafos densos. - **Coerente.** Se duas linhas discordam, o Claude pode escolher uma ao acaso. Releia seus arquivos de vez em quando, inclusive os das subpastas, e apague o que estiver desatualizado. Gritar não ajuda Acrescentar IMPORTANT ou CAIXA ALTA a uma linha que o Claude vive deixando passar tende a fazê-lo aplicar a regra em excesso. Se uma linha realmente não pode ser flexibilizada, ela nem pertence ao CLAUDE.md. Ela pertence a um hook ou a uma regra de negação (deny), que o Claude Code aplica sempre, não importa o que o modelo decida. Para o Claude auditar seus arquivos de instruções atrás de linhas desatualizadas ou conflitantes, rode `/doctor prompt-audit`. Ele relata o que achou e propõe edições, sem mudar nada até você pedir. Exige o Claude Code 2.1.283 ou posterior. ## Importando outros arquivos O CLAUDE.md pode puxar outros arquivos com um `@` antes do caminho. O arquivo importado é carregado junto com o CLAUDE.md que o menciona. ``` See @README for the project overview and @package.json for the npm commands. # Additional instructions - git workflow: @docs/git-instructions.md ``` Caminhos relativos são resolvidos a partir do arquivo que contém a importação. Importações podem importar outros arquivos, até quatro níveis de profundidade. O `@` só é lido fora de trechos de código, então coloque o caminho entre crases se quiser mencioná-lo sem importá-lo. Importações servem para organizar, mas não diminuem o contexto: os arquivos importados continuam sendo carregados por inteiro. Para instruções pessoais que você quer em várias cópias do mesmo repositório, importe um arquivo da sua pasta pessoal, como `@~/.claude/my-project-instructions.md`. Na primeira vez que um projeto importa um arquivo de fora do diretório de trabalho, o Claude Code pede sua aprovação. ## Quando um arquivo fica longo demais Em algum momento o arquivo passa do que toda sessão precisa. Você tem algumas ferramentas, cada uma para um trabalho diferente. | Ferramenta | Use para | Quando carrega | | --- | --- | --- | | CLAUDE.md | Fatos necessários em toda sessão | Toda sessão | | Regras em `.claude/rules/` | Instruções para uma parte do código | Quando o Claude toca arquivos correspondentes (se tiverem escopo) | | Habilidades | Procedimentos de vários passos, manuais de equipe | Só quando usadas ou relevantes | | Hooks | Coisas que sempre ou nunca devem acontecer | Executados pelo próprio Claude Code | ### Regras com escopo para certos arquivos Coloque um arquivo Markdown por assunto em `.claude/rules/`, como `testing.md` ou `api-design.md`. Para uma regra valer só para certos arquivos, acrescente um campo `paths` no topo: ``` --- paths: - "src/api/**/*.ts" --- # API rules - Every endpoint validates its input - Use the standard error response format ``` Uma regra sem `paths` carrega em toda sessão. Uma regra com escopo carrega quando o Claude lê ou edita um arquivo correspondente, o que tira as instruções do caminho no resto do tempo. Se um bloco do CLAUDE.md é um procedimento de vários passos, como preparar um release, mova-o para uma habilidade. As habilidades só carregam quando são usadas. ## Memória automática: as anotações que o Claude guarda para si Além do arquivo que você escreve, o Claude Code pode guardar anotações por conta própria. A memória automática vem ligada por padrão nas sessões locais. Enquanto trabalha, o Claude salva quatro tipos de anotação: sobre você (função e preferências), feedback (correções e abordagens que você confirmou), o projeto (decisões e prazos que não aparecem no código) e referências (onde achar coisas fora do projeto). Ele não salva o que consegue ler no código, nem o que o seu CLAUDE.md já diz. Você verá mensagens como "Saved 2 memories" na sessão. As anotações são Markdown simples em `~/.claude/projects/`, e as primeiras 200 linhas ou 25 KB do arquivo de índice são carregadas no início de cada sessão. Rode `/memory` para ver todos os arquivos de instruções e a pasta da memória automática, abrir qualquer um deles no seu editor e ligar ou desligar a memória automática. Se você disser ao Claude "use sempre pnpm, não npm", ele salva isso na memória automática. Para colocar algo no CLAUDE.md, diga isso: "adicione isto ao CLAUDE.md". Dentro do Claude Tutorial Escrever o que você repetiria Transformar a mesma correção em instrução permanente é um hábito que vale a pena em qualquer tipo de trabalho com o Claude, não só em código, e o app o ensina passo a passo. Em breve [DISPONÍVEL NO Google Play](https://play.google.com/store/apps/details?id=com.claudetutorial.mobile) ## Quando o Claude não segue Passe por estes pontos em ordem. Eles resolvem a maioria dos casos. 1. Confira se o arquivo realmente carregou Rode `/context` e olhe em Memory files. Se o seu arquivo não aparece lá, o Claude não consegue vê-lo. Um CLAUDE.md numa subpasta não aparece na abertura, porque é carregado sob demanda. 2. Deixe a linha mais específica Troque "formate o código bonito" por "use indentação de 2 espaços". Uma linha que dá para verificar é uma linha que o Claude consegue seguir. 3. Procure contradições Dois arquivos que dizem coisas diferentes sobre o mesmo comportamento deixam o Claude no palpite. Confira juntos o arquivo do projeto, o do usuário e as regras. 4. Reduza o tamanho Um arquivo longo dilui todas as linhas. Mova a parte sobre uma área para uma regra com escopo e corte o que o Claude poderia ler sozinho. 5. Imponha, se tiver de acontecer Se uma instrução precisa rodar num ponto fixo, como antes de todo commit, escreva-a como um hook. Quem executa o hook é o Claude Code, então o modelo não pode pulá-lo. Dois casos extras merecem atenção. Depois de um `/compact`, o CLAUDE.md da raiz do projeto é lido de novo do disco, então ele sobrevive. Uma instrução que você deu só na conversa não sobrevive, então mova-a para o arquivo. E quando um CLAUDE.md numa subpasta é muito longo (mais de uns 40.000 caracteres numa janela de contexto menor), o Claude recebe só o começo dele, então mantenha esses curtos. ## Perguntas frequentes ### Onde coloco o CLAUDE.md? Na raiz do projeto (`./CLAUDE.md`) ou em `./.claude/CLAUDE.md`. Coloque preferências pessoais para todos os projetos em `~/.claude/CLAUDE.md`. Use `./CLAUDE.local.md`, adicionado ao `.gitignore`, para anotações privadas sobre um projeto. ### Qual deve ser o tamanho de um CLAUDE.md? Mire em menos de 200 linhas. Se passar, o Claude Code mostra um aviso ao iniciar e no `/status`. Mova as partes de uma área específica para regras com escopo e corte o que o Claude consegue ler no código. ### O CLAUDE.md é a mesma coisa que um prompt de sistema? Não. O CLAUDE.md é entregue como uma mensagem depois do prompt de sistema. O Claude tenta segui-lo, mas não há garantia de cumprimento estrito. Para instruções que precisam valer sempre, use um hook ou uma regra de permissão. ### Devo fazer o commit do CLAUDE.md no git? Sim para o arquivo do projeto, para a equipe inteira compartilhá-lo e ele melhorar a cada correção. Não para o `CLAUDE.local.md`, que é pessoal. ### O Claude lê o CLAUDE.md das subpastas? Sim, sob demanda. Ele carrega o arquivo de uma subpasta na primeira vez que o Claude lê ou edita um arquivo naquela pasta, e mostra uma linha Loaded com o caminho. ### Qual é a diferença entre o CLAUDE.md e uma habilidade? O CLAUDE.md é para fatos necessários em toda sessão. Uma habilidade é um procedimento ou manual que só carrega quando é chamada ou relevante, então não ocupa espaço no resto do tempo. ## Seu checklist do CLAUDE.md - O arquivo está na raiz do projeto e com commit feito, e um arquivo local separado no `.gitignore` guarda o que for pessoal - Ele tem seus comandos de build, teste e lint exatamente como você os roda - Toda linha passa no teste: o Claude não aprenderia isso pelo código, ou perderia tempo redescobrindo - Nenhuma linha contradiz outra, e o arquivo tem menos de 200 linhas - `/context` lista o arquivo em Memory files ## Continue lendo - [Claude Code para iniciantes: instale, entre e faça sua primeira tarefa](https://claudetutorial.com/guides/pt-br/claude-code-para-iniciantes-instale-entre-e-faca-sua-primeira-tarefa) se você ainda não começou uma sessão. - [Boas práticas do Claude Code: hábitos que dão melhores resultados](https://claudetutorial.com/guides/pt-br/boas-praticas-do-claude-code-habitos-que-dao-melhores-resultados) para prompts, verificações e gestão de contexto. - [Modos de permissão e modo plan do Claude Code, explicados](https://claudetutorial.com/guides/pt-br/modos-de-permissao-e-modo-plan-do-claude-code-explicados) para decidir o que o Claude pode fazer sem perguntar. - [Projetos do Claude: contexto que fica](https://claudetutorial.com/guides/pt-br/projetos-do-claude-contexto-que-permanece) para a mesma ideia no app do Claude: instruções permanentes guardadas com um projeto.