Claude no .NET - Dissecando o CLAUDE.md

  Hoje veremos o que é , como funciona e como usar o arquivo CLAUDE.md.

Se você está usando IA para desenvolver aplicações .NET, provavelmente já percebeu que a qualidade das respostas depende muito do contexto fornecido.

É exatamente aqui que entra o arquivo CLAUDE.md.



O que é o CLAUDE.md e por que ele é importante?

O CLAUDE.md é um arquivo Markdown especial que se torna parte do prompt do sistema do Claude. Sempre que você inicia uma sessão do Claude Code em um diretório que contém esse arquivo, seu conteúdo é carregado automaticamente no contexto.

Pense nisso como escrever a documentação de integração para um novo membro da equipe — só que este membro da equipe:

- Tem memória perfeita durante a sessão
 - Segue as instruções com precisão
 - Nunca se irrita quando você se repete
 - Pode armazenar 1.000.000 tokens de contexto (Sonnet 4.6 e o Opus 4.6 no plano Max)

Sem o CLAUDE.md, o Claude inicia cada sessão às cegas. Ele não conhece a estrutura do seu projeto, suas convenções de codificação, seus padrões preferidos ou mesmo como executar seus testes. Você acaba repetindo o mesmo contexto várias vezes.

Com um CLAUDE.md bem elaborado, o Claude começa a funcionar imediatamente. Ele conhece sua arquitetura, respeita seus padrões e toma decisões alinhadas com sua base de código desde o primeiro prompt.

Nota: De acordo com a documentação oficial do Claude Code da Anthropic, os arquivos CLAUDE.md devem ser "aprimorados como qualquer outro prompt usado com frequência". Equipes que iteram em seus arquivos CLAUDE.md obtêm resultados significativamente melhores do que aquelas que os configuram e os esquecem.

Hierarquia de Memória do Código Claude - Como o Contexto é Carregado

Antes de escrevermos uma única linha, você precisa entender o sistema de memória do Código Claude. Ele é hierárquico, e saber como funciona ajuda você a organizar suas instruções de forma eficaz.

Níveis de Memória (Prioridade Mais Alta para Mais Baixa)

Política Empresarial - Regras de nível organizacional (se estiver usando o Claude para Equipes)
Memória do Projeto - Arquivo CLAUDE.md na raiz do seu repositório
Preferências Pessoais - Arquivo CLAUDE.local.md
Regras do Projeto - Arquivos no diretório .claude/rules/
Memória do Usuário - Arquivo ~/.claude/CLAUDE.md para preferências globais pessoais

Ponto-chave: Todos os níveis se combinam - eles não se substituem. Regras mais específicas têm prioridade em caso de conflito. Isso significa que você pode ter preferências globais no seu diretório pessoal e configurações específicas do projeto em cada repositório.

Localização dos arquivos e seu propósito

