O que é o Arquivo CLAUDE.md e Como Criar o Seu [Com Templates]

Se você acabou de instalar o Claude Code e está tentando entender como tirar o máximo da ferramenta, existe uma coisa que vai mudar completamente a qualidade dos resultados: o arquivo CLAUDE.md.

É a configuração mais poderosa do Claude Code — e a mais ignorada por quem está começando.

Neste guia você vai entender o que é, por que importa, o que colocar (e o que não colocar), onde o arquivo deve ficar e vai sair daqui com templates prontos para copiar e adaptar ao seu projeto.

O que é o arquivo CLAUDE.md?

O CLAUDE.md é um arquivo em formato Markdown que o Claude Code lê automaticamente no início de cada sessão. Pense nele como um briefing permanente que você entrega ao Claude toda vez que abre o terminal.

O Claude Code é um agente sem memória persistente. Cada sessão começa do zero — ele não lembra o que você discutiu ontem, não sabe como o seu projeto está organizado, não conhece suas convenções de código. O CLAUDE.md resolve exatamente isso.

Com um bom CLAUDE.md, você não precisa repetir nas mesmas instruções a cada conversa. O Claude já sabe:

Quais comandos usar para build, testes e lint
Como o projeto está estruturado
Quais convenções de código seguir
Quais ferramentas e padrões arquiteturais você usa
O que fazer e o que absolutamente não fazer

É a diferença entre um estagiário que você precisa briefar do zero toda manhã e um dev sênior que já internalizou o projeto.

Por que o CLAUDE.md é tão importante?

O Claude Code precisa de contexto para ser útil. Sem contexto, ele faz suposições — e suposições nem sempre acertam o seu caso específico.

Exemplos do que acontece sem um bom CLAUDE.md:

Você usa var em C# apenas para tipos óbvios, mas o Claude usa em todo lugar
Você tem um padrão de response wrapper nas suas APIs, mas o Claude retorna respostas diretas
Você usa xUnit para testes, mas o Claude escreve com NUnit
Você tem um script específico para rodar migrations, mas o Claude tenta rodar outro comando

Cada uma dessas divergências gera retrabalho. O CLAUDE.md elimina isso antes de acontecer.

A documentação oficial da Anthropic diz: “O CLAUDE.md dá ao Claude contexto persistente que ele não consegue inferir apenas pelo código.” É exatamente isso.

Onde colocar o arquivo CLAUDE.md

O Claude Code suporta múltiplos locais para o arquivo, e cada um tem um propósito diferente:

1. Global: `~/.claude/CLAUDE.md`

Aplica-se a todas as sessões do Claude Code, em qualquer projeto. Use para preferências pessoais que você quer em todo lugar — seu estilo de código preferido, como você quer que o Claude se comunique, suas ferramentas pessoais.

~/.claude/CLAUDE.md

Mantenha esse arquivo curto — no máximo 15 linhas. Ele carrega em todos os projetos, então só coloque coisas verdadeiramente universais.

2. Projeto: `./CLAUDE.md`

O mais importante. Fica na raiz do projeto e é commitado no Git para que toda a equipe tenha o mesmo comportamento. Contém comandos do projeto, estrutura de pastas, convenções de código e regras específicas.

meu-projeto/
├── CLAUDE.md          ← commitar no Git
├── CLAUDE.local.md    ← adicionar ao .gitignore
├── src/
└── ...

3. Local: `./CLAUDE.local.md`

Suas preferências pessoais específicas do projeto, que não devem ser compartilhadas com a equipe. Adicione ao .gitignore. Útil para paths locais, credenciais de ambiente de desenvolvimento, notas pessoais.

4. Subdiretórios

Em monorepos, você pode ter um CLAUDE.md em cada pacote/serviço. O Claude carrega automaticamente o arquivo do diretório em que está trabalhando. Poderoso para repositórios com múltiplas linguagens ou stacks.

O que colocar no CLAUDE.md

A regra de ouro antes de adicionar qualquer coisa: “Se eu remover esta linha, o Claude vai cometer erros?” Se a resposta for não, não coloque.

O CLAUDE.md tem um limite prático de atenção. Arquivos com mais de 80 linhas começam a perder eficiência — o Claude passa a ignorar partes das instruções de forma aleatória. Menos é mais.

As 4 seções essenciais

1. Comandos do projeto

O que o Claude precisa executar: build, testes, lint, migrations, dev server. Sem isso, ele vai tentar adivinhar — e vai errar.

## Comandos
- Build: `dotnet build`
- Testes: `dotnet test`
- Lint: `dotnet format --verify-no-changes`
- Migrations: `dotnet ef database update`
- Dev: `dotnet run --project src/Api`

2. Estrutura do projeto

Onde as coisas ficam. Especialmente útil em projetos maiores onde a estrutura não é óbvia.

## Estrutura
- `src/Api/` — controllers e middleware
- `src/Application/` — handlers MediatR, DTOs
- `src/Domain/` — entidades e value objects
- `src/Infrastructure/` — repositórios EF Core, serviços externos
- `tests/` — projetos de teste xUnit

