Usando o CLAUDE.md em projetos .NET para otimizar o uso da IA

Este artigo mostra como usar o Claude Code junto com o arquivo CLAUDE.md para integrar IA em soluções .NET de forma segura e previsível — sem quebrar arquitetura, pipelines de build, testes automatizados e padrões já consolidados no projeto.

Será que existe uma forma prática de integrar a IA em soluções .NET sem quebrar arquitetura, pipelines de build, testes automatizados e padrões já consolidados no projeto ?

Neste artigo estamos focando no Claude e no uso do arquivo CLAUDE.md. Lembrando que Claude é uma família de modelos LLMs: Haiku (rápido e barato), Sonnet(equilibrado) e Opus(mais poderoso e caro)

O problema não é que o Claude (ou qualquer IA) seja ruim com .NET.
O problema não é a capacidade do Claude, o problema é que ele não conhece o contexto do seu projeto.

Quando pedimos para a IA “criar um endpoint” ou “refatorar um serviço”, ela responde com confiança — mas frequentemente erra o contexto.

No mundo real de projetos .NET, isso aparece assim:

- Cria controllers ignorando o padrão já usado (Minimal API vs Controller)
- Ignora separação em camadas (Application, Domain, Infrastructure)
- Usa EF Core de forma inconsistente com o projeto
- Quebra contratos já definidos entre APIs e serviços
- Ignora validações, handlers ou padrões como MediatR
- Não respeita o fluxo de build, testes e CI/CD

Isso não é falta de capacidade. É falta de contexto.

Um desenvolvedor .NET quando entra em um projeto novo também sofre:

- Precisa entender a solução (.sln)
- Descobrir como os projetos se relacionam
- Entender convenções (nomes, pastas, padrões)
- Aprender como rodar, testar e publicar

A IA passa exatamente pelo mesmo problema — só que em segundos.

A solução é simples e extremamente eficaz:  Definir um único arquivo que explica como o projeto funciona de verdade.

Esse arquivo é o CLAUDE.md.

Nota: Para que o Claude (especialmente usando o Claude Code ou ferramentas de linha de comando da Anthropic) funcione corretamente, o arquivo CLAUDE.md deve ser colocado na raiz da solução (.sln).

Em uma estrutura típica de 4 projetos, seu diretório deve ficar assim:

/MeuProjetoSolucao
│
├── .sln (Arquivo da Solução)
├── CLAUDE.md  <-- O ARQUIVO VAI AQUI
│
├── src/ (ou na raiz)
│   ├── MeuProjeto.Domain/
│   ├── MeuProjeto.Application/
│   ├── MeuProjeto.Infrastructure/
│   └── MeuProjeto.API/
│
└── tests/

Para cenários usando uma arquitetura em camadas, vale a pena adicionar uma seção de "Mapeamento de Camadas" no seu arquivo CLAUDE.md para evitar que a IA crie lógica de banco de dados (Infra) dentro do seu projeto de API:

## Estrutura da Solução
- `Domain`: Entidades, interfaces de repositório e lógica de domínio pura.
- `Application`: DTOs, Mappers, Commands/Queries (MediatR) e Interfaces de serviço.
- `Infrastructure`: Implementação de repositórios (Dapper/EF), acesso a API externas e persistência.
- `API`: Controllers/Endpoints, Injeção de Dependência e Configurações (Startup).

## Regras de Dependência
- A camada `Domain` nunca deve referenciar nenhuma outra.
- A `API` deve referenciar `Application` e `Infrastructure` para o Setup da DI.

Se o seu projeto crescer muito, você pode usar a pasta .claude/rules/ (também na raiz) para separar regras específicas para a API ou para a Infrastructure.

Para que serve realmente o CLAUDE.md

O arquivo CLAUDE.md não deve ser tratado como documentação tradicional, nem como um simples guia de estilo. Ele funciona, na prática, como um guia técnico estruturado — semelhante ao conjunto de orientações que você entregaria a um engenheiro sênior no primeiro dia de trabalho em um projeto.

Em vez de explicar tudo de forma genérica, o objetivo do CLAUDE.md é deixar explícito como o sistema realmente funciona. Isso inclui qual problema o sistema está tentando resolver, quais são as decisões arquiteturais já estabelecidas e quais limites não devem ser ultrapassados. Em um projeto .NET, isso pode significar, por exemplo, deixar claro se a aplicação segue uma arquitetura em camadas (Domain, Application, Infrastructure), se utiliza padrões como CQRS ou MediatR, e como o acesso a dados com EF Core deve ser realizado.

Além disso, o arquivo define regras operacionais claras: quais padrões são aceitos, quais devem ser evitados e, principalmente, como mudanças devem ser implementadas dentro do contexto existente. Isso reduz drasticamente o risco de a IA sugerir soluções que “funcionam isoladamente”, mas quebram a consistência do sistema como um todo.

Outro ponto essencial é a definição de como validar mudanças. Em vez de deixar implícito, o CLAUDE.md pode orientar a IA a seguir o mesmo fluxo que um desenvolvedor seguiria: executar testes, respeitar validações existentes, manter contratos de API e garantir que o build continue íntegro. Isso transforma a IA de um gerador de código em um participante mais responsável dentro do ciclo de desenvolvimento.

