.NET - Desenvolvimento Backend com Claude Code

  Neste artigo vou mostrar como podemos usar o Claude Code no desenvolvimento Backend na plataforma .NET.

O desenvolvimento backend exige muito código repetitivo para implementar funcionalidades essenciais, e isso pode fazer o desenvolvimento parecer lento.  O Claude Code trabalha diretamente com a base de código, editando arquivos e executando comandos dentro do fluxo de desenvolvimento.



Ele atua como um assistente de programação baseado em agentes que pode ler o repositório, fazer alterações e integrar-se com suas ferramentas no terminal, IDE, aplicativo desktop e navegador,  sendo útil para tarefas backend que abrangem múltiplas camadas e pode ajudar com:

- Implementação
- Correção de bugs
- Refatoração
- Testes
- Preparação de releases
- Revisão de código

Para desenvolvimento backend isso importa muito, visto que um endpoint REST pode envolver um controller, service, repository, regras de validação, DTOs e testes, e, o Claude Code consegue trabalhar entre esses arquivos mantendo as alterações alinhadas.

Instalação e Configuração do Claude Code

Antes de instalar, certifique-se de possuir os seguintes requisitos:

- Node.js 18+ (a versão LTS é fortemente recomendada)
- macOS 10.15+, Ubuntu 20.04+/Debian 10+, ou Windows 10+ com WSL
- Pelo menos 8 GB de RAM
- Uma assinatura paga do Claude.ai (Pro, Max5 ou Max20) ou uma chave de API da Anthropic

Instalando o Claude Code

O comando de instalação a seguir pode ser dado em uma janela de prompt de comandos:

npm install -g @anthropic-ai/claude-code

Após a instalação, ao digitar o comando claude, será aberto um fluxo de autenticação via navegador.

Caso prefira usar diretamente uma API Key:

export ANTHROPIC_API_KEY=sua_api_key_aqui

A maneira mais simples de iniciar o Claude Code é navegar até a raiz do projeto e executar:  claude

Se quisermos executar um comando rápido sem iniciar uma sessão completa:

claude -p "Explique o que este serviço ASP.NET Core .NET 10 faz"

Também podemos canalizar saída de logs:

cat error.log | claude -p "Analise a causa raiz destes erros"

Comandos Importantes do Claude Code

Comandos Shell (Fora de uma Sessão) -  Esses comandos são executados antes ou depois de uma sessão do Claude Code :

claude --version
Exibe a versão instalada do Claude Code.

claude config set theme dark
Altera a configuração global do tema para modo escuro.

claude auth login --token SEU_TOKEN
Realiza autenticação com a API da Anthropic antes de iniciar uma sessão.

claude --help
Mostra todos os comandos e opções disponíveis no CLI.

claude session list
Lista sessões anteriores (útil para retomar ou limpar histórico).

Slash Commands (Dentro de uma Sessão) - Durante uma sessão ativa, os comandos iniciados com / controlam o comportamento do Claude Code :

/help - exibe todos os comandos disponíveis
/clear - limpa o histórico da conversa
/compact - comprime e resume o contexto (útil em sessões longas)
/cost - mostra quantos tokens você usou
/doctor - diagnostica problemas de configuração
/init - cria um arquivo de configuração CLAUDE.md do projeto
/review - inicia uma revisão de código das suas alterações atuais
/todos - lista todos os itens TODO que o Claude está rastreando
/rewind - volta para um ponto de controle anterior na sessão
/add-dir - adiciona outro diretório ao contexto da sessão atual
/permissions - visualiza e atualiza as permissões de ferramentas
/bashes - verifica processos em execução em segundo plano
/kill <id> - para um processo específico em segundo plano
/statusline - configura um visor de status ao vivo para tarefas em segundo plano

Trabalhando com Múltiplos Projetos .NET

Por padrão, o Claude Code lê apenas o diretório atual. Porém, aplicações .NET modernas frequentemente usam:

- monorepos
- microsserviços
- soluções com múltiplos projetos

Podemos expandir o contexto usando a flag : --add-dir

A flag --add-dir no Claude Code serve para expandir o contexto de arquivos que o assistente pode ler e analisar, indo além do diretório de trabalho atual. Por padrão, o Claude Code só "enxerga" o diretório onde ele foi iniciado (e seus subdiretórios). Com --add-dir, você adiciona outros diretórios (mesmo que fora da árvore do projeto atual) ao escopo de conhecimento da IA.

Exemplo:

claude --add-dir ../user-service --add-dir ../payment-service

A partir de um diretório como ~/dev/order-service:

O diretório atual (order-service) continua sendo o principal – é onde comandos como dotnet build serão executados se você pedir para rodar algo.

O Claude Code carrega e indexa os arquivos dos diretórios ../user-service e ../payment-service (ou seja, ~/dev/user-service e ~/dev/payment-service).

Durante a sessão, a IA pode ler, pesquisar e referenciar código, configurações, projetos .csproj, etc., desses três serviços.

Ele não pode modificar arquivos nesses diretórios a menos que você explicitamente autorize (como qualquer outro arquivo). Mas pode sugerir alterações consistentes entre eles.

Isso é extremamente útil quando uma alteração atravessa múltiplos serviços.

Configurando o CLAUDE.md
Uma das melhores práticas é executar:  /init

Isso cria um arquivo CLAUDE.md, usado para documentar:
- arquitetura
- convenções
- padrões
- estrutura do projeto
- regras técnicas

Exemplo de CLAUDE.md para .NET 10

# Projeto: Order Service

## Stack Tecnológica
- .NET 10
- ASP.NET Core 10
- Entity Framework Core 10
- PostgreSQL
- RabbitMQ

## Convenções
- Usar records para DTOs
- Usar IEntityTypeConfiguration
- Usar FluentValidation
- Não usar AutoMapper
- Utilizar Result Pattern

## Estrutura
api → application → infrastructure → domain

