Claude Code for .NET Developers: A Practical Getting Started Guide

What Claude Code is (and is not)

Claude Code is Anthropic’s coding agent. It reads your codebase, understands your project structure, and makes multi-file changes based on natural language instructions.

What it is:

• An agent that runs alongside your IDE (Visual Studio, VS Code, Rider, or any editor)
• Capable of reading entire directory structures and understanding project context
• Able to execute shell commands (dotnet build, dotnet test, git diff)
• Available as a terminal CLI, web app, desktop app, and CI runner

What it is not:

• A replacement for code review (everything it produces needs human review)
• Infallible (it makes mistakes, particularly with complex business logic)
• A deployment tool (it does not deploy or provision infrastructure)
• The only AI tool your team needs (inline completion tools are complementary, not competing)

For .NET developers, Claude Code delivers the most value on tasks that touch many files at once: migrating .NET Framework to .NET 10, refactoring a domain concept, generating tests across a service layer, or updating an API contract and all its consumers. For single-file editing, an inline completion tool is faster.

Installation

Windows (PowerShell)

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

The native installer is recommended over the npm package. It auto-updates and handles PATH configuration.

Install Git for Windows if you have not already. Claude Code uses the Bash tool for shell commands; without Git for Windows it falls back to PowerShell, which works but with a different command surface.

macOS, Linux, and WSL

curl -fsSL https://claude.ai/install.sh | bash

Package managers

# Windows WinGet
winget install Anthropic.ClaudeCode

# macOS Homebrew (stable channel)
brew install --cask claude-code

WinGet and Homebrew installations do not auto-update. Run winget upgrade Anthropic.ClaudeCode or brew upgrade claude-code periodically.

Start a session

cd /path/to/MySolution
claude

Log in on first use. Your credentials are stored and reused. Run /help to see available commands.

How Claude Code reads your project

Claude Code loads context from several sources at session start:

• AGENTS.md at the repository root (portable, read by any compliant agent)
• CLAUDE.md at the repository root or .claude/CLAUDE.md (Claude Code-specific)
• .claude/settings.json for permissions, hooks, and environment variables
• ~/.claude/CLAUDE.md for your personal global instructions

Use @filename in a prompt to pull a specific file into context. Claude Code also crawls the project structure to understand the solution layout.

AGENTS.md versus CLAUDE.md

AGENTS.md is the portable instruction surface. It follows the Agent Skills open standard and works with Cursor, Claude Code, and other tools. Put your target framework, coding conventions, dependency preferences, and architectural rules here.

CLAUDE.md is Claude Code-specific. Put workflow instructions here: when to run /compact, which skills to invoke for which tasks, session start reminders.

Keep CLAUDE.md under 300 lines. Above that, instructions are applied less reliably under context pressure. Style rules belong in .editorconfig and Directory.Build.props, not CLAUDE.md.

A good AGENTS.md for a .NET 10 project

# Project: OrderManagement

## Overview
E-commerce order management system. ASP.NET Core Web API (.NET 10) with
EF Core 10, SQL Server, and Azure Service Bus for async operations.

## Architecture
- Clean architecture: Domain, Application, Infrastructure, API layers
- CQRS with MediatR for command/query separation
- Domain events published via Azure Service Bus