O ponto-chave é que o Claude Code carrega automaticamente o conteúdo do CLAUDE.md no contexto de cada sessão. Na prática, isso significa que a IA não começa do zero a cada interação. Ela inicia já alinhada com as regras, padrões e objetivos do projeto.

Em vez de depender de suposições, o Claude passa a operar com contexto compartilhado e restrições bem definidas — ou seja, com os mesmos “guardrails” que você estabeleceria para qualquer desenvolvedor experiente entrando no seu time.

Por que "caprichar no prompt" não funciona

A maioria das equipes tenta resolver isso escrevendo prompts cada vez mais longos, entretanto, essa abordagem não escala pois os prompts são:

- Reescritos constantemente.
- Fáceis de esquecer.
- Inconsistentes entre desenvolvedores.

O CLAUDE.md inverte o modelo :  em vez de repetir as regras todas as vezes, nós as definimos uma vez e deixamos a ferramenta segui-las, com isso a consistência melhora imediatamente.

O que um CLAUDE.md útil deve evitar

Um bom CLAUDE.md não existe apenas para orientar — ele existe principalmente para evitar erros caros, daqueles que não quebram só o código, mas a arquitetura, a consistência do sistema e até o pipeline de entrega.

Se o arquivo não deixa claro o que não deve ser feito, ele está incompleto.

Em projetos .NET reais, alguns erros são recorrentes quando a IA não tem contexto adequado:

Um dos mais comuns é introduzir frameworks, bibliotecas ou camadas que o projeto não utiliza.
Por exemplo, a IA pode sugerir MediatR em um projeto que não usa CQRS, ou criar uma camada de Application que simplesmente não existe. Isso gera inconsistência e aumenta a complexidade sem necessidade.

Outro problema frequente é ignorar aspectos fundamentais de execução, como o uso de CancellationToken e controle de timeout.  Em aplicações ASP.NET Core, isso não é detalhe — é requisito básico para garantir escalabilidade e evitar consumo desnecessário de recursos.

Também é comum a IA tentar introduzir processamento em segundo plano dentro do fluxo de requisição — como disparar tarefas assíncronas sem controle dentro de controllers ou handlers. Isso quebra o modelo de execução do ASP.NET Core e pode gerar comportamentos imprevisíveis, especialmente em produção.

Além disso, há o risco de alterar código sem qualquer forma de validação. A IA pode sugerir mudanças que parecem corretas isoladamente, mas que ignoram testes existentes, contratos de API ou regras de negócio já estabelecidas. Em projetos maduros, isso é inaceitável.

Outro ponto crítico é a tendência de inventar abstrações desnecessárias — interfaces, serviços ou padrões que não fazem parte do design original. Isso polui o código, dificulta a manutenção e vai contra um dos princípios mais importantes em sistemas bem projetados: simplicidade com intenção clara.

Por isso, o CLAUDE.md não deve ser escrito como um texto explicativo longo e genérico.

Ele deve ser escrito como restrições claras e acionáveis. Em vez de dizer:  “Evite processamento em segundo plano”

O ideal é algo como:

- Não utilizar Task.Run dentro de controllers ou handlers
- Não iniciar processamento assíncrono fora do pipeline de requisição
- Todo processamento deve respeitar o fluxo síncrono da requisição HTTP

Ou seja: menos narrativa, mais regra explícita.

Como o Claude carrega a memória do projeto

O Claude Code utiliza uma hierarquia inteligente de arquivos de memória para organizar o conhecimento. Entender como essas camadas se sobrepõem evita frustrações, permitindo que você defina desde preferências globais até regras específicas para cada módulo do seu projeto.

Para aproveitar essa organização, você pode distribuir suas diretrizes entre quatro níveis principais de armazenamento de memória:

1 - ./CLAUDE.md : É o arquivo principal que fica na raiz da sua solução .NET.

O que colocar: O "mapa da mina". Estrutura das 4 camadas (Domain, Application, etc.), versões do .NET e comandos de build/test.

Uso: É compartilhado com todo o time via Git. Garante que qualquer desenvolvedor que use o Claude no projeto receba o mesmo comportamento da IA.