## Testes
- xUnit
- FluentAssertions
- NSubstitute
- Testcontainers

## Observações
- Utilizar CancellationToken
- Preferir consultas AsNoTracking

O Claude lê esse arquivo no início de cada sessão, evitando reexplicar o projeto constantemente.

Planejamento Antes da Implementação

Um recurso extremamente útil do Claude Code é sua capacidade de planejar alterações antes de modificar código.  Isso é muito importante em projetos corporativos grande

Para isso, utilize o comando /plan, que ativa o modo de planejamento. Nesse modo, o Claude Code analisa o código, arquitetura e requisitos, mas não implementa nenhuma alteração – ele apenas gera um plano detalhado. Você pode revisar o plano, ajustá-lo e só então pedir a execução.

Exemplo:
/plan Analise este projeto ASP.NET Core .NET 10 e crie um plano
para implementar multi-tenancy usando EF Core 10.
Não altere arquivos ainda.

O Claude pode:
- analisar arquitetura
- listar arquivos afetados
- identificar riscos
- sugerir estratégia
- recomendar testes

Outro exemplo:


/plan Crie um plano para migrar este monólito ASP.NET Core para microsserviços. 

Após gerar o plano, você pode continuar conversando para refiná-lo. Quando estiver satisfeito, peça: "Agora execute este plano" – e o Claude implementará as mudanças seguindo o que foi acordado.

