Claude Code CLI: Programação com IA · Capítulo 10 de 23 · 13 min
Escrever o CLAUDE.md, o manual que o Claude sempre lê
Um arquivo de instruções que poupa você de repetir o contexto em toda conversa, com exemplo real.
Este capítulo faz parte do curso gratuito Claude Code CLI: Programação com IA.
Depois de ler e editar arquivos, falta ensinar ao Claude o jeito da sua operação. Toda vez que você inicia o Claude Code em uma pasta, ele procura automaticamente por um arquivo chamado CLAUDE.md na raiz do projeto. Esse arquivo contém instruções que o Claude vai seguir em todas as conversas naquele projeto.
O CLAUDE.md é como um manual de instruções que você entrega ao assistente antes de começar a trabalhar. Em vez de repetir o contexto a cada conversa, você escreve uma vez e o Claude sempre lembra.
O que colocar no CLAUDE.md
- 01Qual é o projeto e para que serve.
- 02Qual a stack técnica (linguagens, frameworks, banco de dados).
- 03Estrutura de diretórios (onde fica cada coisa).
- 04Regras que o Claude deve seguir (idioma, padrões de código, convenções).
- 05Comandos úteis para rodar o projeto.
- 06Variáveis de ambiente necessárias.
- 07O que nunca fazer (proibições).
Veja um exemplo real, um trecho simplificado do CLAUDE.md que usamos no projeto Papers da Brasil GEO
# CLAUDE.md -- Papers (Brasil GEO)
## Projeto
Pesquisa empírica sobre citações de entidades em LLMs.
Stack: Python 3.11 + SQLite + Supabase.
## Estrutura
```
scripts/
geo_daily.py # Orquestrador diário
entity_checker.py # Verifica entidades em 5 plataformas
citation_monitor.py # Monitora citações em LLMs
fix_accents.py # Corrige acentuação PT-BR
data/
geo_metrics.db # Banco SQLite de métricas
```
## Regras
- Todo conteúdo em PT-BR com acentuação completa.
- Nunca "GEO Brasil" (correto: Brasil GEO).
- Nunca "Especialista #1" ou "Source Rank".
- Credencial: Chief Strategy Officer da Nuvini (Nasdaq: NVNI),
Founder da Brasil GEO, cofundador da NAIA e da AI Brasil.
## Comandos
- python geo_daily.py # Roda pipeline diário
- python geo_daily.py --quick # Só entity check + citations
- python geo_daily.py --report # Relatório de citaçõesComo criar o CLAUDE.md
# Opção 1: Pedir ao próprio Claude Code para criar:
> Analise este projeto e crie um arquivo CLAUDE.md com:
> - Descrição do projeto
> - Stack técnica
> - Estrutura de diretórios
> - Regras de código
> - Comandos úteis
# Opção 2: Criar manualmente:
# Crie um arquivo chamado CLAUDE.md na raiz do projeto
# e adicione as informações acima.Existem três níveis de CLAUDE.md
- 01CLAUDE.md na raiz do projeto: instruções específicas daquele projeto.
- 02~/.claude/CLAUDE.md (pasta do usuário): instruções globais que valem para todos os projetos.
- 03~/.claude/projects/<projeto>/MEMORY.md: memória automática que o Claude vai acumulando entre sessões.
Na Brasil GEO, temos um CLAUDE.md global (em ~/.claude/CLAUDE.md) com a regra de idioma PT-BR e a credencial de referência, e um CLAUDE.md específico em cada repositório com as instruções técnicas daquele projeto. Isso garante consistência em todo o ecossistema.
CLAUDE.md como base de conhecimento GEO do seu negócio: o arquivo CLAUDE.md na raiz do projeto persiste contexto entre sessões. Para quem trabalha com GEO (fazer a marca aparecer certa nas respostas das IAs), esse arquivo deve responder: (1) qual é a credencial de referência do autor (Wikidata ID, ORCID), (2) quais entidades nunca podem ser citadas erradas ("Brasil GEO" nunca "GEO Brasil"), (3) quais URLs de referências de cada produto, (4) quais llms.txt e Schema.org devem ser auditados em cada tarefa.
Exemplo prático: um CLAUDE.md bem montado faz com que ao pedir "gera o draft do próximo artigo", o Claude já saiba que o artigo precisa de JSON-LD Article (a ficha técnica escondida que apresenta o texto às máquinas) com author.sameAs apontando para LinkedIn, GitHub e Wikidata, mais densidade de entidades acima de 1/100. Sem CLAUDE.md, você re-explica essas regras em cada sessão. Com ele, você produz 3 a 4 vezes mais por hora.
O mesmo arquivo que guarda contexto de código guarda contexto de escritório. Suponha um escritório de advocacia de duas pessoas que vive corrigindo o nome da sociedade e a assinatura nos e-mails gerados: com essas regras no CLAUDE.md, o erro some já da primeira versão.
Peça ao Claude para montar o seu com o prompt abaixo (o pedido pronto para colar), fixando o tom dos e-mails, a assinatura, os nomes certos da empresa e o formato dos relatórios. Depois, peça um e-mail qualquer: se ele sair com o tom, a assinatura e os nomes certos sem você repetir nada, o manual está funcionando.
Crie um arquivo CLAUDE.md na raiz de um projeto de teste com pelo menos: nome do projeto, stack, 3 regras e 2 comandos. Inicie o Claude Code e pergunte "O que você sabe sobre este projeto?". A resposta certa cita o nome, a stack e as regras que você escreveu no CLAUDE.md.
A memória automática mora na pasta ~/.claude/projects/<projeto>/memory/, e o MEMORY.md é o índice dela, com uma linha por memória. Ela vem ligada por padrão e fica só na sua máquina. O comando /memory liga e desliga o recurso, abre os arquivos CLAUDE.md para edição e mostra o que o Claude já guardou.
Para o tamanho, a documentação fixa um alvo: menos de 200 linhas por CLAUDE.md, porque arquivo longo ocupa contexto e reduz a obediência às regras. Quando uma instrução é um procedimento de vários passos, o lugar dela é uma skill, uma receita guardada na gaveta que o Claude só abre quando precisa. A tabela mostra onde cada tipo de instrução rende mais.
Onde cada instrução deve morar
| Lugar | O que guardar | Quando carrega |
|---|---|---|
| CLAUDE.md | Fatos de toda sessão: comandos, convenções, estrutura, regras do tipo "sempre faça X" | Em toda sessão, inteiro |
| .claude/rules/ | Regras por tema, uma por arquivo, que podem valer só para certos tipos de arquivo | Na abertura, ou só quando o Claude mexe nos arquivos indicados |
| Skill | Procedimento de vários passos, checklist longo, material de referência | Só quando é usada |
| MEMORY.md (memória automática) | O que o Claude aprende sozinho sobre o projeto | As primeiras 200 linhas ou 25 KB, o que vier antes, em toda sessão |
O mesmo escritório, antes e depois da faxina no CLAUDE.md
CLAUDE.md inchado
evite
- Mais de 400 linhas, com o roteiro inteiro da petição inicial
- Regra de citação de jurisprudência carregada até para escrever e-mail
- Instruções antigas que contradizem as novas
CLAUDE.md enxuto
faça assim
- Menos de 200 linhas: nome da sociedade, assinatura e tom
- Roteiro da petição numa skill chamada peticao-inicial
- Regra de jurisprudência em .claude/rules/, só para as peças
Conte as linhas do seu CLAUDE.md. Acima de 200, mova o primeiro procedimento de vários passos para uma skill e confira no /memory o que ficou. Acertou quando o arquivo cair abaixo de 200 linhas e o próximo e-mail ainda sair com a assinatura e os nomes certos.
Montar o CLAUDE.md do escritório em cinco passos
Trinta minutos bastam. O objetivo é um arquivo curto que faça toda sessão nova sair no padrão da empresa.
Passo 1: Abra o Claude Code na pasta onde você trabalha
A pasta de propostas, de relatórios ou de contratos: aquela que você mais usa.
Deu certo quando: o pedido liste os arquivos desta pasta devolve os documentos que você esperava.
Erro comum: abrir na pasta do usuário inteira, e o arquivo de regras ficar no lugar errado.
Passo 2: Digite /init
O Claude lê a pasta e propõe um CLAUDE.md inicial.
Deu certo quando: o arquivo CLAUDE.md aparece na pasta.
Erro comum: aceitar o rascunho sem ler; ele pode supor convenções que não são as suas.
Passo 3: Acrescente as cinco regras de escritório
Nome oficial da empresa, assinatura, tom dos e-mails, formato do relatório e o que nunca dizer a um cliente.
Deu certo quando: o arquivo continua abaixo de 200 linhas.
Erro comum: colar o manual inteiro da empresa; arquivo longo ocupa contexto e reduz a obediência às regras.
Passo 4: Confira no /memory o que ficou carregado
O comando abre os arquivos de memória para leitura e edição.
Deu certo quando: o /memory mostra o CLAUDE.md da pasta com o texto que você escreveu.
Erro comum: editar uma cópia do arquivo em outra pasta, que a sessão nunca lê.
Passo 5: Teste numa sessão nova, com um pedido real
Digite /clear e peça um e-mail de cobrança educada a um cliente.
Deu certo quando: o e-mail sai com a assinatura e o nome da empresa certos, sem você repetir as regras.
Erro comum: testar na mesma conversa em que escreveu as regras, onde o Claude ainda lembra delas pelo histórico.
No fim você tem: um CLAUDE.md com menos de 200 linhas que coloca cada sessão nova no padrão do escritório.
Três mudanças do trimestre mexem no arquivo de regras. Desde a versão 2.1.281, de 23 de setembro de 2026, um projeto sem CLAUDE.md passa a ser lido pelo AGENTS.md, o arquivo de instruções que outras ferramentas, como o Codex, já usam; a escolha fica em Project instructions, no /config. O /doctor propõe cortar do CLAUDE.md o que o Claude consegue deduzir sozinho dos arquivos. E o /doctor prompt-audit aponta instruções escritas para modelos antigos e põe no topo do relatório caminhos e comandos que já não existem e arquivos de instrução que se contradizem.
O CLAUDE.md guarda o que vale sempre; a voz da marca, com exemplos, vocabulário e checklist, ocupa espaço demais para morar ali. O lugar dela é uma skill: uma pasta com um arquivo SKILL.md que o Claude só carrega quando o pedido é escrever ou revisar conteúdo. No CLAUDE.md fica uma linha avisando que todo texto público passa pela skill voz-da-marca. O resultado é o mesmo padrão em todo post, sem pesar nas sessões que tratam de planilha ou de agenda.
Criar a skill de voz da marca para o conteúdo
Separe três textos que a marca aprovou e dois que reprovou. Eles viram os exemplos da skill. Tempo estimado: 40 minutos.
Passo 1: Crie a pasta .claude/skills/voz-da-marca/ no projeto de conteúdo
Na pasta do projeto, a skill vale para todo o time que abrir o mesmo repositório. Em ~/.claude/skills/, vale só para você, em todos os projetos.
Deu certo quando: a pasta existe dentro de .claude/skills/, com o nome em minúsculas e hífen.
Erro comum: criar a pasta fora de .claude/skills/, onde o Claude não procura.
Passo 2: Escreva o SKILL.md com nome, descrição e as regras de voz
A descrição diz quando usar, com os gatilhos: post, legenda, e-mail, anúncio, roteiro. O corpo traz tom, palavras proibidas, estrutura e o checklist final.
Deu certo quando: o arquivo abre com o bloco entre linhas de três hifens e o texto das regras logo abaixo.
Erro comum: descrição vaga, como regras de marca; o Claude decide pela descrição se carrega a skill, e ela só aparece quando chamada pelo nome.
Passo 3: Guarde os exemplos num arquivo ao lado
Salve exemplos.md na mesma pasta, com os textos aprovados e os reprovados, cada um com uma linha de motivo. O SKILL.md cita o arquivo, e o Claude o lê só quando precisa.
Deu certo quando: o SKILL.md continua curto, e os exemplos ficam num arquivo próprio.
Erro comum: colar os exemplos dentro do SKILL.md e fazê-lo crescer a cada campanha.
Passo 4: Teste sem citar a skill
Abra uma sessão nova e peça uma legenda de Instagram para o lançamento do mês.
Deu certo quando: a legenda sai sem as palavras proibidas, com a estrutura da skill e o checklist cumprido.
Erro comum: testar só com /voz-da-marca; a chamada direta funciona mesmo com descrição ruim e esconde o problema.
Passo 5: Meça o uso depois de duas semanas
Rode /skill-doctor e veja quantas vezes a skill foi usada e quanto contexto ocupa.
Deu certo quando: a skill aparece com uso registrado nas semanas de produção.
Erro comum: deixar a skill crescer sem medir; toda skill listada pesa em cada conversa.
No fim você tem: uma skill de voz da marca que entra sozinha em todo pedido de conteúdo e deixa o CLAUDE.md curto.
---
name: voz-da-marca
description: Aplica a voz da marca a qualquer texto público. Use ao escrever ou revisar post, legenda, e-mail de campanha, anúncio, roteiro de vídeo ou página de produto.
---
Tom: direto, caloroso, sem exagero. Frases curtas. Você, nunca senhor ou senhora.
Nunca use: incrível, revolucionário, imperdível, garantido.
Estrutura de post: gancho em uma linha, prova (número ou caso), convite à ação.
Exemplos aprovados e reprovados, com o motivo: veja exemplos.md nesta pasta.
Antes de entregar, confira:
1. Nenhuma palavra da lista proibida.
2. Toda afirmação numérica tem fonte.
3. O convite à ação aponta para um único destino.Coordenadora de conteúdo de uma agência com quatro redatores
Agência de marketing digital
Dor
Cada redator escrevia num tom, e a revisão da coordenadora consumia uma tarde por semana só para padronizar posts do mesmo cliente.
Solução
Uma skill voz-da-marca por cliente, guardada no repositório de cada conta, com exemplos aprovados e reprovados e o checklist que ela aplicava à mão.
Resultado
A revisão passa a tratar de estratégia e de fatos, e o tom chega padronizado no primeiro rascunho.
Cenário construído para fins didáticos. Números não correspondem a cliente específico.
Escolha o cliente ou a marca que mais gera texto por semana e monte a skill com os três exemplos aprovados. Acertou quando um redator que nunca leu o manual da marca pedir um post ao Claude e a coordenação aprovar o texto sem pedir ajuste de tom.
Perguntas frequentes deste capítulo
Quantos arquivos CLAUDE.md posso manter e qual prevalece quando eles se contradizem?
O próprio Claude escreve o CLAUDE.md ou preciso redigir na mão?
O que devo colocar no CLAUDE.md e o que é melhor deixar de fora?
Sou gestor e não programo. Um CLAUDE.md de escritório serve para mim?
O CLAUDE.md também vale no Cowork ou é só do terminal?
Seu caderno neste capítulo
Abrir o caderno completoSelecione um trecho do capítulo para destacar ou anotar. Nos vídeos e áudios, use Anotar este momento. No teclado, selecione com Shift e as setas e use Alt+Shift+D para destacar ou Alt+Shift+N para anotar.
Salvo neste navegador. Entre na sua conta para levar o caderno a outros aparelhos.
Entre na sua conta para compartilhar o que aprendeu e convidar alguém para estudar com você.
Conexões deste capítulo
Veja o que estudar antes e para onde seguir depois, explore os conceitos e compare abordagens em outros cursos. Sugestões marcadas como “sugerido pelo grafo” vêm dos assuntos em comum, não do índice do curso.
Estude antes
- CursoSetup Completo: do zero ao Claude Code
- Veja o que o Claude Code faz antes de instalarsugerido pelo grafoApresenta o conceito “Claude Code”, usado em “Escrever o CLAUDE.md, o manual que o Claude sempre lê”.
- CursoAgentes de código para executivossugerido pelo grafo3 capítulos de “Claude Code CLI: Programação com IA” usam conceitos apresentados em “Agentes de código para executivos”.
- CursoMCP para quem decidesugerido pelo grafo7 capítulos de “Claude Code CLI: Programação com IA” usam conceitos apresentados em “MCP para quem decide”.
Conceitos deste capítulo
O mesmo assunto em outros cursos
- Setup de Vibecoding no MacCLAUDE.md — a memória do Claude sobre vocêExaminar conexões de CLAUDE.md — a memória do Claude sobre você
- Setup Completo: do zero ao Claude CodeRegistre suas preferências uma vez para o Claude lembrar sempreExaminar conexões de Registre suas preferências uma vez para o Claude lembrar sempre
- Skills de IA com Vibecoding e TerminalCLAUDE.md: A Constituição do ProjetoExaminar conexões de CLAUDE.md: A Constituição do Projeto
- Vibecoding para SEOSetup do Ambiente: Claude Code + Cursor em 15 MinutosExaminar conexões de Setup do Ambiente: Claude Code + Cursor em 15 Minutos
Leve uma ideia para a prática
Escolha uma atividade no painel e volte a este curso quando quiser.
Atividades e evolução ficam reunidas no painel da sua conta.