## Conventions
- File-scoped namespaces
- Primary constructors for services with injected dependencies
- ILogger<T> for all logging
- IOptions<T> for all configuration sections
- TimeProvider (injected) for all date/time operations (not DateTime.Now)
- Nullable reference types enabled project-wide
- Implicit usings enabled
- No regions (#region)
- IExceptionHandler for cross-cutting error handling

## Libraries
- EF Core 10 (fluent API only, no data annotations)
- MediatR for CQRS
- FluentValidation for input validation
- Mapster for object mapping
- Polly for resilience policies
- xUnit, NSubstitute, FluentAssertions for testing

## Rules
- All API endpoints return ActionResult<T>
- All async methods accept CancellationToken
- All EF read queries use AsNoTracking()
- Repository methods return domain entities, never DTOs
- Mapping to DTOs happens in MediatR handlers

## Do not
- Use DateTime.Now or DateTime.UtcNow (use TimeProvider)
- Use static HttpClient (use IHttpClientFactory)
- Use ConfigurationManager (use IConfiguration)
- Use Thread.Sleep (use await Task.Delay)
- Add #region blocks
- Use data annotations for EF Core mapping

This fits in under 50 lines. The agent reads it and applies the conventions consistently. There is no need to restate these rules in each prompt.

Pre-approve the commands you actually use

The single most productive configuration change for a .NET developer is pre-approving the safe commands. By default, Claude Code prompts before every dotnet build. On a 30-file refactor that is 30 prompts. Pre-approving eliminates that friction without giving up safety.

Create .claude/settings.json in your repository:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(dotnet build*)",
      "Bash(dotnet test*)",
      "Bash(dotnet format*)",
      "Bash(dotnet restore*)",
      "Bash(dotnet ef migrations*)",
      "Bash(dotnet ef database update*)",
      "Bash(dotnet tool*)",
      "Bash(git status)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(git branch*)",
      "Read(**/*)"
    ],
    "deny": [
      "Bash(rm -rf bin*)",
      "Bash(rm -rf obj*)",
      "Bash(rm -rf .git*)",
      "Bash(curl*)",
      "Bash(wget*)",
      "Bash(git push --force*)",
      "Bash(git reset --hard*)",
      "Bash(dotnet nuget add source*)",
      "Bash(dotnet ef database drop --force*)",
      "Read(**/.env)",
      "Read(**/.env.*)",
      "Read(**/appsettings.Production.json)",
      "Read(**/secrets.json)"
    ]
  },
  "env": {
    "DOTNET_NOLOGO": "1",
    "DOTNET_CLI_TELEMETRY_OPTOUT": "1"
  }
}

Commit this file. The whole team shares the approved command set.

allow runs silently. deny blocks and cannot be overridden. deny always takes precedence. Anything not listed is asked. The $schema line enables autocomplete and validation in VS, VS Code, and Rider.

For the full command catalogue (publish, pack, sln management, NuGet hygiene, EF Core database commands, autoMode prose rules, personal versus team scopes), see the .NET configuration guide.

Recommended .NET project anchors

Three files outside Claude Code’s configuration improve output quality across the whole solution:

Directory.Build.props at the solution root:

<Project>
  <PropertyGroup>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
    <AnalysisLevel>latest-recommended</AnalysisLevel>
  </PropertyGroup>
</Project>

When TreatWarningsAsErrors is set, the PostToolUse hook’s dotnet build fails on any warning the agent introduces. The agent reads the failure and fixes it. Style drift gets caught at the file level, not at review time.

.editorconfig shared across the solution enforces consistent indentation, brace style, and using directive ordering. The agent reads .editorconfig and aligns its output. VS, VS Code, Rider, and dotnet format all respect the same file.

.claude/settings.json with the pre-approved commands above, plus hooks. For the hooks (auto-format and build on edit, session start summary, pre-compact snapshot), see the .NET configuration guide.

Using Claude Code alongside your IDE

Claude Code edits files on disk. It does not matter which editor you have open: all changes appear in your editor’s file watcher the moment they land.

Visual Studio

Open Claude Code in the integrated terminal (View > Terminal). Pin the terminal pane next to Solution Explorer. The agent’s file edits appear immediately in the editor. Git Changes shows everything the agent modified, ready for review before you commit.

After .csproj edits, Visual Studio may prompt to reload modified projects. Configure automatic reload at Tools > Options > Projects and Solutions > General > Automatically reload projects on changes outside VS. This removes the interruption during migrations that touch many project files.

The PostToolUse hook running dotnet format is compatible with Visual Studio’s Code Cleanup. Both respect .editorconfig. They do not fight: the agent formats on every file save, and Code Cleanup produces the same result.

VS Code

