Como otimizar o Claude com .NET
Usar o Claude Code com .NET da mesma forma que se usa um chatbot comum é o caminho mais curto para a frustração. O desenvolvedor digita um pedido genérico, aguarda a resposta e se surpreende quando o resultado ignora as convenções do projeto.
Esse comportamento é compreensível, porque a interface conversacional cria a ilusão de que qualquer entrada basta para gerar código de qualidade. Na prática, porém, ferramentas de IA para codificação respondem diretamente à qualidade da estrutura que o desenvolvedor oferece a elas.
Os profissionais que extraem valor real da ferramenta não são necessariamente os mais experientes em programação. Eles simplesmente adotaram um protocolo de sessão consistente, que transforma cada interação em um briefing técnico estruturado.
Este artigo detalha esse protocolo aplicado ao ecossistema .NET. Cada etapa vem com exemplos práticos para projetos reais com C#, ASP.NET Core e as convenções da plataforma.
Por que a estrutura importa mais do que o modelo
Antes de entrar nos detalhes técnicos, vale entender o fundamento do problema.
Modelos de linguagem como o Claude operam com base no contexto fornecido. Quanto mais vago o contexto, mais o modelo precisa preencher lacunas com suposições, e suposições em código de produção geram retrabalho.
No universo .NET, essas suposições aparecem de formas bastante específicas. Por exemplo, o modelo pode instanciar serviços com new em vez de usar o contêiner de injeção de dependência nativo.
Ele também pode adicionar pacotes NuGet desnecessários, ignorar convenções de nomenclatura ou refatorar arquivos fora do escopo original. Cada desvio desses vira um item a mais na revisão do pull request.
Além disso, a própria documentação do Claude Code lembra que a janela de contexto enche rápido e que o desempenho cai à medida que ela se enche. Por isso, contexto bem escolhido vale mais do que contexto abundante.
A solução, portanto, não é trocar de modelo. No Claude Code com .NET, o caminho é fornecer o contexto certo, na estrutura certa, com as restrições certas.
O arquivo CLAUDE.md no Claude Code com .NET
Toda sessão produtiva do Claude Code com .NET começa pelo CLAUDE.md. O Claude lê esse arquivo no início de cada sessão, e ele funciona como um documento de contexto persistente.
Em outras palavras, ele equivale ao onboarding técnico que um desenvolvedor sênior daria a um novo membro do time. A diferença é que esse onboarding fica disponível em toda sessão, sem exceção.
Para projetos .NET, o conteúdo ideal inclui as decisões arquiteturais, as convenções de nomenclatura, os pacotes aprovados, os padrões de teste e, fundamentalmente, o que não deve ser feito. Se você ainda está conhecendo a ferramenta, o guia completo do Claude Code cobre a instalação e os primeiros comandos.
Exemplo de CLAUDE.md para ASP.NET Core
O exemplo abaixo atende um projeto ASP.NET Core com arquitetura limpa, Minimal APIs e MediatR.
# CLAUDE.md
## Architecture
This project follows Clean Architecture with four layers: Domain, Application, Infrastructure and Api.
Never put business logic in the Api layer.
## Conventions
- Endpoints are mapped with Minimal APIs
- Handlers follow the CQRS pattern with MediatR
- Repositories are interfaces defined in Application and implemented in Infrastructure
## Approved packages
- MediatR
- FluentValidation
- Dapper (only for complex read queries)
- Never add Entity Framework Core without explicit approval
## Commands
- Build: dotnet build
- Tests: dotnet test
## Prohibitions
- Do not use `new` to instantiate services registered in the container
- Do not modify files outside the scope of the task
- Do not refactor working code without explicit instruction
Com esse arquivo, você deixa de repetir premissas a cada sessão. Assim, o Claude passa a trabalhar com o vocabulário e as restrições do projeto desde o primeiro prompt.
Se o padrão CQRS ainda é novidade, o artigo sobre CQRS e Mediator no ASP.NET explica a base que o exemplo pressupõe.
Onde o arquivo fica e como o Claude o carrega
O arquivo de projeto pode ficar em ./CLAUDE.md ou em ./.claude/CLAUDE.md. Além dele, existe o ~/.claude/CLAUDE.md, com preferências pessoais para todos os projetos, e o CLAUDE.local.md, que guarda preferências locais e deve entrar no .gitignore.
O Claude Code carrega os arquivos do diretório de trabalho e de todos os diretórios acima dele. Já os arquivos em subdiretórios entram sob demanda, quando o Claude lê arquivos daquelas pastas.
Em uma solução .NET com vários projetos, isso abre uma possibilidade interessante. Você pode manter regras gerais na raiz e regras específicas em src/Api/CLAUDE.md ou tests/CLAUDE.md.
Também é possível importar outros arquivos com a sintaxe @caminho/do/arquivo, por exemplo @docs/architecture.md. Contudo, os arquivos importados também entram no contexto na inicialização, então a importação organiza o conteúdo sem reduzir o custo.
Por fim, o comando /init gera um CLAUDE.md inicial a partir da análise do repositório. Depois, basta refinar o arquivo com as regras que o Claude não descobriria sozinho.
Contexto focado no Claude Code com .NET
Um erro comum no Claude Code com .NET é deixar o agente ler o repositório inteiro na esperança de que ele "entenda o projeto".
Na prática, contexto excessivo dilui a atenção do modelo nos arquivos mais relevantes. Com isso, aumenta a probabilidade de respostas genéricas.
O inverso também é problemático. Contexto insuficiente força o modelo a inventar implementações compatíveis com um padrão que ele nunca viu.
A abordagem correta no Claude Code com .NET é selecionar cirurgicamente os arquivos que realmente importam para a tarefa.
Para adicionar um novo endpoint em um projeto ASP.NET Core, o contexto ideal inclui o arquivo de endpoints do recurso relacionado e o handler de um caso de uso semelhante. Também entram a interface do repositório envolvido e o arquivo de testes de integração do mesmo recurso.
No Claude Code, a forma direta de apontar esses arquivos é a referência com @ dentro do próprio prompt. Dessa forma, o Claude lê cada arquivo antes de responder.
Read @src/Api/Endpoints/OrderEndpoints.cs,
@src/Application/Orders/GetOrderById/GetOrderByIdHandler.cs,
@src/Application/Orders/IOrderRepository.cs and
@tests/Integration/Orders/OrderEndpointsTests.cs
before making any change. Use them as the reference pattern.
Esse nível de precisão direciona a atenção do modelo para os padrões reais do projeto, e não para padrões genéricos da internet.
Quando a investigação é grande, a documentação oficial sugere delegar a pesquisa a subagentes. Eles exploram em um contexto separado e devolvem apenas um resumo, enquanto a conversa principal fica livre para a implementação.
Tarefas específicas para o Claude Code com .NET
A qualidade do prompt define o teto da qualidade do código que o Claude Code com .NET entrega.
"Adicionar um endpoint de cancelamento" é uma intenção. Por outro lado, "adicionar um endpoint DELETE /orders/{id}/cancel que aciona o CancelOrderHandler, retorna 204 em caso de sucesso e 404 se o pedido não existir" já é uma tarefa.
A diferença entre os dois não é apenas de detalhe. Na verdade, é uma diferença de resultado.
Prompts vagos forçam o modelo a tomar decisões que deveriam ser suas. Entre elas estão o nome do endpoint, o código de retorno, o padrão de erro, a forma de injeção do handler e a localização do arquivo.
Cada uma dessas decisões abre uma oportunidade para divergir das convenções do projeto.
A anatomia de um bom prompt
No Claude Code com .NET, um prompt bem estruturado segue quatro partes:
- O que criar, com verbo, recurso e localização.
- O comportamento esperado, incluindo casos de sucesso e de erro.
- A referência de padrão, ou seja, qual arquivo existente serve como modelo.
- O que deve ser testado, com o tipo de teste e os cenários.
Add a DELETE /orders/{id}/cancel endpoint in OrderEndpoints.cs.
The endpoint must call CancelOrderHandler through MediatR.
Return 204 when cancelled, 404 when the order does not exist
and 409 when the current status does not allow cancellation.
Follow exactly the pattern used by the GetOrderById endpoint.
Create an integration test in OrderEndpointsTests.cs covering the three scenarios.
Esse nível de especificidade transforma o Claude em um executor preciso, e não em um autor criativo.
Para mudanças maiores, a documentação recomenda separar exploração, plano e implementação com o modo de plano. Nesse modo, o Claude lê arquivos e responde perguntas sem alterar nada, e você aprova o plano antes da primeira linha de código.
Restrições explícitas no Claude Code com .NET
Esta etapa é onde a maioria dos desenvolvedores que usam o Claude Code com .NET falha, mesmo com bons prompts.
Sem restrições explícitas, o Claude tende a "ajudar" de formas não solicitadas. Em projetos .NET, isso significa middleware que ninguém pediu, refatoração de classes fora do escopo, padrões de log diferentes dos existentes ou pacotes NuGet que o time não aprovou.
Isoladamente, cada uma dessas ações parece benevolente. No contexto de um PR, entretanto, elas viram ruído que alguém precisa revisar, reverter ou justificar.
A solução é tratar as restrições como parte fixa de todo prompt:
Do not modify any file other than OrderEndpoints.cs and OrderEndpointsTests.cs.
Do not add new NuGet packages.
Do not change the signature of existing interfaces.
Do not refactor working code.
Restrições explícitas definem os limites do trabalho com a mesma clareza que a especificação define o conteúdo. Assim, as duas partes se tornam igualmente necessárias.
Em equipes maiores, você pode padronizar essas restrições no próprio CLAUDE.md. Dessa forma, elas passam a fazer parte do contexto automático de toda sessão.
Quando a instrução não basta
Vale um alerta importante. O Claude trata o CLAUDE.md como contexto, e não como configuração imposta, então uma regra escrita pode ser ignorada em uma sessão longa.
Para o que precisa acontecer sempre, sem exceção, a documentação recomenda hooks e regras de permissão. Os hooks executam scripts em pontos definidos do fluxo, enquanto as regras de permissão bloqueiam comandos específicos.
Por exemplo, o trecho abaixo, no .claude/settings.json, impede que o Claude adicione pacotes por conta própria:
{
"permissions": {
"deny": [
"Bash(dotnet add package *)"
]
}
}
Na mesma linha, o artigo como fazer o Claude escrever código de qualidade em .NET mostra como transformar convenções em erros de compilação com analisadores.
Verificação automatizada no Claude Code com .NET
A etapa final do protocolo é também a mais objetiva. O código precisa compilar e os testes precisam passar antes de a tarefa ser considerada concluída.
Essa instrução parece óbvia, mas a maioria de quem usa o Claude Code com .NET não a inclui explicitamente no prompt.
O resultado é código que o Claude declara funcional, mas que falha na primeira execução de dotnet build.
A documentação de boas práticas do Claude Code explica o motivo. Sem uma verificação que possa executar, o único sinal que o Claude tem é a aparência de trabalho concluído, e você vira o ciclo de verificação.
Por isso, a instrução correta é simples e direta:
After generating the code, run:
1. dotnet build
2. dotnet test --filter "Category=Orders"
If either command fails, fix the root cause before finishing.
Show the command output as evidence.
Essa instrução transforma a verificação em parte do contrato da tarefa, e não em uma etapa opcional.
Pedir a saída dos comandos como evidência também ajuda. Afinal, revisar a evidência é mais rápido do que executar a verificação de novo.
Para projetos com pipelines de CI, você pode expandir a instrução com análise estática, cobertura mínima de testes ou dotnet format --verify-no-changes. Quando a verificação precisa ser obrigatória, um hook do tipo Stop impede que o turno termine antes de o script passar.
O protocolo do Claude Code com .NET em um exemplo real
Para consolidar as cinco etapas do Claude Code com .NET, considere um cenário concreto. O objetivo é adicionar suporte a cancelamento de pedidos em um projeto ASP.NET Core existente.
Primeiro, o CLAUDE.md já define arquitetura, convenções e restrições globais.
Em seguida, o contexto selecionado inclui OrderEndpoints.cs, um handler semelhante, IOrderRepository.cs e OrderEndpointsTests.cs.
Então, o prompt completo fica assim:
Context: ASP.NET Core project with Minimal APIs and MediatR.
Reference files: @src/Api/Endpoints/OrderEndpoints.cs @tests/Integration/Orders/OrderEndpointsTests.cs
Task: add a DELETE /orders/{id}/cancel endpoint in OrderEndpoints.cs.
- Call CancelOrderHandler through MediatR
- Return 204 on success, 404 when not found, 409 when the status is invalid
- Follow the existing GetOrderById endpoint pattern
Constraints:
- Modify only OrderEndpoints.cs and OrderEndpointsTests.cs
- Do not add new packages
- Do not refactor existing code
Verification:
- Run dotnet build
- Run dotnet test --filter "Category=Orders"
- Fix any failure before finishing
O resultado desse prompt é radicalmente diferente do resultado de "adicione cancelamento de pedidos". A diferença não está no modelo, e sim na estrutura.
Se o seu projeto usa Minimal APIs e você quer revisar o padrão de mapeamento antes de escrever o prompt, o artigo sobre Minimal APIs no ASP.NET ajuda a definir a referência.
Claude Code com .NET em equipe
O protocolo do Claude Code com .NET descrito aqui escala bem para equipes.
Como o CLAUDE.md fica versionado junto com o repositório, todos os membros do time partem do mesmo conjunto de regras e convenções.
Além disso, alterações nas decisões arquiteturais se refletem automaticamente em todas as sessões futuras, sem depender de comunicação informal.
Você também pode documentar prompts bem estruturados como templates reutilizáveis. Tipos recorrentes de tarefa, como adicionar endpoints, criar handlers ou escrever testes de integração, ganham com isso.
Nesse caso, as skills do Claude Code são o lugar natural para esses templates. Elas ficam em .claude/skills/ e carregam apenas quando a tarefa pede, sem ocupar contexto o tempo todo.
Essa abordagem reduz a variância do código gerado por diferentes membros do time. Com isso, o uso do Claude Code com .NET fica mais previsível e auditável.
Outra prática útil é o padrão escritor e revisor. Uma sessão implementa a mudança e outra, com contexto limpo, revisa o diff sem o viés de quem escreveu o código.
Manutenção do CLAUDE.md
No Claude Code com .NET, o CLAUDE.md não é um documento estático. Ele precisa evoluir junto com o projeto.
Decisões arquiteturais mudam, pacotes entram e saem, e padrões de teste amadurecem.
Cada uma dessas mudanças deve chegar ao CLAUDE.md da mesma forma que chegaria a um ADR (Architecture Decision Record).
Um CLAUDE.md desatualizado é quase tão problemático quanto a ausência dele. Afinal, ele instrui o Claude a seguir convenções que o projeto já abandonou.
O tamanho também importa. A documentação recomenda manter cada arquivo abaixo de 200 linhas, porque arquivos longos consomem mais contexto e reduzem a aderência às regras.
Para cada linha, vale a pergunta sugerida pela própria Anthropic: remover esta instrução faria o Claude errar? Se a resposta for não, a linha pode sair.
A recomendação final é tratar a atualização do CLAUDE.md como parte do merge de qualquer PR com mudanças arquiteturais relevantes. Para conter o consumo de contexto no dia a dia, o artigo sobre como economizar tokens no Claude complementa essa disciplina.
Conclusão
O Claude Code com .NET é uma combinação poderosa, mas o potencial real depende da estrutura que o desenvolvedor oferece a cada sessão.
O protocolo de cinco etapas reúne CLAUDE.md, contexto focado, tarefa específica, restrições explícitas e verificação automatizada. Juntas, essas etapas transformam o Claude de um gerador de código genérico em um colaborador técnico preciso.
Desenvolvedores que adotam essa estrutura de forma consistente não trabalham mais. Pelo contrário, trabalham de forma mais direcionada, com menos retrabalho e mais confiança no código gerado.
Em resumo, a diferença entre usar o Claude como chatbot e usá-lo como ferramenta de engenharia não está no modelo. Está no protocolo.
FAQ
O CLAUDE.md precisa estar na raiz do projeto?
O arquivo de projeto fica em ./CLAUDE.md ou em ./.claude/CLAUDE.md. O Claude Code também carrega arquivos dos diretórios acima do diretório de trabalho e, sob demanda, dos subdiretórios.
Posso ter vários arquivos CLAUDE.md em uma solução .NET?
Sim. Cada subdiretório pode ter o próprio CLAUDE.md, e o Claude inclui esse arquivo quando lê arquivos daquela pasta.
O protocolo funciona para refatorações grandes?
Funciona, mas refatorações grandes exigem decomposição em tarefas menores. Cada etapa deve ter o próprio ciclo de prompt, restrição e verificação.
O que fazer se o Claude alterar arquivos fora do escopo?
Revise o diff completo antes de aceitar a mudança e trate a violação como um bug de prompt. Para regras que não podem falhar, use regras de permissão ou hooks.
Devo incluir exemplos de código no CLAUDE.md?
Sim, quando a convenção for difícil de descrever em prosa. Trechos curtos de endpoints ou handlers reduzem ambiguidades, desde que o arquivo continue enxuto.
O protocolo vale fora do terminal?
As etapas de contexto, tarefa, restrições e verificação valem para qualquer uso do Claude em código. O CLAUDE.md, porém, é um recurso do Claude Code, disponível no terminal, nas extensões de IDE e no aplicativo desktop.