3. Padrões e convenções de código

Decisões técnicas que o Claude não consegue inferir só de ler o código — ou que você quer reforçar explicitamente.

## Padrões
- CQRS com MediatR — handlers em Application/
- Repositories em Infrastructure/, interfaces em Domain/
- Nunca expor entidades diretamente nas APIs — sempre usar DTOs
- Usar `var` apenas quando o tipo é óbvio na mesma linha
- Testes: Arrange/Act/Assert com comentários de seção

4. Regras importantes

O que o Claude absolutamente não deve fazer. Seja específico — regras vagas são ignoradas.

## Regras
- NUNCA modificar arquivos de migration — criar nova migration sempre
- NUNCA usar Console.WriteLine — usar ILogger<T>
- NUNCA commitar diretamente na main — criar branch sempre

O que NÃO colocar no CLAUDE.md

Tão importante quanto saber o que incluir é saber o que evitar:

❌ Instruções de personalidade — “Seja um desenvolvedor sênior”, “Pense passo a passo”. O Claude Code já tem instruções de sistema robustas. Você está desperdiçando espaço.

❌ Coisas que o Claude aprende sozinho — O Claude Code tem memória automática em ~/.claude/projects/. Ele aprende os comandos de build e padrões que descobre durante as sessões. Não precisa repetir no CLAUDE.md.

❌ Regras de linter — Use um linter de verdade. eslint, dotnet format, ruff. São determinísticos e não ocupam espaço no contexto.

❌ Tudo que não é universal — Se uma instrução só se aplica a 10% das tarefas, não coloque no CLAUDE.md. Use skills ou comandos slash para isso.

Como gerar o CLAUDE.md automaticamente

O Claude Code tem um comando que analisa o seu projeto e gera um CLAUDE.md inicial automaticamente:

bash

/init

Execute esse comando na raiz do projeto. O Claude vai ler a estrutura de diretórios, detectar o sistema de build, frameworks de teste e padrões de código, e gerar um arquivo inicial. É um ótimo ponto de partida para refinar.

Templates prontos para copiar

Template 1 — ASP.NET Core / C#

# [Nome do Projeto]

API REST com ASP.NET Core 8, EF Core, MediatR.

## Comandos
- Build: `dotnet build`
- Testes: `dotnet test --no-build`
- Lint: `dotnet format --verify-no-changes`
- Migrations: `dotnet ef database update --project src/Infrastructure`
- Dev: `dotnet run --project src/Api`

## Estrutura
- `src/Api/` — Controllers, Middleware, Program.cs
- `src/Application/` — Commands, Queries, Handlers (MediatR)
- `src/Domain/` — Entidades, Value Objects, interfaces de repositório
- `src/Infrastructure/` — EF Core, repositórios, serviços externos
- `tests/Unit/` — testes xUnit unitários
- `tests/Integration/` — testes de integração com TestContainers

## Padrões
- CQRS com MediatR — sem lógica de negócio em controllers
- Repositórios em Infrastructure/, interfaces em Domain/
- Responses de API sempre via Result<T> pattern
- `var` apenas quando o tipo é óbvio na mesma linha
- Testes: padrão Arrange/Act/Assert com comentários de seção

## Regras
- NUNCA modificar migrations existentes — sempre criar nova
- NUNCA usar Console.WriteLine — usar ILogger<T> injetado
- NUNCA retornar entidades diretamente — sempre DTOs/ViewModels
- Antes de qualquer commit: `dotnet format && dotnet test`

Template 2 — Node.js / TypeScript

# [Nome do Projeto]

API REST com Node.js, TypeScript, Express e PostgreSQL (Prisma).

## Comandos
- Dev: `npm run dev`
- Build: `npm run build`
- Testes: `npm test`
- Lint: `npm run lint`
- Migrations: `npx prisma migrate dev`

## Estrutura
- `src/routes/` — definição de rotas Express
- `src/controllers/` — handlers de requisição
- `src/services/` — lógica de negócio
- `src/repositories/` — acesso a dados (Prisma)
- `src/middlewares/` — auth, validação, erros
- `tests/` — Jest, espelhando estrutura de src/

## Padrões
- TypeScript strict mode — proibido usar `any`
- Respostas de API: `{ data, error, status }`
- Usar logger customizado (`src/utils/logger.ts`) — não console.log
- Validação de entrada com Zod
- Erros tratados por middleware global em `src/middlewares/errorHandler.ts`

## Regras
- NUNCA expor stack traces em respostas de produção
- NUNCA commitar .env — usar .env.example atualizado
- Executar `npm run lint && npm test` antes de commitar

Template 3 — React / Next.js (Frontend)

# [Nome do Projeto]

Frontend React com Next.js 14 (App Router), TypeScript e Tailwind.

## Comandos
- Dev: `npm run dev`
- Build: `npm run build`
- Testes: `npm test`
- Lint: `npm run lint`
- Type check: `npx tsc --noEmit`