Install the Claude Code VS Code extension for an inline panel. Or run claude in the integrated terminal (`Ctrl+“).

Pair Claude Code with the C# Dev Kit extension. The Dev Kit’s test explorer and IntelliSense align with what the agent produces via dotnet test.

Add a .vscode/settings.json to the repository:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "ms-dotnettools.csdevkit",
  "dotnet.defaultSolution": "MyApp.sln",
  "omnisharp.enableEditorConfigSupport": true
}

This ensures the formatter settings in the repo match what the agent and dotnet format produce.

Rider

Open Claude Code in the JetBrains terminal tool window (Alt+F12). Rider also has a Claude Code plugin available in the JetBrains Marketplace.

Align ReSharper’s inspection settings with the analysers configured in Directory.Build.props. If the project enforces warnings-as-errors on specific Roslyn analysers, set ReSharper to the same severity. This prevents the agent and ReSharper disagreeing on what constitutes a problem.

What carries across all three IDEs

File watcher pickup of agent edits, Git diff review, .editorconfig enforcement, and the sensors in .claude/settings.json hooks. The agent edits files the same way regardless of which editor is open. It does not need IDE access.

A note on what we use at Talk Think Do

At Talk Think Do, Cursor is the primary IDE for all engineers, per the Q1 2026 AI Velocity Report. Claude Code runs alongside it for agent workflows and longer-running tasks. We share this as a data point, not a recommendation. Readers on Visual Studio or VS Code are not missing anything material: the configuration in this guide works identically across all three.

Practical workflows for .NET developers

Large-scale refactoring with worktrees

For a rename or restructure that touches dozens of files, use --worktree so the changes land on a separate branch:

claude --worktree rename-customer-to-client "Rename the Customer domain entity to Client across the entire solution. Update class names, variable names, file names, database mappings (keep the table name as Customers), API endpoints, and test classes. Follow AGENTS.md conventions."

The original working tree stays unchanged while the agent works on the branch. Review the diff when it reports back.

.NET Framework migration

See the .NET Framework to .NET 10 migration guide for the full workflow. The key sequence:

> Invoke /migrate-dotnet-project on src/OrderManagement.Domain/

The migrate-dotnet-project skill reads AGENTS.md, produces a plan, waits for confirmation, then migrates file by file with a build check after each file.

Test generation

Use a skill rather than a free-form prompt for consistent results:

> Invoke /write-xunit-tests on src/OrderManagement.Application/Handlers/CreateOrderHandler.cs

The skill follows the naming conventions in AGENTS.md and uses the project’s test libraries (xUnit, NSubstitute, FluentAssertions). See the .NET configuration guide for the skill definition.

Code review via a subagent

> Use the code-reviewer agent to review the changes in this PR branch

The code-reviewer subagent runs dotnet build and dotnet test before offering any opinion. It grounds its findings in sensor output rather than speculating. See the .NET configuration guide for the agent definition.

API client generation

> Read OrderController and generate a TypeScript client for our React front end.
> Use fetch with proper error handling. Generate TypeScript interfaces matching the C# DTOs.
> Follow the naming conventions in AGENTS.md.

Working with large .NET solutions

Use /compact regularly

Claude Code’s conversation context accumulates. For large solutions, the context fills. The /compact command compresses the conversation while keeping the most relevant information.

When to run /compact:

• After completing migration of each project in a multi-project solution
• After a long analysis session before starting modification work
• When responses seem to have lost earlier context

A PreCompact hook in .claude/settings.json can save a migration progress snapshot to .claude/migration-progress.log automatically. See the .NET configuration guide.

Scope your requests

Rather than “migrate the entire solution,” scope to one project at a time:

> Migrate src/OrderManagement.Domain/ to .NET 10.

Then, after review:

> The Domain project is migrated and green. Now migrate src/OrderManagement.Infrastructure/.

Use .gitignore patterns

Claude Code respects .gitignore. Ensure bin/, obj/, and node_modules/ are excluded so the agent does not read build output.

Cloud agents: Claude Code on the move

The terminal CLI is one surface. The same agent runs on the web at claude.ai/code, as a desktop app, and via mobile browser. The same account, the same MCP servers, and the same skills follow you.

Background agents

Start a long-running task as a background agent while you keep working:

claude --bg "Read src/OrderManagement.Infrastructure/ and produce a migration plan following AGENTS.md. Write the plan to .claude/migration-plan-infrastructure.md."

Claude Code notifies you when the agent finishes. Review the output in the terminal or from the web UI.

Parallel migrations

Each background agent gets its own git worktree:

claude --worktree migrate-domain "Migrate src/OrderManagement.Domain/ to .NET 10"
claude --worktree migrate-infrastructure "Migrate src/OrderManagement.Infrastructure/ to .NET 10"

Both agents run at the same time on separate branches. The original source tree stays buildable.

Exploring ideas on the go

Open claude.ai/code on your phone. Ask a question about your codebase. Review the response. Start a refactor proposal on the train and review the resulting plan at your desk.

Useful for “will this WCF service translate cleanly to gRPC?” questions that do not require the laptop open.

Honest limitations

Cloud agents need network access to your repository. Keep secrets out of the repo: the deny list in .claude/settings.json blocks reads of .env files and production appsettings.json. Long-running migrations should still be reviewed in chunks even when the agent runs unattended.

For Managed Agents environments (cloud containers with dotnet-sdk-10.0 pre-installed), see the .NET configuration guide.

What Claude Code does well (and what it does not)

Strong performance

• Namespace and using statement updates: near-perfect accuracy across large codebases
• API replacement (well-defined mappings): ConfigurationManager to IConfiguration, HttpWebRequest to HttpClient
• Project file conversion: SDK-style .csproj, PackageReference migration
• Boilerplate generation: Dockerfiles, GitHub Actions workflows, Bicep templates, DI registration
• Test framework migration: MSTest to xUnit, Moq to NSubstitute

Moderate performance (review carefully)

• EF6 to EF Core migration: gets the structure right but can miss lazy loading differences and complex inheritance mapping
• Dependency injection refactoring: handles standard registrations well but can misconfigure scoped/transient lifetimes
• LINQ query translation: most queries translate correctly; complex joins or group-by operations may behave differently

Weak performance (human-led)

• Architecture decisions: which services to extract, how to decompose a monolith
• Business logic validation: verifying migrated logic behaves identically to the original
• Security review: ensuring authentication and authorisation patterns are correctly migrated

Tooling that pairs with Claude Code on .NET projects

dotnet format: runs via the PostToolUse hook after every file edit. Keeps output consistent with .editorconfig without manual intervention.

ArchUnitNET: structural tests that fail if the agent violates your module boundaries. The agent cannot quietly leak a domain entity into an infrastructure concern. Pair with xUnit.

Stryker.NET: mutation testing that verifies the agent’s generated tests actually cover the code. Run after migration to confirm the test suite is still meaningful.

GitHub Advanced Security CodeQL: security scanning that runs in CI. The agent’s output is scanned the same way as human-written code.

For the deeper framing of computational sensors versus inferential checks, see Harness Engineering for Coding Agents.

In practice

Two representative examples from recent TTD engagements, anonymised.

A .NET team adopted Claude Code for backend development across three active projects. Initial output quality was inconsistent. After writing project-specific AGENTS.md files for each repository covering EF Core conventions, DI patterns, and test naming standards, output quality improved measurably. Review corrections dropped by approximately 40-50%. The AGENTS.md investment (roughly two hours per project) paid back within the first migration session.

A separate team used Claude Code for a 90k-line .NET Framework 4.8 Web API migration. The critical step was pre-approving the migration command set before starting: dotnet build, dotnet test, dotnet format, dotnet ef migrations, upgrade-assistant. Without that, the first day was dominated by permission prompts. With the approved command set in place, the agent could run a build check after every file without interruption. The HttpClient migration (full IHttpClientFactory pattern across 40 integration classes) was handled almost entirely by the agent following the migration rules in AGENTS.md.

In our Q1 2026 AI Velocity Report, 84% of production code is AI-authored, with Claude Code as the primary agent for backend .NET work. The CLAUDE.md and AGENTS.md configuration is the single most impactful adoption step across every project.

See the numbers

The Q1 2026 AI Velocity Report records 84% AI-authored code, 40-50% faster delivery, and six live MCP integrations. For the full stack, tools, and methodology behind those numbers, see the Q1 2026 AI Velocity Report.

Next steps

For the full configuration reference (complete command catalogue, advanced hooks, MCP servers, skills, subagents, cloud environments, and CI integration), see the Claude Code .NET configuration guide.

For migration-specific workflows, see the .NET Framework to .NET 10 migration guide.

For the broader context of AI-assisted .NET modernisation, see the .NET modernisation playbook.

For the harness engineering framing behind the configuration choices in this guide, see Harness Engineering for Coding Agents.

For our Claude Code development service, where we handle the migration while your team focuses on business delivery.