Claude Code no .NET: projetos, testes e debug com IA

O que é o Claude Code no .NET

O Claude Code é um agente de programação da Anthropic que roda no terminal e também se integra a editores como o VS Code. Ele lê o código, edita arquivos e executa comandos, sempre dentro das permissões que você concede.

Na prática, isso significa que ele não apenas sugere trechos de código. Ele cria pastas, roda o dotnet build, executa testes e interpreta as mensagens de erro do compilador.

Por isso, o Claude Code no .NET funciona como um par de programação que domina o CLI da plataforma. A diferença em relação a um chat comum está na capacidade de agir sobre o repositório inteiro.

A documentação oficial descreve esse comportamento na visão geral do Claude Code. Vale a leitura antes de liberar permissões amplas para o agente.

O ponto central deste artigo, no entanto, não é a ferramenta em si. O que faz diferença é a forma como você descreve o que quer, e é aí que entram os arquivos de especificação.

Arquivos de especificação como base do método

Um prompt solto em uma janela de chat gera resultados imprevisíveis. Um arquivo markdown versionado, com regras claras, gera resultados repetíveis.

Essa é a mesma lógica do spec driven development, em que a especificação vira a fonte da verdade do projeto. Em vez de conversar com a IA, você entrega um contrato.

O experimento publicado pelo Round The Code usa exatamente essa abordagem. Cada tarefa ganha um arquivo numerado, como 01-create-project.md, 02-create-unit-tests.md e 03-add-comments.md.

# 01-create-project.md

## Stack
- .NET 10 and C# 14
- SQL Server with Entity Framework Core

## Solution
- Create a `.slnx` solution named `Store`
- Projects: `Store.Api`, `Store.Application`, `Store.Infrastructure`
- Enable Central Package Management with `Directory.Packages.props`

## Coding rules
- Use file scoped namespaces
- One type per file
- Pass `CancellationToken` to every async call
- Do not add comments

## Endpoint
- GET /api/products returns every product where `IsDeleted` is false

## Verification
- Run `dotnet build` and `dotnet run`
- Confirm the Swagger page loads
- Generate a CLAUDE.md with these rules

# Prompt usado para criar o projeto
/plan Read 01-create-project.md and plan how you are going to build it

Criando um projeto com Claude Code no .NET

A primeira tarefa do experimento parte de uma pasta vazia contendo apenas o arquivo de especificação. A partir dele, o agente monta uma solução completa em Clean Architecture.

<!-- Directory.Packages.props -->
<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>
  <ItemGroup>
    <PackageVersion Include="Microsoft.EntityFrameworkCore.SqlServer" Version="10.0.0" />
    <PackageVersion Include="Swashbuckle.AspNetCore" Version="10.0.0" />
  </ItemGroup>
</Project>

namespace Store.Api.Endpoints;

public static class ProductEndpoints
{
    extension(IEndpointRouteBuilder app)
    {
        public IEndpointRouteBuilder MapProductEndpoints()
        {
            app.MapGet("/api/products", GetProductsAsync);
            return app;
        }
    }

    public static async Task<IResult> GetProductsAsync(
        IProductService productService,
        CancellationToken cancellationToken)
    {
        var products = await productService.GetActiveAsync(cancellationToken);
        return Results.Ok(products);
    }
}

Escrevendo testes unitários com Claude Code no .NET

A segunda tarefa reaproveita a mesma ideia. Um novo arquivo, 02-create-unit-tests.md, descreve como os testes devem ser escritos.

O plano gerado listou os métodos de serviço, repositório e endpoint que precisavam de cobertura. Em seguida, detalhou a criação dos projetos de teste, a instalação dos pacotes e a atualização do CLAUDE.md com as convenções de testes.

namespace Store.ApplicationTests.Services;

public class ProductServiceTests
{
    private readonly Mock<IProductRepository> _repository;
    private readonly ProductService _service;

    public ProductServiceTests()
    {
        _repository = new Mock<IProductRepository>();
        _service = new ProductService(_repository.Object);
    }

    [Fact]
    public async Task GetActiveAsync_ReturnsOnlyActiveProducts()
    {
        // Arrange
        var cancellationToken = TestContext.Current.CancellationToken;
        _repository
            .Setup(r => r.GetActiveAsync(cancellationToken))
            .ReturnsAsync([new Product { Id = 1, Name = "Keyboard" }]);

        // Act
        var act = await _service.GetActiveAsync(cancellationToken);

        // Assert
        Assert.Single(act);
    }
}

Documentando o código com Claude Code no .NET

O primeiro arquivo proibia comentários de propósito. Assim, a terceira tarefa adiciona a documentação depois, com regras próprias definidas em 03-add-comments.md.

A especificação ativa a propriedade GenerateDocumentationFile nos projetos Api, Application e Infrastructure. Com ela, o compilador emite o aviso CS1591 para todo membro público sem documentação, segundo a referência de comentários XML do C#.

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

A regra seguinte é clara: corrigir cada aviso, nunca suprimi-lo. Desse modo, o build passa a funcionar como uma checagem automática de documentação.

Além disso, cada comentário precisa ter no máximo 60 caracteres e descrever o que o membro faz, sem repetir o nome dele. Nas implementações de interface, o Claude Code no .NET usa <inheritdoc /> e mantém a documentação completa na interface.

namespace Store.Application.Products;

/// <summary>
/// Reads products from the data store.
/// </summary>
public interface IProductRepository
{
    /// <summary>
    /// Gets products that are not deleted.
    /// </summary>
    /// <param name="cancellationToken">Cancels the operation.</param>
    /// <returns>The active products.</returns>
    Task<IReadOnlyList<Product>> GetActiveAsync(CancellationToken cancellationToken);
}

