Você abre o Claude Code num projeto .NET que não tocava há uma semana. Digita uma pergunta e o agente responde como se fosse o primeiro dia: não sabe qual é o banco, não sabe como você nomeia variáveis, não sabe que usa xUnit e não NUnit. Resultado: você passa os próximos cinco minutos reexplicando o contexto antes de conseguir qualquer coisa útil.

O CLAUDE.md resolve isso.

O que é o CLAUDE.md

É um arquivo de texto simples que o Claude Code lê automaticamente toda vez que você inicia uma sessão num repositório. Funciona como o "system prompt" do agente para aquele projeto específico.

A documentação oficial chama de "memória de projeto". Na prática, é você dizendo ao agente: essa é a stack, essas são as convenções, esses são os comandos, não faça isso aqui. Uma vez escrito, você para de repetir contexto toda hora.

Sem o arquivo, o Claude Code começa cada sessão do zero. Com ele, age como um dev sênior que já fez onboarding no projeto.

Onde o arquivo fica

Na raiz do repositório, no mesmo nível do .sln ou do diretório src/. O Claude Code procura pelo arquivo ao iniciar e o carrega antes de qualquer interação.

Você também pode ter CLAUDE.md em subdiretórios. Num monorepo com múltiplos serviços, faz sentido ter um na raiz com contexto global e arquivos específicos em cada pasta:

meu-projeto/
├── CLAUDE.md            ← contexto global, lido sempre
├── src/
│   ├── Api/
│   │   └── CLAUDE.md   ← contexto específico da API
│   └── Worker/
│       └── CLAUDE.md   ← contexto específico do worker
├── MinhaSolucao.sln
└── README.md

O Claude Code empilha os arquivos do diretório raiz até onde você está trabalhando. Contexto global mais contexto específico, sem repetição.

Um CLAUDE.md real para projeto ASP.NET Core

Esse é um exemplo funcional para uma API com ASP.NET Core 8, Entity Framework Core, PostgreSQL e xUnit. É o tipo de arquivo que vai em qualquer projeto .NET antes de o Claude Code tocar no código:

# Contexto do Projeto

API de gestão de pedidos. ASP.NET Core 8, Entity Framework Core 8 (Code First),
PostgreSQL 16, xUnit para testes.

## Stack e Versões

- .NET 8 / C# 12
- ASP.NET Core 8 (controllers)
- Entity Framework Core 8 com Npgsql
- PostgreSQL 16 (local via Docker, produção na Render)
- xUnit 2.x + Testcontainers para testes de integração
- FluentAssertions para assertions

## Estrutura de Pastas

src/
  Api/           → endpoints, controllers, middlewares
  Application/   → use cases, DTOs, interfaces
  Domain/        → entidades, value objects, regras de negócio
  Infrastructure → repositórios, EF DbContext, migrations

## Convenções de Código

- Async/await em todos os métodos que acessam banco ou I/O; sufixo Async obrigatório
- Nunca usar .Result ou .Wait() — causa deadlock em ASP.NET Core
- Evitar var quando o tipo não é óbvio pela atribuição
- Sem AutoMapper: mapeamento manual é a convenção do projeto

## Comandos

Rodar testes:          dotnet test
Build:                 dotnet build
Aplicar migrations:    dotnet ef database update --project src/Infrastructure
Nova migration:        dotnet ef migrations add NomeDaMigration --project src/Infrastructure --startup-project src/Api
Subir banco local:     docker compose up -d postgres

## O que Não Fazer

- Não mockar o banco nos testes de integração — usamos Testcontainers com PostgreSQL real
- Não colocar lógica de negócio nos controllers
- Não criar migrations sem revisar o SQL gerado (`dotnet ef migrations script`)

Esse arquivo tem uns 280 tokens. Pouca coisa. Mas o ganho em qualidade das respostas é imediato: o agente para de sugerir .Result, para de propor AutoMapper, entende que migration precisa do --startup-project separado.

O que colocar (e o que não colocar)

Coloque

Stack e versões específicas. "ASP.NET Core 8" é mais útil que "API .NET". O agente adapta sugestões pra versão correta da API e avisa quando uma feature não existe naquela versão.

Comandos não-óbvios. Qualquer projeto tem dotnet build. O que o Claude Code não vai adivinhar é que sua migration precisa de --startup-project, ou que seu Docker Compose se chama compose.dev.yaml e não docker-compose.yml.

Convenções que contradizem o padrão C#. Se o time usa _nomePrivado com underscore, escreva isso. Se você proíbe var, escreva. O agente assume as convenções do C# por padrão; o CLAUDE.md é pra declarar onde você diverge.

O que evitar. A seção "Não Fazer" é frequentemente a mais valiosa. Onde o agente vai escorregar se não for avisado? Mockar banco quando você usa Testcontainers? Colocar lógica no controller? Liste essas armadilhas.

Contexto de negócio em 2-3 frases. "API de gestão de pedidos para varejo" ajuda o Claude Code a nomear variáveis, escrever comentários e sugerir estruturas que fazem sentido para o domínio. Não precisa de mais que isso.

Não coloque

Coisas que estão nos arquivos. Não liste todos os packages do .csproj. O Claude Code lê esse arquivo quando precisa. O CLAUDE.md é para o que não está no código.

Convenções óbvias do C#. "Usar PascalCase para propriedades públicas" é o padrão da linguagem, dispensável. Foco no que diverge do padrão ou no que o agente tipicamente erra.

Documentação funcional. Se você tem um docs/ com specs de negócio, mencione a pasta. Mas não copie o conteúdo lá para o CLAUDE.md: o contexto vira ruído e consome tokens sem retorno proporcional.

CLAUDE.md e consumo de tokens

O arquivo é enviado inteiro em toda sessão. Um arquivo de 500 tokens significa 500 tokens a menos para código e conversa. Na prática, 200-500 tokens é um tamanho bom para a maioria dos projetos .NET.

Mas o custo real não está no tamanho do CLAUDE.md. Está em sessões longas onde o contexto cresce sem controle. Se você ainda não leu sobre isso, o post Como economizar tokens no Claude Code tem as técnicas que mais fazem diferença no dia a dia.

E se você está conectando o agente a ferramentas externas, banco de dados ou APIs via MCP, o guia de MCP para devs explica como configurar sem explodir o contexto.

Commitar ou não commitar?

Commite. O CLAUDE.md deve estar no controle de versão por dois motivos práticos.

Primeiro, qualquer dev do time recebe o mesmo contexto configurado automaticamente ao clonar o repositório. Não depende de ninguém lembrar de "configurar o Claude Code" na mão.

Segundo, o arquivo evolui com o projeto. Quando você muda a stack ou adota uma nova convenção, faz sentido que essa mudança apareça no histórico de commits junto com o código que motivou ela.

A única coisa que fica fora do CLAUDE.md: credenciais, tokens e URLs de produção. Essas vão em variáveis de ambiente ou .env.local. O CLAUDE.md é informação técnica do projeto, não segredo de infraestrutura.

Se você está começando com Claude Code e ainda não tem o agente configurado no seu projeto .NET, o post O que é Claude Code e como usar no projeto C# .NET cobre os primeiros passos antes de criar o CLAUDE.md.