Nota: Podemos também ativar o modo plan (ou Plan Mode) no Claude Code, o que é uma ótima maneira de analisar o código e planejar mudanças sem fazer edições automáticas, garantindo que o AI leia e entenda o projeto antes de intervir
  • No terminal, com o Claude Code aberto, pressione Shift + Tab duas vezes.
  • Você verá o modo mudar no indicador do terminal.
    		•

    Entendimento da Base de Código

    Uma das capacidades mais fortes do Claude Code é entender relacionamentos em toda a solução.

    Isso é extremamente poderoso em aplicações .NET complexas.

    Podemos pedir:  "Explique como o fluxo de autenticação funciona neste projeto."

    O Claude pode navegar por:
    - middleware
    - JWT
    - Identity
    - controllers
    - services
    - handlers
    - repositories

    Isso ajuda muito em: onboarding , debugging, sistemas legados, documentação e análise arquitetural

    Podemos melhorar esta operação usando subagentes usando o seguinte prompt:

    Execute múltiplos subagentes de exploração em paralelo e Explique como o fluxo de autenticação funciona neste projeto.

    Notem o prompt enviado: " Execute múltiplos subagentes de exploração em paralelo ..."

    Eu estou pedindo explicitamente para o Claude dividir o trabalho em múltiplos agentes especializados executando em paralelo.

    Fluxos Reais de Trabalho com .NET 10 e EF Core 10

    Gerar um Endpoint REST do Zero

    Podemos enviar o seguinte prompt em linguagem natural:

    Crie um endpoint POST /orders em ASP.NET Core .NET 10.
    O corpo da requisição deve conter customerId, items
    (lista de productId e quantity) e shippingAddress.
    Retorne status 201.
    Use records para DTOs e siga o CLAUDE.md.

    O Claude irá gerar:
    - controller
    - service
    - repository
    - entidade
    - DTOs
    - validações
    - mapeamentos EF Core

    Se você estiver trabalhando com a abordagem do DDD e Clean Architecture pode melhorar o prompt como algo assim:

    Atue como um desenvolvedor especialista em .NET 10 e DDD. Crie um endpoint POST /orders seguindo estas especificações técnicas:

    1. Arquitetura: Siga rigorosamente a estrutura Controller -> Service -> Repository -> Domain definida no CLAUDE.md.

    2. Domain: Implemente a Entidade Order usando Tactical Design (encapsulamento e lógica no domínio).

    3. DTOs: Use public record com Primary Constructors para CreateOrderRequest, OrderItemRequest e OrderResponse.

    4. Persistência: Use Entity Framework Core 10 com PostgreSQL. Implemente o mapeamento via IEntityTypeConfiguration.

    5. Contrato: O corpo da requisição deve ter customerId, items (lista de productId e quantity) e shippingAddress. Retorne 201 Created.

    6. Padrões:

      • Utilize Injeção de Dependência via construtores primários do C# 14.

      • Garanta que o método no Service seja transacional.

      • Não utilize bibliotecas externas de geração de código (sem Lombok.NET/AutoMapper), prefira recursos nativos do C#.

    Agora temos o contexto de um especialista , a restrição de ferramentas, o foco no DDD e o mapeamento explícito usando IEntityTypeConfiguration

    Escrever Testes para Código Existente

    Com o Claude Code, você pode gerar testes de alta qualidade para código já existente – sejam classes, serviços, controllers ou repositórios. Ele entende a lógica de negócios, as dependências e os padrões do projeto.

    Exemplo de prompt básico:

    Escreva testes unitários para a classe OrderService.

    Use xUnit e NSubstitute.

    Cubra:
    - fluxo feliz (pedido criado com sucesso)
    - lista de pedidos vazia
    - cliente inexistente (lança exceção)

    Mas você pode ir muito além, usando o /plan para garantir qualidade:

    m

    /plan Gere uma suíte de testes para o OrderService com os seguintes requisitos:

    1. Framework: xUnit
    2. Mocking: NSubstitute (ou Moq, se preferir)
    3. Padrão: Arrange-Act-Assert (AAA)
    4. Cenários a cobrir:
    - Criar pedido com itens válidos → retorna OrderId
    - Criar pedido com cliente inexistente → lança CustomerNotFoundException
    - Obter pedidos por cliente → retorna lista vazia quando não há pedidos
    - Cancelar pedido já pago → lança InvalidOperationException
    5. Use dados de teste via theory members (InlineData/MemberData)
    6. Gere também testes de integração para o repositório (com Testcontainers + PostgreSQL)

    O Claude Code irá:

    -Analisar o código real do OrderService, suas dependências (IOrderRepository, IPaymentService, etc.)
    -Gerar testes que respeitam a assinatura dos métodos e o comportamento esperado
    -Incluir mocks configurados corretamente (Returns(), Received())
    -Sugerir nomes de métodos de teste seguindo a convenção :     
                     NomeDoMétodo_Condição_ResultadoEsperado
    -    Adicionar [Fact] para testes que não recebem parâmetros e [Theory] para os parametrizados
    -Identificar lacunas de cobertura que você talvez não tenha pensado (ex: concorrência, timeout, null arguments)

    Após gerar os testes, use /review para que o Claude verifique se os testes estão corretos, completos e seguem as melhores práticas de xUnit.

    Depurar Logs e Erros

    O Claude Code é uma ferramenta poderosa para analisar logs, stack traces e mensagens de erro – especialmente em ambientes .NET com logging estruturado (Serilog, NLog, Application Insights) e mensageria (RabbitMQ, Kafka). Ele pode identificar a causa raiz, sugerir correções e até gerar o código da solução.

    Formas de usar:

    Enviar logs via pipe (terminal) - Útil para logs longos ou quando o arquivo está fora do diretório de trabalho.

    cat logs/application.log | claude -p "Identifique a causa raiz deste erro e sugira uma correção"

    Ou, em um pipeline mais elaborado:

    tail -100 logs/error.log | claude -p "Analise estas últimas 100 mensagens. Quais são os erros mais frequentes? Priorize por severidade."

    Referenciar o arquivo diretamente na sessão - Dentro de uma sessão interativa (claude), você pode simplesmente pedir:


     Analise o arquivo logs/application.log e explique por que o consumer do RabbitMQ está lançando SerializationException.

    Combinar com visualização seletiva - Se o log for gigantesco, use head, grep ou jq (para logs JSON) antes de enviar:

    grep -A 20 "SerializationException" logs/application.log | claude -p "Qual o padrão aqui?"

    Usar /review para examinar erro atual - Se você acabou de executar a aplicação e viu um erro no terminal, pode usar:


     /review O sistema acabou de lançar uma exceção. Veja o stack trace abaixo e me diga o que causou: System.InvalidOperationException: O DbContext foi descartado...

    Depuração com múltiplos arquivos - Em um cenário complexo, combine o log com o código que gerou o erro:

     Analise logs/error.log e o código de OrderService. O erro 'NullReferenceException' acontece no método ProcessPayment. Explique por que a propriedade PaymentMethod pode ser nula e como corrigir.

    O que o Claude Code pode fazer por você:

    ✅ Apontar a linha exata de código que causou a exceção (se o stack trace estiver presente)
    ✅ Reconhecer problemas comuns no ecossistema .NET:
    DbUpdateConcurrencyException no EF Core → sugere padrões de retry ou optimistic concurrency
    SerializationException no RabbitMQ → aponta mismatch de contratos entre produtor/consumidor
    TaskCanceledException em HttpClient → identifica timeout ou cancellation token
    JsonSerializationException no System.Text.Json → indica propriedade faltando ou tipo errado
    ✅ Sugerir correções imediatas com exemplo de código pronto
    ✅ Recomendar testes para reproduzir o erro (ex: teste de integração com logging)
    ✅ Se usar Serilog com enriquecimento de contexto, ele interpreta propriedades como {UserId}, {CorrelationId} e ajuda a rastrear a origem

    Se o erro for recorrente, você pode rodar:

    /plan Com base nos erros do log de hoje, planeje uma rota de correção definitiva.

    O Claude vai listar as causas prováveis, os arquivos que precisam ser alterados e os testes que devem ser escritos antes de aplicar o fix.

    Refatorar Múltiplos Arquivos em Todo o Projeto .NET

    O Claude Code é excepcional para refatorações que atravessam toda a solução – algo que normalmente seria tedioso, propenso a erros e demorado. Ele entende as dependências entre arquivos, projetos e até mesmo across microsserviços (se você usar --add-dir).

    Você pode apenas pedir:

    Renomeie OrderEntity para Order em toda a solução.
    Atualize imports, EF Core e repositories.

    Mas pode ir além usando este prompt simple mas poderoso:

    Renomeie a classe OrderEntity para Order em toda a solução.
    Atualize:
    - Nomes de arquivo (OrderEntity.cs → Order.cs)
    - Nomes de classe internos
    - Todos os usos em controllers, services, repositories
    - Configurações do EF Core (HasKey, ToTable, etc.)
    - Constantes de mensagens (ex: "OrderEntity" em logs ou serialização)
    - Testes unitários e de integração

    O Claude Code irá:

    - Pesquisar automaticamente todas as ocorrências no código (incluindo projetos de teste, shared kernel, migrations)
    - Renomear arquivos fisicamente no disco
    - Atualizar namespace, class, construtores e referências
    - Ajustar configurações do EF Core que usam entity.HasKey(o => o.Id) em vez de referências literais
    - Corrigir imports e usings (ex: using MeuProjeto.Domain.Entities;)
    - Verificar se há conflitos com nomes existentes (ex: já existe uma classe Order?)
    - Sugerir uma ordem segura de alterações (ex: primeiro alterar interfaces/contratos, depois implementações)

     Para refatorações críticas é melhor usar o modo de planejamento : /plan

    /plan Refatore toda a solução para substituir o tipo `long OrderId` por `OrderId` (value object) seguindo o padrão de Domain-Driven Design.

    Impactos esperados:
    - Criar record struct OrderId (int Value)
    - Atualizar todas as entidades, comandos, queries, eventos
    - Ajustar os handlers e repositórios
    - Modificar as migrations do EF Core (criar uma nova migração com conversão de tipo)
    - Atualizar os testes

    Com esse plano, o Claude irá:

    - Listar exatamente todos os arquivos afetados (contagem e localização)
    - Identificar riscos (ex: serialização JSON pode mudar, API externas quebram)
    - Propor estratégia (ex: criar um JsonConverter customizado para compatibilidade retroativa)
    - Solicitar sua aprovação antes de executar qualquer alteraçã

    Um exemplo mais avançado seria remover a dependência circular:

    Renomeie OrderEntity para Order em toda a solução.
    Atualize imports, EF Core e repositories.

    Após a refatoração, peça:

    Rode dotnet build e dotnet test e verifique se tudo passou.