Localização Propósito Commit ou Git ?
./.CLAUDE.md Instruções para todo o projeto
compartilhadas com a equipe		 Sim
./.CLAUDE.local.md Suas preferências pessoais de projeto Não
./.claude/rules/*md Regras específicas para tarefas ou pastas Sim
~/.claude/CLAUDE.md Preferências globais para todos os projetos N/A

Sintaxe de Importação

Para projetos maiores, você pode dividir as instruções em vários arquivos usando a sintaxe de importação:

@.claude/rules/architecture.md
@.claude/rules/testing.md
@.claude/rules/api-conventions.md

Isso mantém seu arquivo CLAUDE.md raiz organizado, ao mesmo tempo que permite organizar instruções detalhadas em arquivos específicos. As importações são resolvidas recursivamente em até 5 níveis de profundidade.

Dica profissional: Use importações para referenciar arquivos nos diretórios pessoais dos membros da equipe para preferências individuais que não devem ser incluídas no commit:
@~/personal-dotnet-preferences.md

A Estrutura:  O QUE-PORQUÊ-COMO

A Anthropic recomenda organizar seu CLAUDE.md em três camadas. Essa estrutura garante que Claude tenha o contexto completo, sem informações desnecessárias.

O QUE - Seu Conjunto de Tecnologias e Estrutura

Informe a Claude exatamente quais tecnologias você está usando e como o projeto está organizado.

## Tecnologias
- .NET 10, APIs mínimas da ASP.NET Core
- Entity Framework Core 10 com PostgreSQL
- Mediator para o padrão CQRS (gerado a partir do código-fonte)
- FluentValidation para validação de requisições
- Scalar para documentação da API (OpenAPI)

## Estrutura do Projeto
- `src/Api/` - Ponto de entrada, endpoints, middleware
- `src/Application/` - Comandos, consultas, handlers, DTOs
- `src/Domain/` - Entidades, objetos de valor, eventos de domínio
- `src/Infrastructure/` - EF Core, integrações externas
- `tests/` - Testes unitários e de integração

O PORQUÊ - Propósito e Decisões Arquitetônicas

Explique o raciocínio por trás da sua arquitetura. Isso ajuda Claude a tomar decisões que estejam alinhadas com a sua filosofia de projeto.

## Filosofia de Arquitetura
Seguimos a Arquitetura Limpa com separação CQRS:
- **Domain** não possui dependências - pura lógica de negócios
- **Application** orquestra casos de uso por meio de manipuladores Mediator
- **Infrastructure** implementa interfaces definidas na Aplicação
- **API** é enxuta - apenas definições de endpoints e injeção de dependência (DI)

Por que CQRS? Precisamos de modelos de leitura/escrita diferentes para otimizar o desempenho.

Por que Mediator ? Desacopla os manipuladores da camada HTTP, permite comportamentos em pipeline e é gerado a partir do código-fonte para melhor desempenho.

O COMO - Comandos e Regras de Fluxo de Trabalho

Documente os comandos que Claude deve conhecer e as regras de fluxo de trabalho que você espera que ele siga.

## Comandos
- Build: `dotnet build`
- Test: `dotnet test --no-build`
- Run: `dotnet run --project src/Api`
- Migrations: `dotnet ef migrations add <Nome> --project src/Infrastructure --startup-project src/Api`

## Regras de Fluxo de Trabalho
- SEMPRE crie uma branch de recurso antes de fazer alterações
- Execute `dotnet test` após cada implementação
- Nunca modifique arquivos em `src/Domain/` sem aprovação explícita
- Mantenha os commits atômicos - uma alteração lógica por commit

O que incluir (e o que NÃO incluir)

É aqui que a maioria dos desenvolvedores erra. Ou incluem muito pouco (Claude opera às cegas) ou muito (desperdiçando tokens de contexto com detalhes irrelevantes).

Inclua o seguinte:

Tecnologias e versões - Seja específico: “Entity Framework Core 10”, não apenas “EF Core”
Estrutura do projeto - Mapeie as pastas para suas respectivas finalidades
Comandos comuns - Build, test, run, migrations
Convenções de codificação - Nomenclatura, padrões, preferências de estilo
Padrões utilizados - Mediator, Result pattern, CQRS
Padrões NÃO utilizados - Igualmente importante para evitar sugestões indesejadas
Terminologia de domínio - Termos de negócio que se relacionam com entidades de código
Instruções de teste - Como executar testes, quais frameworks são utilizados
Fluxo de trabalho do repositório - Nomenclatura de branches, convenções de commits, processo de Pull Requests

NÃO inclua:

Segredos ou credenciais - Nunca inclua chaves de API, strings de conexão ou senhas
Regras de estilo de código que os linters processam - Utilize Prettier/ESLint/formato dotnet
Conhecimento óbvio do framework - Claude sabe como o ASP.NET Core funciona
Documentação excessiva - Inclua links para a documentação em vez de copiar o conteúdo
Contexto histórico - Concentre-se no estado atual, não no histórico do projeto

IMPORTANTE: Cada palavra em CLAUDE.md consome tokens de contexto. Mantenha o arquivo com menos de 200 linhas. Idealmente, busque um arquivo raiz com 50 a 100 linhas, incluindo as importações para as seções detalhadas.

O Modelo Completo de CLAUDE.md para .NET

Aqui está uma sugestão de um modelo para projetos .NET. Você pode ajustar para se adequar à sua pilha de tecnologias e convenções específicas. (Sistema de Vendas)

# CLAUDE.md - [Nome do Projeto]

## Visão Geral
[Descrição em uma frase do que este projeto faz]

## Tecnologias Utilizadas
- .NET 10, APIs Mínimas do ASP.NET Core
- Entity Framework Core 10 com PostgreSQL
- Mediator para CQRS (gerado a partir do código-fonte, https://github.com/martinothamar/Mediator)
- FluentValidation para validação de requisições
- Scalar para documentação OpenAPI
- xUnit + FluentAssertions para testes

## Estrutura do Projeto
- `src/Api/` - Endpoints, middleware, configuração de Injeção de Dependência (DI)
- `src/Application/` - Comandos, consultas, manipuladores, validadores
- `src/Domain/` - Entidades, objetos de valor, enums, eventos de domínio
- `src/Infrastructure/` - EF Core, serviços externos, repositórios
- `tests/UnitTests/` - Testes de domínio e de aplicação
- `tests/IntegrationTests/` - Testes de API e banco de dados

## Comandos
- Construir: `dotnet build`
- Testar: `dotnet test`
- Executar API: `dotnet run --project src/Api`
- Adicionar Migração: `dotnet ef migrations add <Nome> -p src/Infrastructure -s src/Api`
- Atualizar Banco de Dados: `dotnet ef database update -p src/Infrastructure -s src/Api`
- Formatar: `dotnet format`

## Regras de Arquitetura
- A camada de domínio NÃO possui dependências externas
- A camada de aplicação define as interfaces, a infraestrutura as implementa
- Todo o acesso ao banco de dados passa pelo DbContext do EF Core (sem padrão de repositório)
- Usar Mediator para todo o tratamento de comandos/consultas
- A camada de API é enxuta - apenas definições de endpoints

## Convenções de Código

### Nomenclatura
- Comandos: `Create[Entity]Command`, `Update[Entity]Command`
- Consultas: `Get[Entity]Query`, `List[Entities]Query`
- Manipuladores: `[Command/Query]Handler`
- DTOs: `[Entity]Dto`, `Create[Entity]Request`

### Padrões que usamos
- Construtores primários para injeção de dependência
- Registros para DTOs e comandos
- Padrão Result<T> para tratamento de erros (sem exceções para controle de fluxo)
- Namespaces com escopo de arquivo
- Sempre passe CancellationToken para métodos assíncronos

### Padrões que NÃO usamos (Nunca sugerimos)
- Padrão Repository (use o EF Core diretamente)
- AutoMapper (escreva mapeamentos explícitos)
- Exceções para erros de lógica de negócios
- Procedimentos armazenados

## Validação
- Toda a validação de requisições em validadores FluentValidation
- Validadores registrados automaticamente via varredura de assemblies
- A validação é executada no pipeline do Mediator Comportamento

## Testes
- Testes unitários: Lógica de domínio e manipuladores
- Padrão Triple A: Use o padrão AAA: Arrange, Act e Assert
- Testes de integração: Teste completo dos endpoints da API com WebApplicationFactory
- Use FluentAssertions para asserções legíveis
- Nomenclatura de testes: `[Método]_[Cenário]_[ResultadoEsperado]`

## Fluxo de trabalho Git
- Nomenclatura de branches: `feature/`, `bugfix/`, `hotfix/`
- Formato de commit: `tipo: descrição` (feature, fix, refactor, test, docs)
- Sempre crie uma branch antes de fazer alterações
- Execute os testes antes de fazer o commit

## Termos de Domínio
- Pedido → Entidade `Order`
- Cliente → Entidade `Customer`
- Item do Pedido → Entidade `OrderItem`
- Cancelamento → Comando `CancelOrderCommand`
- Total do Pedido → Propriedade `Order.TotalAmount`

Obs: Nesta sugestão não recomandamos usar o padrão Repository mas isso pode ser diferente para o seu cenário.

Organizando o CLAUDE.md para Grandes Projetos .NET

Para soluções corporativas com várias equipes ou módulos, um único arquivo CLAUDE.md torna-se difícil de gerenciar. Use o diretório .claude/rules/ para organizar as instruções.

Estrutura de Diretórios (Para um projeto específico)

.claude/
├── rules/
│ ├── architecture.md # Regras e dependências das camadas
│ ├── api-conventions.md # Padrões de endpoints
│ ├── testing.md # Padrões e nomenclatura de testes
│ ├── database.md # Convenções do EF Core
│ └── modules/
│ ├── identity.md # Especificidades do módulo Identity
│ ├── catalog.md # Especificidades do módulo Catalog
│ └── orders.md # Especificidades do módulo Orders

Regras com Escopo usando Frontmatter

Você pode restringir o escopo das regras a caminhos específicos usando frontmatter YAML:

---
paths:
  - src/Modules/Identity/**
  - tests/**/Identity*
