Claude Code com .NET, Parte 1: da Configuração às Skills

Jornada de cinco passos com o Claude Code em .NET

Quem experimenta um assistente de código pela primeira vez costuma pular direto para o pedido ("crie uma API de tarefas") e se frustra com o resultado: nomes fora do padrão, pacotes que ninguém pediu, testes que não rodam. O problema raramente é o modelo. É que ele não conhece o projeto, não sabe o que pode executar sozinho e foi usado como autocompletar em vez de colega de trabalho. Configuração e ritmo de conversa definem a qualidade do resultado tanto quanto o pedido em si.

Este artigo percorre a jornada completa com o Claude Code, o agente de linha de comando da Anthropic, em um projeto .NET 10: instalar, escrever o CLAUDE.md, definir permissões, dominar o ritmo pedir, iterar e confirmar, criar skills e, por fim, usar tudo no kickoff de uma Minimal API com testes. Na série, o artigo sobre MCP mostrou como um modelo chega às suas ferramentas; aqui vemos como o desenvolvedor trabalha com o modelo no dia a dia. Todo o código e os arquivos de configuração estão em um repositório e foram compilados e executados.

Instalação do Claude Code e mecanismos de configuração

O Claude Code é um agente que roda no seu terminal (também há extensões para VS Code e JetBrains e um app desktop). Ele lê arquivos do projeto, edita código, executa comandos como dotnet build e dotnet test, e repete esse ciclo até concluir o pedido. Como ele age no seu repositório, três decisões importam desde o primeiro dia: o que ele precisa saber, o que ele pode fazer sozinho e quando ele deve perguntar.

Instalação e login. No Windows, pelo PowerShell (ou pelo WinGet):

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


winget install Anthropic.ClaudeCode


claude --version

Na primeira execução de claude, o login abre no navegador; depois, /login troca de conta. Entre na pasta do projeto antes de iniciar, porque ela define o que o Claude enxerga.

Os quatro mecanismos de configuração são:

• CLAUDE.md: instruções em texto que entram no contexto de toda sessão. Fica em ./CLAUDE.md (ou ./.claude/CLAUDE.md) para o time, em ~/.claude/CLAUDE.md para você em todos os projetos e em ./CLAUDE.local.md para preferências pessoais do projeto (fora do git). O comando /init gera um primeiro rascunho a partir do código.
• settings.json: regras de permissão e demais opções. Existe em ~/.claude/settings.json (usuário), .claude/settings.json (projeto, versionado) e .claude/settings.local.json (pessoal, fora do git). O nível mais específico vence.
• Modos de permissão: definem quando o Claude pergunta. Os principais são default (pergunta antes de editar ou executar), acceptEdits (aceita edições de arquivo), plan (só lê e propõe um plano) e auto (um classificador revisa as ações no seu lugar). Shift+Tab alterna entre eles na sessão.
• Skills: procedimentos reutilizáveis, uma pasta com um SKILL.md, que o Claude carrega quando a tarefa combina com a descrição ou quando você chama /nome.

Atenção ao modo inicial: a partir da versão 2.1.283 o modo auto é o inicial em sessões interativas do terminal. Confira o modo ativo na barra de status e, em projeto novo, comece em plan ou default até confiar nas regras.

O CLAUDE.md pode importar outros arquivos com @caminho, o que evita duplicar texto:

Visão geral e como rodar: @README.md

Regras de permissão têm o formato Tool(padrão), avaliadas na ordem deny, ask, allow; a primeira que casa decide. Um espaço antes do * final importa: Bash(dotnet test *) casa dotnet test e dotnet test --no-build, mas não dotnet testx.

Ciclo pedir, planejar e iterar no Claude Code, com skills

A abordagem é um ciclo com portões de confirmação. Você pede, o Claude planeja, executa, você revisa e só então registra o resultado.

Pedir. Um bom pedido tem objetivo, restrições e critério de pronto. Compare:

Antes:  crie uma API de tarefas





Depois: Crie uma Minimal API de tarefas em .NET 10 com lista em


        memória (criar, obter, listar, concluir). Sem banco e sem


        pacotes extras. Pronto quando dotnet build e dotnet test


        passarem.

Planejar. Para mudanças que tocam vários arquivos, inicie em modo plano. O Claude lê o código, propõe o plano e não edita nada até você aprovar:

claude --permission-mode plan

Na sessão, /plan e Shift+Tab entram nesse modo. Ao terminar, o Claude apresenta o plano com três saídas: aprovar e seguir em modo auto, aprovar e revisar cada edição, ou continuar planejando com seus ajustes. Ctrl+G abre o plano no editor para você alterá-lo antes de aprovar.

Executar e revisar. Com o plano aprovado, o Claude edita e roda dotnet build e dotnet test. As regras allow do settings.json evitam interrupções nos comandos seguros; as regras ask mantêm o portão em git commit e git push.

Iterar. Peça um ajuste por vez e por escrito, em vez de refazer o pedido inteiro. Esc interrompe uma ação em andamento, /rewind volta conversa e código a um ponto anterior e /clear começa uma conversa nova, o que vale ao trocar de tarefa. Com a conversa longa, /compact resume o histórico.

Reaproveitar. Quando você repete o mesmo roteiro, vire skill. A estrutura é uma pasta e um arquivo:

.claude/skills/


  novo-endpoint/


    SKILL.md          instruções (obrigatório)


  pronto-para-commit/


    SKILL.md

O SKILL.md tem um cabeçalho YAML (name, description, e opcionalmente argument-hint, allowed-tools, disable-model-invocation) seguido das instruções. A description é o que o Claude lê para decidir quando usar a skill.

Próximo passo. Com o CLAUDE.md, o settings.json, os modos de permissão e as skills definidos, falta aplicar tudo. Na Parte 2 esta configuração entra em uso no kickoff de uma Minimal API em .NET 10 com testes, do repositório ao commit.

Referências da Parte 1: docs do Claude Code e repositório

• Código do artigo no GitHub: ceseidl/claude-code-dotnet
• Claude Code: Quickstart
• Claude Code: Como o Claude lembra do seu projeto (CLAUDE.md)
• Claude Code: Skills
• Claude Code: Settings e Permissões
• Claude Code: Modos de permissão
• Claude Code: Referência de comandos e MCP
• Série: MCP em .NET: Conectando Modelos de IA a Ferramentas e Dados (ceseidl/mcp-dotnet)

Leia também

• Claude Code com .NET, Parte 2: continua a série e aplica a configuração num projeto real com testes.
• Estrutura de um Projeto Claude Code: detalha o que vai em cada arquivo e pasta do projeto configurado aqui.
• MCP em .NET: Conectando Modelos de IA a Ferramentas e Dados: mostra como dar a modelos de IA acesso a ferramentas e dados via MCP.

Quer levar IA e Claude Code para o fluxo do seu time .NET? Conheça o serviço de backend e arquitetura .NET.