Claude Code na prática: como usar IA para gerar projetos .NET com Clean Architecture

O papel da especificação no Claude Code com Clean Architecture

Antes de pedir ao Claude Code para criar qualquer coisa, prepare um arquivo de especificação. Esse arquivo geralmente se chama spec.md e funciona como um contrato entre você e a ferramenta.

Sem esse documento, o agente não sabe qual stack você usa, qual padrão arquitetural deseja, quais endpoints precisam existir ou qual banco de dados será utilizado. Em outras palavras, ele vai preencher as lacunas com suposições próprias.

Com um spec.md bem escrito, por outro lado, o Claude Code com Clean Architecture parte de um contexto sólido desde o primeiro prompt. Dessa forma, o código gerado tende a seguir as suas expectativas, e não as preferências padrão do modelo.

Além disso, o arquivo funciona como documentação viva do projeto. Você pode pedir que o próprio agente atualize a especificação sempre que fizer uma alteração relevante, mantendo um registro das decisões de implementação.

O que incluir no spec.md

O arquivo de especificação deve cobrir cinco áreas principais. São elas a stack tecnológica, a arquitetura, a estrutura de arquivos, os endpoints da API e a configuração do banco de dados.

CurrencyConverter/
├── CurrencyConverter.Domain/
├── CurrencyConverter.Application/
├── CurrencyConverter.Infrastructure/
├── CurrencyConverter.Api/
└── CurrencyConverter.Tests/

Exemplo prático: Currency Converter API

Para ilustrar o processo, vamos usar um exemplo real: uma API de conversão de moedas. O objetivo é criar uma API em .NET 8 com Clean Architecture que lista as moedas disponíveis e converte valores entre elas.

O spec.md desse projeto começaria assim:

# Specification: Currency Converter API

## Stack
- .NET 8 (LTS)
- C# 12
- ASP.NET Core Web API
- Entity Framework Core 8 with SQL Server
- Clean Architecture

## Architecture
- Domain: Currency and ExchangeRate entities, ICurrencyRepository and IExchangeRateRepository interfaces
- Application: GetAllCurrencies and ConvertCurrency use cases, matching DTOs
- Infrastructure: DbContext, repository implementations, EF Core migrations
- Api: CurrencyController exposing the endpoints below

## Endpoints
- GET /api/currencies: returns all registered currencies
- POST /api/currencies/convert: receives amount, source and target currency, returns the converted amount

## Database
- Local SQL Server
- Connection string: Server=localhost;Database=CurrencyDb;Trusted_Connection=True

Com esse documento, o agente tem todas as informações necessárias para gerar o projeto de forma coerente. Por exemplo, a interface de repositório descrita na camada Domain pode resultar em algo como:

namespace CurrencyConverter.Domain.Repositories;

// contrato definido no Domain e implementado na Infrastructure
public interface ICurrencyRepository
{
    Task<IReadOnlyList<Currency>> GetAllAsync(CancellationToken cancellationToken = default);
    Task<Currency?> GetByCodeAsync(string code, CancellationToken cancellationToken = default);
}

Instalação e configuração no Windows

Antes de usar o Claude Code com Clean Architecture, você precisa instalar a ferramenta, que funciona em Windows, macOS e Linux. No Windows, o PowerShell é o caminho recomendado tanto para instalar quanto para usar o agente no dia a dia.

Atualmente, a Anthropic recomenda o instalador nativo, que não depende do Node.js e se atualiza sozinho em segundo plano. No PowerShell, a instalação é feita com um único comando:

irm https://claude.ai/install.ps1 | iex

Também existe a opção pelo WinGet, com o comando winget install Anthropic.ClaudeCode. Além disso, o pacote npm continua disponível para quem já tem o Node.js instalado:

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

Após a instalação, pode aparecer uma mensagem informando que o executável não está no PATH. Nesse caso, copie o caminho indicado, adicione uma nova entrada na variável Path do usuário e reinicie o terminal.

Em seguida, confirme a instalação com claude --version e, se algo parecer errado, execute claude doctor. Depois, navegue até a pasta do projeto e inicie a ferramenta:

cd C:\projects\CurrencyConverter
claude

Na primeira execução, a ferramenta abre o navegador para você fazer login com sua conta. Alternativamente, você pode usar uma conta do Console da Anthropic, com cobrança direta por uso da API.

Planos e preços

Antes de usar a ferramenta de forma intensiva, entenda os custos envolvidos. O plano gratuito do Claude não inclui o Claude Code, então você precisa de pelo menos uma assinatura Pro.

O plano Pro atende quem está começando a experimentar o Claude Code com Clean Architecture em projetos pessoais. Por outro lado, se os limites forem atingidos com frequência, o plano Max oferece cotas mais altas para uso intensivo.

Para equipes e empresas, existem os planos Team e Enterprise, com recursos adicionais de gerenciamento. O artigo sobre os planos do Claude em 2026 compara as opções em detalhe.

Os preços mudam com frequência. Por isso, consulte sempre a página oficial de preços da Anthropic antes de escolher um plano.

Gerando o projeto com Claude Code com Clean Architecture