---

# Regras do Módulo de Identidade

Este módulo gerencia autenticação e autorização.

## Padrões
- Usar o ASP.NET Core Identity para gerenciamento de usuários
- Tokens JWT para autenticação de API
- Rotação de token de atualização habilitada
- Regras de senha definidas em IdentitySettings

## Testes
- Simular o serviço IIdentityService para testes unitários
- Usar usuários de teste definidos em IdentityTestData

Erros comuns e como evitá-los

Erro 1: Usar o CLAUDE.md como um linter

Errado:

- Use 4 espaços para indentação
- Sempre adicione vírgulas no final
- Comprimento máximo da linha: 120 caracteres

Correto:

- Criar um arquivo .editorconfig na raiz da solução definindo regras como indentação, uso de var, espaçamento e convenções de código
- Executar dotnet format no projeto para aplicar automaticamente as regras de estilo definidas no .editorconfig

Erro 2: Incluir tudo do /init

O comando /init gera um CLAUDE.md inicial ao analisar seu projeto. Sempre revise e reduza o conteúdo. O conteúdo gerado automaticamente geralmente inclui:

- Descrições redundantes
- Padrões de framework óbvios
- Listagens de pastas excessivas

Mantenha apenas o que é exclusivo do SEU projeto.

Erro 3: Esquecer de atualizar

