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

What Claude Code is (and is not)

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

What it is:

• A terminal tool that runs alongside your IDE (Visual Studio, Rider, VS Code)
• Capable of reading entire directory structures and understanding project context
• Able to execute shell commands (dotnet build, dotnet test, git diff)
• Effective at repetitive, well-defined code changes at scale

What it is not:

• An IDE plugin or extension (it runs in the terminal)
• A replacement for code review (everything it produces needs human review)
• Infallible (it can and does make mistakes, particularly with complex business logic)
• A deployment tool (it does not deploy, provision infrastructure, or manage environments)

For .NET developers accustomed to GitHub Copilot or JetBrains AI, the mental model is different. Copilot suggests completions as you type. Claude Code takes instructions and executes multi-step changes across your project. The two tools complement each other: Copilot for in-flow code completion, Claude Code for larger structural tasks.

Installation and setup

Claude Code requires Node.js 18+ and an Anthropic API key.

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

Navigate to your .NET solution directory and start Claude Code:

cd /path/to/MySolution
claude

Claude Code reads your project structure on startup. For a .NET solution, it recognises .sln files, .csproj files, and the standard project layout.

Configuring CLAUDE.md for .NET projects

The CLAUDE.md file is the most important configuration step. It lives in the root of your repository and gives Claude Code project-specific context that dramatically improves output quality.

Structure of a good CLAUDE.md

A CLAUDE.md for a .NET project should cover five areas:

1. Project overview and target:

# Project: OrderManagement

## Overview
E-commerce order management system. ASP.NET Core Web API (.NET 10) with
EF Core, 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

2. Coding conventions:

## Conventions
- File-scoped namespaces
- Primary constructors for classes with injected dependencies
- ILogger<T> for all logging
- Nullable reference types enabled project-wide
- Implicit usings enabled
- XML documentation on all public APIs
- No regions (#region)

3. Framework and library preferences:

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

4. Project-specific rules:

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

5. Migration-specific rules (if applicable):

## Migration rules (temporary, remove after migration)
- Source: .NET Framework 4.8 with EF6
- Target: .NET 10 with EF Core 10
- ConfigurationManager -> IConfiguration
- HttpWebRequest -> HttpClient via IHttpClientFactory
- Keep all database table and column names unchanged
- Do not change any business logic during migration

Why CLAUDE.md matters

Without CLAUDE.md, Claude Code generates correct but generic .NET 10 code. With CLAUDE.md, it generates code that follows your project’s specific conventions. The difference is measurable: in our experience, code generated with a well-configured CLAUDE.md requires 40-60% fewer review corrections than code generated without one.

Practical workflows for .NET developers

Workflow 1: Large-scale refactoring

Renaming a domain concept, changing an interface, or restructuring a namespace affects dozens of files. Claude Code handles these cross-cutting changes efficiently.

> Rename the "Customer" domain entity to "Client" across the entire solution.
> Update all references: class names, variable names, file names, database
> mappings (but keep the database table name as "Customers"), API endpoints,
> and test classes.

Claude Code reads the affected files, identifies all references, and makes the changes consistently. For a rename that touches 40 files, this takes minutes rather than the hour it would take manually (even with IDE refactoring tools, which often miss string references, configuration files, and test data).

Workflow 2: .NET Framework migration

This is where Claude Code delivers the most value for .NET teams. See our .NET Framework to .NET 10 migration guide for the full workflow. The key commands:

> Analyse src/OrderManagement.Domain/ and list all .NET Framework APIs
> that need migration to .NET 10. Include the file, line, current API,
> and recommended replacement.

> Migrate src/OrderManagement.Infrastructure/ to .NET 10 following the
> rules in CLAUDE.md. Migrate one file at a time.

> Run dotnet test for the OrderManagement.Tests project and fix any
> failures caused by the migration.

Workflow 3: Test generation

Claude Code generates meaningful test cases, not just boilerplate.

> Write xUnit tests for src/OrderManagement.Application/Handlers/
> CreateOrderHandler.cs. Cover the happy path, validation failures,
> and the case where the customer does not exist. Use NSubstitute for
> mocking and FluentAssertions for assertions. Follow the naming
> convention in CLAUDE.md.

The output follows your testing conventions from CLAUDE.md and generates realistic test scenarios based on the actual code, not generic templates.

Workflow 4: API client generation

When your .NET API serves a React Native or Blazor frontend, Claude Code can generate typed API clients:

> Read the OrderController and generate a TypeScript API client for
> React Native. Use fetch with proper error handling. Generate
> TypeScript interfaces matching the C# DTOs.

Working with large .NET solutions

Enterprise .NET solutions often contain 15-50 projects and hundreds of thousands of lines. Claude Code handles large codebases, but you need to manage the conversation context.

Use /compact regularly

Claude Code maintains a conversation context that accumulates as you work. For large solutions, this context fills up. The /compact command compresses the conversation, 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 Claude Code starts giving responses that seem to have lost earlier context

Scope your requests

Rather than asking Claude Code to “migrate the entire solution,” scope requests to individual projects or components:

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

Then, after review:

> Now migrate src/OrderManagement.Infrastructure/ to .NET 10.
> The Domain project has already been migrated.

This produces better results because Claude Code can focus its attention on one component at a time.

Use .gitignore patterns

Claude Code respects .gitignore. Ensure your .gitignore excludes bin/, obj/, node_modules/, and other generated directories so Claude Code does not waste context reading build output.

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, MSTest to xUnit
• 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, assertion library changes

Moderate performance (review carefully)

• EF6 to EF Core migration: Gets the structure right but can miss lazy loading behavioural differences and complex inheritance mapping
• Dependency injection refactoring: Handles standard registrations well but can misconfigure scoped/transient lifetimes for complex service graphs
• LINQ query translation: Most queries translate correctly, but complex queries with multiple joins or group-by operations may behave differently on EF Core

Weak performance (human-led)

• Architecture decisions: Which services to extract, how to decompose a monolith, where to draw service boundaries
• Business logic validation: Verifying that migrated business logic behaves identically to the original
• Performance optimisation: Identifying and resolving performance regressions caused by migration
• Security review: Ensuring authentication, authorisation, and data protection patterns are correctly migrated

Tips from production use

These are patterns we have developed from using Claude Code across dozens of .NET projects:

Start every session by asking Claude Code to read your CLAUDE.md. Even though it is in the repository root, explicitly asking Claude Code to read it ensures the conventions are front-of-mind for the session.

Ask for a plan before execution. Before any large change, ask Claude Code to produce a migration plan or change list. Review the plan. Then ask it to execute. This catches misunderstandings before they become multi-file changes to undo.

Commit frequently. After each successful component migration, commit. If Claude Code makes a mistake in the next component, you can revert without losing prior work.

Review diffs, not files. After Claude Code makes changes, review the git diff rather than reading entire files. The diff shows exactly what changed, making review faster and more focused.

Do not let Claude Code make architectural decisions. Use it as a tool to implement decisions you have already made. “Migrate this WCF service to gRPC using the contract we discussed” is a better prompt than “figure out the best replacement for this WCF service.”

Cost considerations

Claude Code uses Anthropic’s API, billed by token usage (input and output). For .NET work:

• Analysis sessions (reading and reporting on code) are input-heavy and relatively affordable
• Migration sessions (reading and rewriting code) use both input and output tokens
• Large codebases consume more input tokens because Claude Code reads more context

We manage costs by scoping sessions to individual projects rather than entire solutions, using /compact to avoid re-reading already-processed code, and batching similar changes (migrate all services in one session rather than one at a time).

For enterprise teams considering Claude Code at scale, Anthropic offers volume pricing. Contact Anthropic directly for enterprise pricing.

What we have seen in practice

[CLIENT EXAMPLE: Our internal team adopted Claude Code for all .NET development in Q3 2025. Our AI Velocity Report tracks the metrics: 84% AI-authored code in production deliveries, with Claude Code as the primary AI tool for backend .NET work. The CLAUDE.md configuration was the single most impactful adoption step. Teams that invested an hour in writing a thorough CLAUDE.md saw measurably better output quality than teams that used generic prompts.]

[CLIENT EXAMPLE: A client’s in-house .NET team adopted Claude Code after we used it for their migration project. Their initial experience was mixed: output quality was inconsistent. After we helped them write project-specific CLAUDE.md files for their three main repositories, output quality improved significantly. The key was specifying their EF Core conventions, their DI patterns, and their test naming standards.]

Next steps

If you are evaluating Claude Code for your .NET team, start with a small, well-scoped project: a utility library migration, a test generation exercise, or a single-component refactoring. Build your CLAUDE.md based on what you learn. Then scale to larger tasks.

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

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

For IP and licensing considerations around AI-generated code, see Who Owns AI-Written Code?.

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