/// <inheritdoc />
public sealed class ProductRepository(StoreDbContext context) : IProductRepository
{
    /// <inheritdoc />
    public async Task<IReadOnlyList<Product>> GetActiveAsync(CancellationToken cancellationToken)
        => await context.Products
            .Where(p => !p.IsDeleted)
            .ToListAsync(cancellationToken);
}

Nos projetos de teste, a regra muda. Só entram os comentários // Arrange, // Act e // Assert, que deixam a estrutura de cada teste evidente.

Por fim, o Claude Code no .NET substituiu no CLAUDE.md a regra antiga de não comentar pelas novas regras de documentação. Isso mostra como o arquivo de convenções evolui junto com o projeto.

O limite de 60 caracteres resolve um problema comum dos modelos, que tendem a escrever comentários longos demais. Por outro lado, a IA raramente erra ortografia e mantém os parâmetros documentados em sincronia com a assinatura dos métodos.

Depurando exceções com Claude Code no .NET

Seguir regras de arquitetura é uma coisa. Encontrar a causa de um erro em produção, no entanto, exige outro tipo de raciocínio.

Ao chamar /api/products, a API retornou um erro 500 com uma exceção do SQL Server. O autor então pediu ajuda ao agente com um prompt simples, sem arquivo de especificação.

I ran the project. Went to run /api/products, but I get a SQL Server error. Can you debug it for me?

# Cria a migration inicial e aplica no banco
dotnet ef migrations add InitialCreate --project src/Store.Infrastructure --startup-project src/Store.Api
dotnet ef database update --project src/Store.Infrastructure --startup-project src/Store.Api

Boas práticas para usar o Claude Code no .NET

O experimento deixa algumas lições que valem para qualquer projeto. A primeira é tratar a especificação como código: versionada, revisada e reutilizada.

A segunda é sempre começar pelo planejamento. Revisar um plano é rápido, enquanto desfazer dezenas de arquivos gerados com a premissa errada consome tempo.

A terceira é incluir critérios de verificação na própria especificação. Quando o arquivo exige dotnet build, dotnet test e uma checagem do Swagger, o Claude Code no .NET valida o próprio trabalho antes de entregar.

Também convém manter o CLAUDE.md atualizado a cada etapa. Ele funciona como a memória do projeto e evita que regras se percam entre sessões.

Por outro lado, a IA não elimina a revisão humana. Você continua responsável por avaliar o código, aprovar o plano e decidir o que entra no repositório.

Por fim, configure as permissões com cuidado. O Claude Code no .NET executa comandos reais, então vale restringir o que ele pode fazer sem confirmação, principalmente em repositórios de produção.

O que isso significa para o desenvolvedor .NET

O autor do experimento afirma que a IA é assustadoramente boa nessas tarefas. Mesmo assim, em uma enquete feita por ele no LinkedIn, apenas 6% dos desenvolvedores disseram ter perdido o emprego por causa da IA.

Na leitura dele, esse número baixo reflete a lentidão das empresas em adotar a tecnologia. Contudo, a adoção tende a acelerar, e quem não dominar essas ferramentas pode ficar para trás.

Na prática, o papel do desenvolvedor muda de foco. Saber escrever uma boa especificação, revisar um plano e validar o resultado passa a valer tanto quanto digitar código rapidamente.

Isso não reduz a importância do conhecimento técnico, muito pelo contrário. Para escrever uma especificação que exige Central Package Management, extension members e <inheritdoc />, você precisa conhecer cada um desses recursos.

Em outras palavras, o Claude Code no .NET amplifica quem já domina a plataforma. Ele transforma conhecimento em entrega com muito mais velocidade.

Conclusão

O experimento mostra que o Claude Code no .NET entrega resultados consistentes em quatro frentes: criar projetos, escrever testes, documentar código e depurar exceções. Em todas elas, o segredo está em uma especificação clara e verificável.

Além disso, o modo de planejamento dá ao desenvolvedor o controle sobre o que será feito antes de qualquer alteração. Somado ao CLAUDE.md, ele garante que as regras do projeto sobrevivam entre sessões.

Se você ainda cria projetos e testes manualmente, vale começar por uma tarefa pequena. Escreva uma especificação, peça um plano, revise e só então execute.

Com o tempo, seus arquivos de especificação viram ativos reutilizáveis da equipe. É assim que a IA deixa de ser um atalho pontual e passa a fazer parte do processo de engenharia.

FAQ

O Claude Code funciona com o Visual Studio?

O Claude Code roda no terminal e tem extensões oficiais para VS Code e JetBrains. Com o Visual Studio, você pode usá-lo pelo terminal integrado, lado a lado com o editor.

Preciso escrever uma especificação para cada tarefa?

Não é obrigatório, mas tarefas repetitivas ganham muito com isso. Para pedidos pontuais, como a depuração do experimento, um prompt direto costuma bastar.

O que é o arquivo CLAUDE.md?

É um arquivo markdown com as convenções do projeto, lido pelo Claude Code no início de cada sessão. Ele evita que você precise repetir as regras a cada conversa.

O modo de planejamento altera arquivos?

Não. No modo de planejamento, o agente apenas analisa o contexto e propõe um plano, aguardando sua aprovação para executar.

A IA substitui o desenvolvedor .NET?

Os dados do experimento não indicam isso. O papel muda para especificar, revisar e validar, o que exige ainda mais conhecimento da plataforma.