Com a ferramenta rodando e o spec.md pronto, o processo começa com uma instrução simples. No terminal, você pode escrever algo como:

Read the spec.md file and create the .NET project as described in it.

A partir desse ponto, o agente pede permissão antes de cada ação significativa. Ele pode solicitar autorização para criar uma pasta, escrever um arquivo, executar um comando do .NET CLI ou alterar um arquivo existente.

Esse comportamento é intencional e mantém você no controle do que acontece no projeto. Para cada solicitação, você pode aprovar, recusar ou pedir esclarecimentos antes de seguir.

Durante a criação de um projeto com várias camadas, porém, isso gera muitas confirmações. Na prática, usar o Claude Code com Clean Architecture em uma solution nova pode exigir dezenas de aprovações.

Gerenciando permissões com modos de execução

Para projetos novos, em que você confia no processo, é possível reduzir as interrupções do Claude Code com Clean Architecture usando os modos de permissão. A documentação oficial sobre modos de permissão descreve cada um deles.

Para iniciar com um modo específico, use o parâmetro --permission-mode:

claude --permission-mode acceptEdits

O modo acceptEdits aprova automaticamente edições de arquivos e comandos simples de sistema de arquivos dentro da pasta de trabalho. Contudo, outros comandos, como a execução do .NET CLI, ainda pedem confirmação.

Também existe o modo plan, que apenas lê o projeto e apresenta um plano antes de alterar qualquer coisa. Esse modo combina bem com o Claude Code com Clean Architecture, porque você revisa a divisão de camadas antes da primeira linha de código.

Durante a sessão, a combinação Shift+Tab alterna entre os modos disponíveis.

Para ambientes controlados em que você deseja remover todas as confirmações, existe o parâmetro --dangerously-skip-permissions:

claude --dangerously-skip-permissions

Use esse parâmetro com muita cautela. Nesse modo, o agente executa tudo sem nenhuma barreira, o que pode levar a alterações indesejadas quando o contexto não está bem especificado.

Validando o código do Claude Code com Clean Architecture

Após a geração, abra a solution no Visual Studio 2022 e confira a estrutura. No exemplo da Currency Converter API, o primeiro ponto é verificar se as quatro camadas viraram projetos separados.

Em seguida, confira as referências entre projetos, que mostram se o Claude Code com Clean Architecture respeitou a direção das dependências. O Domain não deve referenciar nenhum outro projeto, enquanto a Infrastructure referencia o núcleo da aplicação para implementar suas interfaces.

Depois, abra o arquivo appsettings.json da camada de API e verifique a string de conexão:

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=CurrencyDb;Trusted_Connection=True;TrustServerCertificate=True"
  }
}

Com a string correta, aplique as migrações do Entity Framework Core para criar o banco. Como o DbContext fica na Infrastructure e a configuração fica na API, informe os dois projetos ao comando:

dotnet ef database update --project CurrencyConverter.Infrastructure --startup-project CurrencyConverter.Api

Esse comando cria o banco e aplica as migrações geradas, montando as tabelas conforme as entidades do Domain. A referência das ferramentas do EF Core explica a diferença entre projeto de destino e projeto de inicialização.

Testando a API do Claude Code com Clean Architecture

Com o banco criado e populado (caso o agente tenha gerado dados iniciais), execute a API:

dotnet run --project CurrencyConverter.Api

Você pode testar os endpoints pelo Swagger UI, que o template de Web API do ASP.NET Core 8 habilita em ambiente de desenvolvimento. Ferramentas como Postman e HTTPie também funcionam bem.

Para listar as moedas, envie uma requisição para GET https://localhost:5001/api/currencies. A resposta esperada é uma lista parecida com esta:

[
  { "code": "BRL", "name": "Brazilian Real" },
  { "code": "USD", "name": "US Dollar" },
  { "code": "GBP", "name": "Pound Sterling" }
]

Para testar a conversão, envie uma requisição POST para o endpoint de conversão:

POST https://localhost:5001/api/currencies/convert
Content-Type: application/json

{
  "amount": 100,
  "fromCurrency": "BRL",
  "toCurrency": "GBP"
}

No exemplo demonstrado no vídeo original, a conversão de R$ 100 para libras retornou aproximadamente £ 14. Esse resultado confirma que os endpoints funcionam e que o Claude Code com Clean Architecture implementou a lógica de conversão na camada correta.

O arquivo CLAUDE.md e o ciclo de documentação

O agente lê automaticamente um arquivo chamado CLAUDE.md na raiz do projeto no início de cada sessão. Por isso, quando você usa o Claude Code com Clean Architecture, esse arquivo funciona como memória persistente das regras de cada camada.

Você pode gerar uma primeira versão com o comando /init e depois pedir que o agente a mantenha atualizada. Nela ficam as decisões arquiteturais, os endpoints criados, as dependências instaladas e as instruções para as próximas interações.

Por exemplo, depois de adicionar um endpoint de autenticação, peça ao agente que registre o novo endpoint e seu comportamento no CLAUDE.md. Isso mantém a consistência, principalmente em equipes em que várias pessoas usam a ferramenta.