2 - ./.claude/rules/*.md : Em vez de um arquivo CLAUDE.md gigante e confuso, você separa regras específicas em arquivos dentro desta pasta.os de regras modulares agrupados por tema.

Exemplos:
api-rules.md : Regras sobre códigos de status HTTP e validação.
db-rules.md : Padrões de escrita SQL ou mapeamentos do Dapper.
tests-rules.md : Como mockar dependências na camada de Application.
Vantagem: O Claude carrega apenas o "especialista" necessário para a tarefa atual.

3 - ./CLAUDE.local.md : Notas privadas de cada desenvolvedor (não comitadas). Este arquivo deve estar no seu .gitignore para nunca subir para o servidor.

O que colocar: Notas que só importam para você hoje.

Exemplo: "Estou trabalhando na refatoração da classe X, ignore erros de build na pasta Y por enquanto" ou "Sempre use nomes de variáveis em português neste meu módulo específico".

Uso: Customização temporária sem afetar o resto da equipe.

4 - ~/.claude/CLAUDE.md : Preferências globais pessoais. Este arquivo fica na pasta do seu usuário no sistema operacional (fora da pasta do projeto).

O que colocar: Suas preferências genéricas de codificação que valem para qualquer projeto que você abrir.

Exemplo: "Nunca use comentários óbvios", "Sempre use var em C#", ou "Seja conciso nas explicações e foque no código".

Uso: Define a "personalidade" do Claude para você, independentemente de ser um projeto .NET, Python ou React.

Resumindo:

Como exemplo temos a seguir um ponto de partida prático para uma API .NET moderna. Este exemplo é intencionalmente opinativo e curto sendo apenas uma sugestão de uso genérica:

# CLAUDE.md – Instruções do Projeto (.NET)

## O que é este repositório
- API backend em .NET 10 focada em confiabilidade de produção e latência previsível.
- Prefira padrões simples e explícitos em vez de abstrações complexas.

## Tech stack
- .NET 10 / C#
- ASP.NET Core (Minimal APIs)
- Dapper (não usar EF Core)
- Redis para cache
- Azure hosting
- Application Insights para logs e métricas

## Mapa do Repositório
- src/Api/    → endpoints, middleware, DI
- src/App/    → serviços de aplicação
- src/Infra/  → bancos de dados, Redis, clientes HTTP
- tests/      → testes de unidade e integração

## Regras Rígidas (Hard Rules)
- Não introduza novas camadas arquiteturais.
- Não adicione frameworks que já não usamos.
- Sempre passe CancellationToken em chamadas assíncronas.
- Jamais use "sync over async" (síncrono sobre assíncrono).
- Não use Task.Run em manipuladores de requisição.
- Chamadas HTTP externas devem ter timeouts e cancelamento.
- O cache deve considerar orçamentos de tempo e proteção contra stampede.

## Fluxo de Trabalho (Workflow)
1. Faça perguntas de esclarecimento se os requisitos não estiverem claros.
2. Proponha um plano e liste os arquivos a serem alterados.
3. Implemente a menor mudança viável.
4. Adicione ou atualize testes quando apropriado.
5. Forneça comandos para verificar as mudanças.

## Comandos
- Build: dotnet build
- Test: dotnet test
- Run: dotnet run --project src/Api

Isso sozinho elimina uma enorme quantidade de suposições que a IA poderia fazer.

Usando regras modulares para manter a sanidade

À medida que os projetos crescem, as regras se acumulam, e, colocar tudo em um só arquivo torna-se inviável. Nestes cenários a recomendação é usar .claude/rules/ para temas específicos:

Exemplo de Convenções de API:
  Preferir Minimal APIs a Controllers.
  Validar entradas precocemente.
  Usar ProblemDetails para erros.

Exemplo de Performance:
  Retentativas apenas para operações idempotentes.
  As chamadas ao Redis devem falhar rapidamente (fail fast).

Mantendo o CLAUDE.md ao longo do tempo

O CLAUDE.md deve evoluir com a base de código:

1- Gere um arquivo inicial usando /init.
2- Remova qualquer coisa genérica.
3- Mantenha apenas a "verdade" específica do repositório.
4- Quando o Claude cometer um erro, adicione uma regra que o previna no futuro.
5- Limpe o contexto entre tarefas não relacionadas usando /clear.

O que incluir e o que evitar

Conteúdo de alto valor:
  Tecnologias e versões exatas.
  Estrutura de pastas e responsabilidades.
  Comandos de build e teste.
  Padrões que são explicitamente proibidos.

Conteúdo de baixo valor ou arriscado:
  Segredos ou credenciais.
  Regras de estilo já impostas por formatadores (linters).
  Blocos gigantes de documentação que o Claude pode consultar sozinho.

O objetivo não é ensinar .NET, o objetivo é ensinar ESTE repositório.

Um teste simples para validar a configuração

Após adicionar o CLAUDE.md com as instruções, tente este prompt:

“Adicione um novo endpoint que chame um serviço HTTP externo e faça o cache da resposta com segurança. Mostre o plano primeiro, depois implemente.”

Se a resposta seguir os padrões da sua API, usar cancelamento corretamente, aplicar timeouts e evitar processamento pesado na thread da requisição, então a configuração está funcionando. Se não, suas regras estão incompletas.

Considerações Finais

As ferramentas de IA são tão úteis quanto o contexto que recebem, e sua utilidade é proporcional ao contexto fornecido. Melhores prompts são soluções paliativas; diretrizes bem definidas no projeto são soluções permanentes.

O CLAUDE.md transforma um assistente de IA de um "autocompletar" imprevisível em um colega de equipe consistente tornando-o mais informado.

E estamos conversados...  

"(Disse Jesus) Na casa de meu Pai há muitas moradas; se não fosse assim, eu vo-lo teria dito. Vou preparar-vos lugar."
João 14:2