Se falhar, analise os erros e corrija automaticamente.

    Gerar Documentação OpenAPI a partir do Código ASP.NET Core

    O Claude Code pode analisar seus controllers, ações, modelos de dados e configurações de rota para gerar uma especificação OpenAPI 3.0 completa e precisa – muito além do que o pacote Swashbuckle ou NSwag oferecem por padrão, pois ele entende o contexto de negócio e pode enriquecer a documentação com exemplos reais.

    Exemplo de prompt básico:

    Leia o OrderController.cs e gere uma especificação OpenAPI 3.0 válida para todos os endpoints.
    Inclua:
    - Paths, HTTP methods, parâmetros
    - Request/response schemas (baseados nos DTOs reais)
    - Códigos de status (200, 400, 404, 500)
    - Exemplos de payload (usando dados realistas do domínio)

    Podemos melhorar usando /plan e refinamentos:

    /plan Gere uma especificação OpenAPI completa para o projeto OrderService.API:

    Requisitos:
    1. Use OpenAPI 3.0 em YAML (ou JSON)
    2. Inclua security scheme JWT Bearer (como está no Program.cs)
    3. Adicione tags para agrupar endpoints por recurso
    4. Para cada endpoint, descreva os possíveis erros com exemplos
    5. Gere exemplos de request/response com valores que façam sentido no domínio (ex: "ProductId": "prod-123")
    6. Inclua parâmetros de query (filtros, paginação) com descrições
    7. Adicione um summary e description para cada operação
    8. Valide se os schemas estão corretos (evitar referências circulares)

    O que o Claude Code faz com esse prompt:

    ✅ Lê todos os controllers, actions e atributos ([HttpGet], [Route], [FromBody], etc.)
    ✅ Extrai os DTOs de entrada/saída e mapeia suas propriedades (tipos .NET → tipos OpenAPI)
    ✅ Reconhece anotações de validação ([Required], [Range], [EmailAddress]) e traduz para required, minimum, format
    ✅ Identifica o esquema de autenticação usado (ex: [Authorize] + JWT)
    ✅ Gera exemplos realistas a partir dos nomes das propriedades (ex: para OrderDate, usa "2025-05-09T10:30:00Z")
    ✅ Mantém consistência com o versionamento (se existir ApiVersion atributo)
    ✅ Pode gerar arquivo pronto para ser usado no Swagger UI, Redoc ou ferramentas como Postman/Insomnia

    Podemos ir além da OpenAPI:

    Com base no OrderController e na OpenAPI gerada, crie um arquivo API.md com:
    - Exemplos de chamadas curl
    - Fluxos típicos (criar pedido → pagar → cancelar)
    - Guia de códigos de erro

    O claude Code vai usar a OpenAPI mais os exemplos reais e vai incluir explicações e com isso teremos uma documentação mais rica doque o NSwag e Swashbuckle pode entregar.

    Em um cenário avançado podemos ter:

    /plan Analise a diferença entre a versão 1 e 2 da API de Orders (usando [ApiVersion]).
    Gere um OpenAPI que documente ambas, indicando breaking changes e campos obsoletos.

    Executar Serviços em Background no Claude Code

    Em projetos .NET complexos, você frequentemente precisa executar múltiplos processos simultaneamente: a API principal, um consumidor RabbitMQ/Kafka, um worker de background, ou até mesmo rodar testes continuamente.

    O Claude Code oferece recursos nativos para gerenciar esses processos em segundo plano sem travar sua sessão.

    Comandos essenciais para background no Claude Code

    Exemplo prático: iniciar serviços .NET em background

    Dentro de uma sessão do Claude Code, você pode pedir:

    Inicie a aplicação ASP.NET Core OrderService.API em background usando dotnet run.
    Depois, inicie um consumer RabbitMQ separado (projeto OrderService.Worker).
    Execute os testes de integração continuamente sempre que código mudar (dotnet watch test).
    Monitore os logs de todos os serviços.

    O Claude Code irá:

    - Executar dotnet run --project src/OrderService.API em background (via shell)
    - Executar dotnet run --project src/OrderService.Worker em segundo plano
    - Configurar dotnet watch test --project tests/OrderService.IntegrationTests para rodar automaticamente
    - Registrar os PIDs e permitir que você os gerencie com /bashes e /kill

    Fluxo recomendado dentro do Claude Code :

    1. /tasks # verifica se há processos rodando
    2. dotnet run --project src/OrderService.API --no-build &
    3. dotnet run --project src/OrderService.Worker --no-build &
    4. /tasks # vê os IDs dos processos
    5. /statusline # ativa o painel ao vivo com CPU/memória/logs
    6. dotnet watch test --project tests/OrderService.IntegrationTests

    A recomendação é usar /plan para o ambiente de desenvolvimento

    /plan Configure um ambiente de desenvolvimento completo que seja reproduzível:

    1. Inicie o Docker Compose (PostgreSQL, RabbitMQ, Redis)
    2. Aguarde os contêineres estarem prontos (health check)
    3. Execute as migrations do EF Core (dotnet ef database update)
    4. Inicie a API em background (porta 5000)
    5. Inicie o worker de mensageria em background
    6. Inicie os testes contínuos (dotnet watch test)
    7. Exiba no /statusline o estado de cada serviço

    Usando Skills no Claude Code para Projetos .NET Corporativos

    As Skills são um dos recursos mais poderosos do Claude Code para organizações que precisam de padrões consistentes, redução de boilerplate e aceleração do desenvolvimento. Uma Skill encapsula conhecimento reutilizável (instruções, convenções, templates, validações) que o Claude aplica automaticamente ao executar uma tarefa específica.

    O que uma Skill pode conter (no contexto .NET):
    - Estrutura de pastas e nomes de projetos (Clean Architecture, Vertical Slices, etc.)
    - Padrões de código: CQRS com MediatR, Repositories, Unit of Work
    - Configurações padrão: Program.cs, appsettings.json, dependency injection
    - Testes automáticos: xUnit fixtures, Testcontainers, mocks com NSubstitute
    - Documentação: OpenAPI, README, comentários XML
    - Validações: FluentValidation, anotações de dados
    - Persistência: Configurações do EF Core (IEntityTypeConfiguration), migrations
    - Mensageria: Kafka/RabbitMQ consumers/producers padrão

    Exemplo básico de uso de uma Skill:

    Use a skill dotnet-clean-architecture e implemente um endpoint POST /products usando EF Core 10.

    O que acontece quando você invoca essa Skill:

    - O Claude Code carrega um conjunto de regras pré-definidas (que podem estar em um arquivo .claude/skills/dotnet-clean-architecture.md) e aplica:
    - Cria a estrutura de pastas: Application/Products/Commands/CreateProduct, Domain/Entities/Product, Infrastructure/Configurations/ProductConfiguration (supondo que isso esteja definido na skill...)
    - Gera o comando com MediatR (CreateProductCommand, CreateProductCommandHandler)
    - Adiciona validação com FluentValidation (CreateProductCommandValidator)
    - Cria o repositório específico ou usa um genérico
    - Configura o mapeamento do EF Core (relacionamentos, índices, conversões)
    - Gera os testes unitários e de integração
    - Adiciona o endpoint via Minimal API ou Controller (seguindo o padrão da Skill)

    Criando sua própria Skill para a empresa

    Você pode criar skills personalizadas para padronizar aspectos específicos do seu ecossistema .NET.

    Exemplo de estrutura de uma skill (arquivo .claude/skills/dotnet-clean-architecture.md):

    # Skill: dotnet-clean-architecture

    ## Contexto
    Aplicar a arquitetura limpa com CQRS e MediatR em projetos .NET 10.

    ## Convenções
    - Camadas: API → Application → Domain → Infrastructure
    - Commands e Queries separados por agregado (ex: Products, Orders)
    - Cada Command/Query tem: Handler, Validator, Response DTO
    - Repositórios: usar IRepository<T> genérico + implementações específicas quando necessário
    - EF Core: usar IEntityTypeConfiguration para cada entidade

    ## Implementação de um novo endpoint (POST /{recurso})
    1. Criar Command record com propriedades imutáveis
    2. Criar Handler que valida e persiste via DbContext
    3. Criar Validator usando FluentValidation (regras obrigatórias)
    4. Adicionar mapeamento (AutoMapper ou manual)
    5. Criar endpoint Minimal API: app.MapPost("/api/products", ...)
    6. Gerar teste unitário (Handler) e teste de integração (endpoint + banco real)

    ## Exemplo de código gerado
    [Fornecer templates reais de código que o Claude deve seguir]

    Onde e como definir e criar Skills:

    Fluxo recomendado para criar uma nova Skill:

    Peça ao Claude: "Crie uma skill chamada dotnet-mediatr-handler que gere commands, handlers e validators seguindo nossos padrões"

    -Claude analisa o código existente para inferir os padrões
    -Claude gera o arquivo .claude/skills/dotnet-mediatr-handler.md
    -Você revisa, ajusta e commita

    A Skill já está disponível para todo o time usar com "Use a skill dotnet-mediatr-handler..."

    Usando subagentes

    Os Subagentes são agentes auto-contidos, isolados em seu próprio contexto, que atuam de forma independente para realizar pesquisas, explorar a base de código ou fazer alterações, retornando apenas um resumo das descobertas ou o resultado final. O agente principal permanece limpo e

    Atualmente o Claude Code possui dois modelos de subagentes:

    1. Subagents dinâmicos (automáticos) - que são Criados automaticamente pelo Claude durante a execução.
    2. Subagents persistentes (customizados) -  que são  criados manualmente por você na pasta:  .claude/agents/   que fica dentro do projeto

    Benefícios Chave

    Preservação do Contexto Principal (forked contexts): Cenários de pesquisa barulhentos e logs de falhas de teste agora são descartados após o uso. Se o subagente for configurado com context: fork, o agente principal não carrega as 500 linhas de saída de um teste com falha, recebendo apenas um resumo limpo.

    Paralelismo e Velocidade: Subagentes podem executar tarefas independentes em paralelo, reduzindo drasticamente o tempo de espera (ex: um subagente inspeciona a camada de dados enquanto outro mapeia os endpoints da UI).

    Modularidade e Especialização: Permite criar agentes de IA com responsabilidades delimitadas. O agente orquestrador coordena subagentes especialistas (ex: api-agent, efcore-agent, testing-agent)

    Trabalhando com Múltiplos Subagentes

    Para projetos .NET, você pode criar subagentes especialistas e invocá-los na mesma tarefa. Eles podem ser definidos no projeto em .claude/agents/ ou globalmente em ~/.claude/agents/.

    Estrutura de um Subagente (Exemplo para .NET)

    Definido como Markdown com cabeçalho YAML (ex: efcore-agent.md):

    ---
    name: efcore-agent
    description: Projetar entidades, mapeamentos e migrações do EF Core.
    tools: ["Read", "Grep", "Glob", "Write", "Edit", "Bash(dotnet ef migrations add)"]
    model: sonnet
    ---
    Você é especialista em Entity Framework Core 10. Responsabilidades:
    1. Criar entidades (`/Domain/Entities`) seguindo o padrão da empresa.
    2. Configurar mapeamentos com `IEntityTypeConfiguration`.
    3. Gerar migrações com `dotnet ef migrations add`.
    4. Validar consultas LINQ para otimização.

    Regras: Não modificar configurações de DI ou Program.cs.

    Exemplo de orquestração:

    Implemente o módulo de Pedidos usando os seguintes subagentes:
    - api-agent: para endpoints e DTOs
    - efcore-agent: para entidades e migrações
    - testing-agent: para testes de integração

    Execute-os em paralelo para a funcionalidade CriarPedido

    O Claude Code possui agentes nativos prontos para serem usados quando necessários que você pode consultar usando o comando /agents. (Este comando também permite criar subagentes)

    Comparando Skills com Subagentes:

    Use subagentes quando: a tarefa for barulhenta, delimitada e fácil de resumir (ex: pesquisa em múltiplos arquivos, executar suite de testes que gera muito log, validação independente antes de commitar).

    Evite subagentes se: a conversa for simples e direta, ou se a troca de contexto constante não compensar a sobrecarga.

    Revisão de Código

    Claude Code vai além de ser apenas um assistente de programação — é uma ferramenta de revisão técnica extremamente poderosa, especialmente para os desafios diários do desenvolvimento .NET. Com sua capacidade de processar código e mudanças de forma contextual, ele pode funcionar como um parceiro de revisão, seja para verificar sua própria implementação localmente ou para analisar PRs inteiros.     

    Revise este Pull Request e identifique:
    - problemas de arquitetura
    - problemas de performance
    - possíveis bugs
    - melhorias para EF Core 10

    Em aplicações .NET empresariais, o Claude Code se destaca ao detectar automaticamente:

    N+1 no EF Core: Identifica padrões como foreach sobre IEnumerable que disparam consultas desnecessárias.

    Tracking desnecessário: Sugere .AsNoTracking() em consultas somente leitura para ganho de performance.

    Problemas de async/await: Detecta deadlocks potenciais (.Result, .Wait()) e caminhos que quebram o fluxo assíncrono.

    Vazamento de dependências: Aponta injeções de DbContext com lifetime errado, ou dependências transitórias em singletons.

    Violações SOLID: Captura acoplamentos diretos onde interfaces seriam mais apropriadas.

    Revisão Interativa com o Comando /review

    Durante sua sessão no terminal, o comando /review é a maneira mais rápida de submeter suas mudanças locais a uma análise completa, seguindo as regras definidas no seu CLAUDE.md. Ele examina código em busca de:

    - Clareza, legibilidade e possíveis bugs.
    - Conformidade com as diretrizes do projeto.
    - Questões de desempenho específicas do .NET.

    Exemplo de uso do /review:

    Cenário: Você está trabalhando em uma nova funcionalidade que adiciona um endpoint PUT /api/orders/{id}/cancel no OrderService. Você fez as alterações em três arquivos:

    OrdersController.cs (adicionou o endpoint)
    CancelOrderCommand.cs (novo comando MediatR)
    CancelOrderCommandHandler.cs (lógica de cancelamento)
    Antes de commitar, você quer uma revisão técnica.

    Dentro da sessão do Claude Code, você digita:

    /review Revise minhas alterações não commitadas. Verifique:
    - Problemas de async/await
    - Uso correto do EF Core (evitar N+1, tracking desnecessário)
    - Tratamento de exceções e códigos HTTP
    - Conformidade com nossa convenção de CancellationToken

    O Claude Code então:
     - Executa git diff para ver as alterações pendentes
    - Analisa cada arquivo modificado em contexto
    - Gera um relatório estruturado

    Resumo da Estratégia de Revisão para .NET

    Agrupe seus esforços de revisão em camadas:

    1. Camada Local (Antes do Commit):
    Execute /review e aplique as correções manuais sugeridas.

    2. Camada de Pull Request (Sem Automação Completa):
    Utilize Subagentes especializados (segurança, performance, regras) ativados manualmente via /task para revisões complexas em PRs que tocam múltiplos serviços.

    3. Camada de Compliance e Segurança:
    Integre o GitHub Action de Segurança para escanear automaticamente vulnerabilidades críticas, com output em JSON para governança.

    4. Camada de Automação 24/7:
    Configure Hooks críticos de escrita (ex: bloqueio de push para a main se testes falharem ou se houver SQL Injection detectado).

    Nota: Hooks no Claude Code são mecanismos que permitem executar ações automáticas antes ou depois de determinados eventos durante a execução do agente. Pense nos hooks como pontos de extensão do fluxo do Claude Code.

    Imagine que toda vez que Claude modificar código backend você queira executar testes automaticamente.
    Exemplo conceitual:
    {
      "hooks": {
         "afterEdit": [
            "dotnet test"
          ]
       }
    }

    		  

    Essas quatro camadas garantem código de alta qualidade desde o primeiro comando local até a esteira final de entrega contínua.

    Modernização de Sistemas Legados .NET

    Muitas empresas ainda possuem sistemas críticos construídos sobre tecnologias legadas:

    .NET Framework 4.x (vs .NET Core/.NET 5+)
    ASP.NET MVC 5 / WebForms
    Entity Framework 6 (vs EF Core)
    ADO.NET manual com SqlConnection, DataTables
    Windows Communication Foundation (WCF)
    Web API 2 (vs Minimal APIs / Controllers)

    O Claude Code é uma ferramenta transformadora para modernizar esses sistemas, pois entende o código antigo, planeja a migração incremental e gera o novo código compatível com .NET 10.

    Abordagem recomendada: planejamento com /plan antes da ação: 

    /plan Migre este projeto ASP.NET MVC 5 para ASP.NET Core .NET 10.
    Substitua EF6 por EF Core 10.
    Não altere código ainda.

    Inclua no plano:
    1. Análise de compatibilidade (breaking changes)
    2. Ordem de migração (projeto por projeto)
    3. Substituição de bibliotecas (ex: System.Web → Microsoft.AspNetCore)
    4. Estratégia de roteamento (Attribute Routing vs Convention)
    5. Migração de autenticação (Membership → Identity)
    6. Testes de regressão sugeridos

    O Claude Code irá gerar um plano detalhado com:
    - Arquivos mais críticos e complexos
    - Dependências circulares que precisam ser quebradas
    - Estratégia de side-by-side (executar antigo e novo simultaneamente)
    - Estimativa de esforço por módulo

    Exemplo específico: Converter ADO.NET manual para EF Core 10 

    Converta este repositório que usa ADO.NET manual (SqlCommand, DataReader) para EF Core 10.
    Mantenha a mesma assinatura de métodos (IEnumerable<T>, Task<..>).
    Gere as entidades, DbContext e mapeamentos (IEntityTypeConfiguration).

    Estratégias avançadas para grandes sistemas legados:

    Exemplo de /plan para migração WebForms → Razor Pages:

    /plan Migre a página WebForms "Products.aspx" (com code-behind) para Razor Pages no .NET 10.
    Mantenha a mesma lógica de negócio e validação.
    Use o padrão PageModel + handler methods (OnGetAsync, OnPostAsync).

    Para um sistema grande, você pode orquestrar múltiplos subagentes: (Antes você deve criar os subagentes)

    Use os subagentes:
    - legacy-analyzer (examina o código antigo e lista dependências)
    - efcore-generator (cria entidades e DbContext)
    - api-converter (converte controllers MVC para Minimal APIs)
    - test-generator (cria testes de regressão)

    Migre o módulo de Orders seguindo o plano do legacy-analyzer.

    Exemplo de prompt para um cenário real (ADO.NET + WebForms):

    Temos um sistema legado de pedidos com:
    - WebForms (30 páginas)
    - ADO.NET (15 repositórios com SQL manual)
    - .NET Framework 4.7.2

    Crie um plano de migração para .NET 10 com EF Core, priorizando o módulo de Produtos (5 páginas, 3 repositórios).
    Para cada repositório, gere o equivalente EF Core.
    Para cada página, gere a Razor Page correspondente.
    Não altere o código original – crie os novos arquivos em uma pasta /Modernized.

    Trabalhando com Migrations EF Core 10

    Um dos fluxos mais produtivos do Claude Code é ajudar a evoluir o esquema do banco de dados de forma segura e automatizada. Em vez de escrever a migration manualmente, você descreve a mudança de modelo e o Claude:

    -Altera as entidades (adiciona/remove propriedades, ajusta tipos)
    -Atualiza os relacionamentos (HasOne, HasMany, WithOne, etc.)
    -Cria uma nova migration com dotnet ef migrations add
    -Ajusta consultas existentes que usam a estrutura antiga
    -Atualiza os testes de integração que dependem do modelo

    Exemplo simples:

    Adicione suporte para múltiplos endereços no Customer.
    Um Customer pode ter vários Endereços (Addresses).
    Gere a migration EF Core 10 correspondente.

    Para mudanças complexas use o comando /plan :

    /plan Refatore o esquema de pedidos para suportar múltiplos itens com quantidade e preço unitário.
    Atualmente Order tem um ProductId e Quantity. Queremos uma tabela OrderItem.

    - Remover ProductId, Quantity e UnitPrice de Order
    - Criar entidade OrderItem com referência a Order e Product
    - Atualizar as queries e DTOs
    - Gerar a migration (com dados existentes – preciso preservar os dados atuais)

    Inclua no plano um script de migração de dados.

    Exemplos de prompts usando recursos avançados para migrações com Claude Code:

    Evitando erros comuns – Claude Code pode detectar:

    ❌ Esquecer de adicionar DbSet<Address> no DbContext
    ❌ Não incluir a nova entidade em um IEntityTypeConfiguration
    ❌ Criar uma migration que causa perda de dados (ex: drop de coluna sem aviso)
    ❌ Não ajustar consultas que projetavam a propriedade removida

    O Claude alerta e sugere correções antes de executar a migration.

    Integração com revisão e testes:

    /review Revise a migration `AddProductIsActive` e os ajustes nos repositórios. Verifique se não quebramos nenhum contrato de API.

    O Claude pode até sugerir rodar dotnet ef database update em um banco de testes (via Testcontainers) para validar a migration.

    Otimização de Performance
    O Claude Code se destaca como um consultor de performance, analisando seu código ASP.NET Core e Entity Framework Core para identificar gargalos e sugerir melhorias concretas. Você não precisa mais caçar problemas – basta descrever o cenário e o Claude Code entrega um diagnóstico com ações corretivas e exemplos de código.

    Exemplos básicos de prompt:

    Analise este endpoint ASP.NET Core e identifique gargalos de performance
    ou
    Otimize estas consultas EF Core 10 para reduzir tempo de resposta.

    Exemplo prático – análise de endpoint:  Você envia o código de um endpoint e pede

    Analise este endpoint GET /api/orders/customer/{customerId}:

    [HttpGet("customer/{customerId}")]
    public async Task<IActionResult> GetOrdersByCustomer(int customerId)
    {
    var orders = await _context.Orders
    .Where(o => o.CustomerId == customerId)
    .ToListAsync();

    foreach (var order in orders)
    {
    order.ItemsCount = await _context.OrderItems.CountAsync(i => i.OrderId == order.Id);
    }

    return Ok(orders);
    }

    Usando /review para performance:  Antes de commitar, execute /review com foco em performance:

    /review Minhas alterações vão para produção. Identifique possíveis regressões de performance.

    Exemplo de consultas EF Core complexas – otimização step-by-step:

    Preciso otimizar esta query que está lenta:

    var result = _context.Products
         .Include(p => p.Category)
         .Include(p => p.Supplier)
         .Include(p => p.Reviews)
         .Where(p => p.CategoryId == catId && p.Price > minPrice)
         .OrderBy(p => p.Name)
         .Skip(10000)
         .Take(20)
         .ToList();

    Estratégia de índices – o Claude Code até gera o código de migração:

    Sugiro criar um índice composto em Products (CategoryId, Price) e ordenar por Name.
    Migration:

    migrationBuilder.CreateIndex(
    name: "IX_Products_CategoryId_Price",
    table: "Products",
    columns: new[] { "CategoryId", "Price" });

    Comando /plan para uma análise completa da API:

    /plan Faça uma análise de performance em toda a API de Orders:
    - Liste os endpoints mais lentos (supondo que temos logs com duração)
    - Priorize os que mais impactam o usuário
    - Para cada um, sugira exatamente as mudanças de código
    - Gere testes de carga simples (usando Bombardier ou K6)

    Dica profissional – criar uma Skill de performance:  Para padronizar as revisões de performance no time, crie uma skill:

    # Skill: dotnet-performance-review

    Ao revisar código, sempre verifique:
    1. Consultas EF Core: evitar N+1, rastreamento desnecessário, projeções.
    2. Uso de IAsyncEnumerable para grandes streams.
    3. Caching de dados estáticos ou semi-estáticos.
    4. Evitar bloqueios assíncronos (.Result, .Wait()).
    5. Configuração de timeout em HttpClients.

    Depois use: Use a skill dotnet-performance-review para revisar este PR.

    Resumo para times .NET:
    ✅ Claude Code identifica problemas que geralmente passam despercebidos em code reviews manuais.
    ✅ Fornece código corrigido e pronto para implementar.
    ✅ Sugere índices e migrações completas.
    ✅ Pode gerar testes de performance (BenchmarkDotNet) para validar as melhorias.
    ✅ Quando integrado com /review, toda pull request pode ser escaneada por regressões de performance.

    Integração com Ferramentas do Ambiente

    O Claude Code não se limita a analisar e gerar código; ele também interage diretamente com as principais ferramentas do ecossistema .NET e DevOps. Isso permite criar fluxos de trabalho automatizados e contextuais, onde a IA executa comandos reais no seu ambiente.

    Ferramentas suportadas nativamente:

    Exemplos práticos dentro de uma sessão do Claude Code:

    # Ciclo completo de desenvolvimento
    Execute os testes, identifique falhas e corrija os problemas.

    O Claude irá:
    Rodar dotnet test --logger "console;verbosity=detailed"
    Analisar a saída, listar as falhas
    Identificar quais testes falharam e qual a exceção
    Propor correções no código (ou aplicá-las automaticamente)
    Reexecutar os testes para validação

    # Atualização de pacotes
    Atualize todos os packages NuGet para versões compatíveis com .NET 10.

    O Claude irá:
    Verificar o TargetFramework nos .csproj
    Executar dotnet list package --outdated
    Para cada pacote, determinar a versão mais recente compatível com .NET 10
    Executar dotnet add package <nome> --version <versão> ou editar o .csproj
    Rodar dotnet restore e dotnet build para verificar compatibilidade

    Fluxos avançados com múltiplas ferramentas:

    Usando /taksk (/bashes) para processos em background:

    Quando você inicia serviços (API, worker, banco), o Claude Code permite gerenciá-los:

    # Inicie a API e o worker em background
    dotnet run --project src/OrderService.API &
    dotnet run --project src/OrderService.Worker &

    # Liste os processos
    /bashes

    # Pare um processo específico
    /kill 12345

    Criação de scripts personalizados:  Você pode pedir ao Claude para gerar scripts que combinem várias ferramentas:

    Crie um script PowerShell chamado 'restore-and-test.ps1' que:
    - Restaura os pacotes NuGet
    - Reconstrói a solução
    - Inicia um container Testcontainer de PostgreSQL
    - Executa os testes de integração
    - Para o container ao final

    Benefícios para o dia a dia .NET:

    ✅ Redução de contexto: Não precisa alternar entre terminal, IDE e documentação.
    ✅ Automação sob demanda: Execute pipelines completos com um prompt.
    ✅ Diagnóstico rápido: Claude lê logs extensos e aponta a causa exata.
    ✅ Reprodutibilidade: Os comandos executados ficam registrados no histórico da sessão.
    ✅ Onboarding: Novos desenvolvedores podem executar tarefas complexas sem conhecer todos os comandos.

    Claude Code Como Parceiro de Desenvolvimento

    O Claude Code funciona melhor quando usado como parceiro de programação e não como substituto do desenvolvedor.

    Ainda precisamos:
    pensar na arquitetura
    revisar o código gerado
    validar regras de negócio
    garantir qualidade
    tomar decisões técnicas corretas

    O verdadeiro ganho de produtividade acontece quando o desenvolvedor sabe orientar a IA corretamente.

    Não basta apenas pedir código. É preciso saber:
    como estruturar os prompts
    como dividir problemas complexos
    como conduzir o agente
    como validar as respostas
    como fornecer contexto adequado
    como revisar criticamente o resultado

    A IA deve ser conduzida pelo desenvolvedor — e não o contrário.

    Quanto melhor forem as instruções, o contexto e a capacidade técnica de quem está utilizando a ferramenta, melhores serão os resultados produzidos.

    Mesmo assim, o Claude Code reduz drasticamente o trabalho repetitivo e acelera tarefas operacionais do backend moderno.

    Quando combinado com .NET 10 e EF Core 10, ele pode acelerar significativamente o desenvolvimento de aplicações modernas, permitindo que o desenvolvedor foque mais em arquitetura, regras de negócio e decisões estratégicas, enquanto a IA auxilia nas tarefas operacionais e repetitivas do dia a dia.

    E estamos conversados...  

    "E graças a Deus, que sempre nos faz triunfar em Cristo, e por meio de nós manifesta em todo o lugar a fragrância do seu conhecimento"
    2 Coríntios 2:14

    Referências:

    José Carlos Macoratti