Você também pode editar o arquivo manualmente para incluir convenções de nomenclatura e regras de negócio. O guia sobre como otimizar o Claude com .NET traz recomendações para estruturar esse conteúdo.

Integração com o Visual Studio 2022

Por padrão, a ferramenta opera pelo terminal, o que obriga a alternar entre editor e console. Para tornar o fluxo mais fluido, é possível integrá-la ao Visual Studio 2022.

No momento da escrita deste artigo, não existe uma extensão oficial da Anthropic para o Visual Studio 2022. Porém, há uma extensão não oficial disponível no Visual Studio Marketplace.

Para instalá-la, acesse o menu Extensions, clique em Manage Extensions, pesquise por "Claude Code" na aba Online e instale. Depois, reinicie o Visual Studio para carregar a extensão.

Em seguida, abra View, depois Other Windows, e selecione a janela do Claude Code. Com isso, você usa o Claude Code com Clean Architecture direto da IDE, sem trocar de janela.

Integração com o Visual Studio Code

Para quem prefere o Visual Studio Code, a situação é ainda melhor. A Anthropic publica uma extensão oficial, disponível no marketplace do editor.

Para instalar, abra o painel de extensões com Ctrl+Shift+X, pesquise por "Claude Code" e escolha a extensão da Anthropic. Assim, a ferramenta aparece como um painel lateral, ao lado do código e do terminal.

A extensão também mostra as alterações propostas diretamente no editor, o que facilita a revisão. Quem usa Rider ou outra IDE da JetBrains também conta com um plugin oficial.

Boas práticas do Claude Code com Clean Architecture

Algumas práticas melhoram a qualidade do código gerado e evitam problemas comuns. Confira as principais:

• Fixe a versão do .NET no spec.md. Isso evita APIs obsoletas e estilos de código desatualizados.
• Descreva as interfaces antes das implementações. Quando o Domain já define os contratos, o agente cria implementações mais coerentes e testáveis.
• Peça testes desde o início. Uma seção sobre testes com xUnit e Moq faz o agente escrever os testes junto com o código de produção.
• Revise o CLAUDE.md com frequência. Ele precisa refletir o estado atual da arquitetura, das convenções e das regras de negócio.
• Use o Git antes de cada sessão. Assim, qualquer alteração indesejada pode ser revertida com um comando.

Em projetos grandes e já existentes, mantenha o modo de permissão padrão. Nesse caso, as confirmações funcionam como um ponto de controle importante.

Em projetos novos e pequenos, por outro lado, modos mais permissivos aceleram o trabalho. Mesmo assim, o Claude Code com Clean Architecture só entrega bons resultados quando alguém revisa o que foi gerado.

Para ir além, o artigo sobre como fazer o Claude escrever código de qualidade em .NET aprofunda técnicas de revisão e padronização.

Conclusão

Usar o Claude Code com Clean Architecture mostra como a IA pode acelerar o desenvolvimento no ecossistema .NET. A combinação de um spec.md bem estruturado com a capacidade do agente permite criar projetos inteiros em uma fração do tempo.

O exemplo da Currency Converter API mostra que é possível gerar uma API .NET 8 funcional, com camadas, banco de dados, migrações e endpoints testáveis. Tudo isso a partir de uma especificação escrita em Markdown.

Além disso, as integrações com Visual Studio e Visual Studio Code reduzem a troca de contexto entre ferramentas. Contudo, o segredo não está apenas na qualidade da IA, e sim na qualidade da especificação que você entrega a ela.

Portanto, quanto mais detalhado e preciso for o seu spec.md, mais fiel ao seu design será o resultado do Claude Code com Clean Architecture.

FAQ

O Claude Code funciona offline?

Não. A ferramenta precisa de conexão com a internet, porque as requisições são processadas nos servidores da Anthropic.

Preciso de uma conta paga para usar o Claude Code?

Sim. É necessário ter pelo menos o plano Pro ou uma conta com cobrança pela API, pois o plano gratuito não inclui a ferramenta.

O Claude Code pode modificar arquivos existentes?

Sim. Ele lê, altera e exclui arquivos do projeto, por isso use controle de versão antes de iniciar cada sessão.

O arquivo spec.md precisa ter exatamente esse nome?

Não. Você pode usar outro nome, desde que o referencie corretamente no prompt, mas spec.md é a convenção mais comum.

O Claude Code lida bem com projetos grandes já existentes?

Sim, com ressalvas. Em bases muito grandes, a janela de contexto pesa, e um CLAUDE.md bem escrito ajuda a resumir o projeto.

Posso usar outros bancos além do SQL Server?

Sim. Basta indicar no spec.md o banco desejado, como PostgreSQL, SQLite ou MySQL, já que o EF Core tem provedores para todos eles.

O Claude Code substitui o desenvolvedor?

Não. O desenvolvedor continua responsável por revisar o código, entender a arquitetura e tomar as decisões de design.

Como proteger strings de conexão e outros segredos?

Use variáveis de ambiente ou o Secret Manager do .NET. Nunca grave credenciais no spec.md nem em código versionado.