Seu CLAUDE.md deve evoluir com sua base de código. Quando você:

Adicionar uma nova biblioteca → Atualize a pilha de tecnologias
Alterar os padrões de arquitetura → Atualize as regras
Adicionar novos módulos → Adicione regras específicas do módulo

Trate-o como documentação viva, não como uma configuração única.

Erro 4: Duplicar a documentação oficial

Errado:

## Como o Mediator funciona
O Mediator é uma biblioteca que implementa o padrão Mediator...
[500 palavras explicando o Mediator]

Correto:

## Utilização do Mediator
Utilizamos o Mediator para CQRS. Consulte: https://github.com/martinothamar/Mediator

Nossas convenções:
- Um manipulador por arquivo
- Manipuladores na mesma pasta que o comando/consulta
- Comportamentos do pipeline: Validação → Registro → Transação

Resultados Reais: Antes e Depois

DVejamos agora a diferença que um bom CLAUDE.md faz.

Antes do CLAUDE.md

Prompt: “Adicione um novo endpoint para criar um produto”

Resposta do Claude: Cria um controlador com o padrão Repository, adiciona a configuração do AutoMapper, coloca a validação no controlador e ignora os padrões existentes.

Resultado: 30 minutos ajustando as suposições do Claude para corresponder à sua arquitetura.

Depois do CLAUDE.md

Prompt: “Adicione um novo endpoint para criar um produto”

Resposta do Claude: Cria um CreateProductCommand com Mediator, adiciona o validador FluentValidation, usa seus padrões DTO, segue sua estrutura de pastas e até cria a branch primeiro.

Resultado: Código que corresponde perfeitamente à sua base de código. Mescle e siga em frente.

Comparando o CLAUDE.md com outras ferramentas de IA

Se você já usou outros assistentes de codificação com IA, veja como o CLAUDE.md se compara a arquivos de contexto de projeto semelhantes.

Ferramenta Arquivo Principais diferenças
Claude Code CLAUDE.md Memória hierárquica, suporte a importações e regras com escopo por diretório
Github Copilot github/copilot-instructions Instruções versionadas no repositório, foco em contexto de código e integração com GitHub
Gemini CLI GEMINI.md Personaliza o comportamento do agente para a pasta específica onde está localizado
Codex AGENTS.md Atual como guia de contexto e oriente a IA a
trabalhar com o projeto

O que torna o CLAUDE.md diferente:

Carregamento hierárquico - Combina os níveis de usuário, projeto e regras
Sintaxe de importação - Referencie outros arquivos com @caminho/para/arquivo.md
Regras com escopo - Aplique regras a caminhos específicos por meio do frontmatter
Integração com o contexto do modelo – Permite fornecer instruções mais ricas dentro do limite de contexto da IA (isso pode variar conforme o modelo)

Dicas práticas

1. Atualize o arquivo CLAUD.md em tempo real

Durante uma sessão, peça ao Claude diretamente na conversa:

"Adicione ao CLAUDE.md: sempre usar Result<T> em vez de exceções"

Ou use /memory para abrir e editar os arquivos de memória manualmente;

Ou edite o CLAUDE.md diretamente como qualquer outro arquivo do projeto;

O Claude adiciona isso ao seu arquivo CLAUDE.md sem interromper seu fluxo de trabalho.

2. Documente seus comandos "não óbvios"

Todo projeto tem comandos que não são óbvios. Documente-os:

## Comandos Não Óbvios
- Reiniciar o banco de dados de teste: `docker-compose down -v && docker-compose up -d db`
- Gerar o cliente: `npm run generate-api-client --prefix src/Web`
- Limpar o Redis: `docker exec redis redis-cli FLUSHALL`

3. Inclua soluções alternativas para erros

Se o seu projeto tiver problemas conhecidos ou soluções alternativas, documente-os:

## Problemas Conhecidos e Soluções Alternativas
- A migração do EF Core falha no Mac M1: Adicione a flag `--runtime osx-arm64`
- O hot reload quebra o SignalR: Reinicie o `dotnet watch` após alterações no hub
- Os testes atingem o tempo limite na primeira execução: Execute `dotnet build` primeiro para aquecer

4. Exemplos de Código Canônico de Referência

Em vez de explicar padrões em prosa, aponte para exemplos de código existentes:

## Exemplos de código
- Nova implementação de comando: Consulte `src/Application/Products/Commands/CreateProduct/`
- Padrão de teste de integração: Consulte `tests/IntegrationTests/Products/CreateProductTests.cs`
- Endpoint com autenticação: Consulte `src/Api/Endpoints/Orders/CreateOrderEndpoint.cs`

Isso utiliza menos tokens e mostra padrões reais do seu código.

5. Especifique os diretórios de trabalho para os comandos
Os comandos que precisam ser executados a partir de diretórios específicos devem indicar isso:

## Comandos
- Testes de API: `dotnet test` (executar a partir de `tests/Api.IntegrationTests/`)
- Gerar migrações: `dotnet ef migrations add <Nome>` (executar a partir da raiz da solução)
- Compilação do frontend: `npm run build` (executar a partir de `src/Web/`)

Guia Rápido: Lista de Verificação do CLAUDE.md

Antes de enviar seu CLAUDE.md, verifique:

- A pilha de tecnologias com as versões específicas listadas
- A estrutura do projeto com a finalidade de cada pasta
- Os comandos de compilação, teste e execução
- A filosofia da arquitetura (o porquê, e não apenas o quê)
- As convenções de nomenclatura para seus padrões
- Os padrões que você usa E os padrões que você evita
- O fluxo de trabalho do Git e a nomenclatura de branches
- A terminologia do domínio mapeada para o código
- Sem segredos, credenciais ou strings de conexão
- Menos de 200 linhas (consulte a documentação para obter detalhes)
- Testado com um prompt real para verificar a eficácia

Conclusão:

O uso do CLAUDE.md vai muito além de uma simples configuração — ele se torna uma peça estratégica para alinhar a IA com a arquitetura, padrões e decisões reais do seu projeto.

Quando bem estruturado, reduz drasticamente retrabalho, melhora a qualidade do código gerado e transforma a IA em um verdadeiro membro produtivo da equipe.

Em vez de lutar contra suposições genéricas, você passa a orientar o agente com contexto preciso, garantindo consistência, escala e velocidade no desenvolvimento.

E estamos conversados...  

'Porque éreis como ovelhas desgarradas; mas agora tendes voltado ao Pastor e Bispo das vossas almas.'
1 Pedro 2:25

Referências:

José Carlos Macoratti