## Estrutura
- `app/` — rotas Next.js App Router
- `components/ui/` — componentes reutilizáveis (shadcn/ui base)
- `components/features/` — componentes específicos de feature
- `lib/` — utilitários, helpers, configurações
- `hooks/` — custom React hooks
- `types/` — TypeScript types e interfaces globais

## Padrões
- TypeScript strict — sem `any`
- Componentes funcionais com hooks — sem class components
- Estado global: Zustand (ver `lib/store/`)
- Fetch de dados: React Query para estado de servidor
- Estilização: Tailwind CSS — sem CSS modules, sem styled-components
- Imagens: sempre via `next/image`

## Regras
- NUNCA usar `useEffect` para fetch — usar React Query
- NUNCA hard-codar strings de UI — usar arquivo de constantes
- Executar `npm run lint && npx tsc --noEmit` antes de commitar

Template 4 — Global (`~/.claude/CLAUDE.md`)

# Preferências Pessoais

## Comunicação
- Responder em português brasileiro
- Ser direto — sem introduções desnecessárias
- Mostrar o raciocínio quando a decisão for não-óbvia

## Git
- Criar branch antes de qualquer mudança de feature
- Mensagens de commit em inglês, formato: `tipo: descrição curta`
- Nunca commitar diretamente na main/master

## Código
- Preferir clareza a esperteza
- Adicionar comentário quando o "por quê" não é óbvio pelo código

Dica avançada: importar arquivos no CLAUDE.md

O CLAUDE.md suporta importar outros arquivos usando a sintaxe @path/to/arquivo. Isso é útil para manter o arquivo principal enxuto e delegar detalhes para arquivos específicos:

## Comandos
- Build: `dotnet build`
- Testes: `dotnet test`
- Lint: `dotnet format --verify-no-changes`
- Migrations: `dotnet ef database update`
- Dev: `dotnet run --project src/Api`

O Claude vai carregar os arquivos referenciados automaticamente. Útil para projetos maiores onde você quer separar por contexto sem inflar o arquivo principal.

Mantendo o CLAUDE.md saudável ao longo do tempo

O CLAUDE.md não é um documento que você escreve uma vez e esquece. Trate-o como código: revise, podre e teste regularmente.

Sinais de que o arquivo precisa de atenção:

O Claude continua cometendo um erro que você já documentou — provavelmente o arquivo está longo demais e a instrução está sendo ignorada
O Claude faz perguntas que já estão respondidas no arquivo — a instrução pode estar ambígua
O arquivo tem mais de 80 linhas — hora de cortar

Hábito recomendado: Sempre que o Claude cometer um erro recorrente, adicione uma linha específica ao CLAUDE.md para prevenir. O arquivo vai crescer organicamente a partir de problemas reais, o que é muito mais valioso do que um arquivo escrito especulativamente.

Perguntas Frequentes

O CLAUDE.md é obrigatório para usar o Claude Code? Não. Mas sem ele, o Claude começa cada sessão sem nenhum contexto do seu projeto. Você vai repetir as mesmas informações toda vez. Um CLAUDE.md bem feito é o investimento de 30 minutos que economiza horas ao longo do tempo.

Qual o tamanho ideal do CLAUDE.md? Entre 30 e 60 linhas para um projeto típico. Acima de 80 linhas, a qualidade de seguimento das instruções começa a cair. Se o arquivo está crescendo muito, considere mover parte do conteúdo para skills ou regras em .claude/rules/.

Posso ter CLAUDE.md em múltiplos diretórios no mesmo projeto? Sim. Em monorepos isso é especialmente útil. Coloque instruções específicas de cada pacote no diretório correspondente. O Claude carrega automaticamente o arquivo do diretório em que está trabalhando.

O CLAUDE.md funciona com outros editores além do terminal? O CLAUDE.md é específico do Claude Code. Ferramentas como Cursor e Windsurf têm arquivos equivalentes (.cursorrules, AGENTS.md) com propósito similar.

Devo commitar o CLAUDE.md no Git? Sim, o ./CLAUDE.md do projeto deve ser commitado para que toda a equipe se beneficie. Para configurações pessoais, use ./CLAUDE.local.md e adicione ao .gitignore.

Conclusão

O CLAUDE.md é a diferença entre um Claude Code que trabalha com você e um que trabalha contra você. Com um arquivo bem feito, você elimina retrabalho, mantém consistência de código e aproveita muito mais do potencial da ferramenta.

O caminho mais rápido para começar: rode /init no seu projeto agora, revise o arquivo gerado e adicione as regras específicas que o Claude não consegue inferir sozinho. Vai levar 20 minutos e vai economizar muito mais do que isso.

👉 Quer ver mais sobre como configurar o Claude Code do jeito certo? Leia o Guia Completo →

Receba um template de CLAUDE.md pronto toda semana na newsletter do Código Agente — direto no seu email, sem enrolação.

📧 Gostou do conteúdo? Assine a newsletter do Código Agente e receba uma dica prática de Claude Code toda semana — templates, workflows e novidades do ecossistema em PT-BR.

👉 Assinar agora →