# Claude Code .NET: practical guide for C# and ASP.NET Core

URL: https://agentvera.dev/en/blog/claude-code-for-dotnet/ · Published: 2026-11-01

Learn how to use Claude Code on C# and ASP.NET Core projects, including CLAUDE.md setup, a safe working loop, test verification, and EF Core pitfalls.

**In short:**

- A repository-root CLAUDE.md with exact dotnet build, test, and format commands makes Claude Code far more reliable on .NET solutions.
- Use a small, test-verified loop and carefully review EF Core migrations, DI changes, and async edits.
- For parallel .NET work, isolate agents in git worktrees or use AgentVera with checkpoints, code review, and token budgets.

When you start Claude Code on a .NET codebase, run `claude` in the directory that contains the solution file or the main project, not in a subfolder such as `src/MyApp` unless that is the only scope you want. The agent reads the files you point it at, but it cannot reliably infer your build, test, and migration commands unless you document them. The fastest way to make it useful is a repository-root CLAUDE.md with exact dotnet CLI commands and .NET-specific rules. See [Claude Code](/en/agents/claude-code/) for the general workflow.

## Why Claude Code fits .NET work

Claude Code works well with .NET because a typical solution is made of plain-text files: .sln, .csproj, .cs, Program.cs, appsettings.json, and test files. The agent can parse the solution structure, identify target frameworks, read DI registrations, and run `dotnet build` or `dotnet test` to use the compiler and test runner as an automated review loop. It understands common ASP.NET Core patterns such as minimal APIs, controllers, middleware, and the options pattern, and it can follow existing EF Core mappings and query style. The main advantage over asking a chatbot outside your repo is that Claude Code executes in your terminal, so it sees the same compiler errors and test output you do and can act on them.

## Setting up a .NET project for Claude Code

Put a `CLAUDE.md` at the repository root. For a larger repository, add a second short file in the test folder if test conventions differ. The file should give the agent: build and test commands, format/lint commands, solution layout, target framework, and rules for areas where bad changes are expensive, especially EF Core migrations and DI lifetimes. Use exact project paths where possible because .NET solutions often contain multiple projects and the agent can otherwise pick the wrong one.

Example `CLAUDE.md` for a typical ASP.NET Core solution:

```markdown
# CLAUDE.md

## Solution layout
- Use `MyApp.sln` in the repo root.
- `src/MyApp.Api` is the Web API project.
- `src/MyApp.Core` contains domain models and interfaces.
- `src/MyApp.Infrastructure` contains EF Core DbContext and migrations.
- `tests/MyApp.Tests` contains xUnit tests.

## Commands
- Restore: `dotnet restore MyApp.sln`
- Build: `dotnet build MyApp.sln --no-restore`
- Test: `dotnet test tests/MyApp.Tests/MyApp.Tests.csproj --no-build`
- Format: `dotnet format MyApp.sln --no-restore`

## .NET rules
- Target .NET 8 and C# 12; enable nullable reference types.
- Follow the existing minimal API style in `Program.cs`.
- Register services in `Program.cs`, not in static classes.
- Do not create or remove EF Core migrations unless explicitly asked.
- When asked to add a migration, run `dotnet ef migrations add <Name>` from `src/MyApp.Infrastructure`.
- Do not run destructive commands such as `dotnet ef database drop` or `git push --force`.
- Prefer asynchronous methods with `Async` suffix in controllers and services.
- Keep tests as small focused facts; do not turn an integration test into a unit test.
```

This block uses exact dotnet CLI syntax and names the migration project, which prevents a very common .NET problem: the agent creates a migration in the wrong project or against the wrong DbContext. Keep the file short enough that Claude Code will actually follow it instead of skimming. You can also point it to a checklist such as [Claude Code best practices: a practical checklist](/en/blog/claude-code-best-practices/) for general prompt and review habits.

## Working loop for .NET changes

Use a tight loop: plan first, make one small change, run tests, review the diff. Do not let the agent refactor an entire solution and then run `dotnet test` once at the end; .NET compile errors cascade, and a single missing using or wrong namespace can hide the real failure. Start with a planning turn, ask for the exact files it will touch, and then say "go ahead" only after the plan looks correct. You can also use plan mode to keep changes exploratory until the approach is confirmed; see [Claude Code plan mode: plan first, then let it build](/en/blog/claude-code-plan-mode/).

Example prompts for typical .NET work:

- "Read the solution and list the projects, target frameworks, and the public API surface of the order service."
- "Add a GET /api/orders/{id} endpoint in MyApp.Api that returns OrderDto from OrderService. Follow the existing endpoint style exactly and register any new service in Program.cs."
- "Add an OrderService method to calculate order total, then write xUnit tests for discount, tax, and empty order."
- "Rewrite GetOpenOrders in OrderRepository to use AsNoTracking and project directly to OrderSummaryDto. Do not change the method signature."
- "Run dotnet test for MyApp.Tests, fix any failures you introduced, and keep the fix limited to the files you changed."

After each prompt, review `git diff` before moving on. The agent is most dangerous when it silently edits tests to make them pass, so watch for changed assertions in test files.

## Typical .NET tasks and pitfalls

The table below shows tasks where Claude Code is usually reliable and the areas to watch closely.

| Task | Good prompt | Watch closely |
|------|-------------|---------------|
| Add a minimal API endpoint | "Add POST /api/products using the existing ProductService and return 201 with a location header." | Route conflicts, model binding, JSON serializer options, and missing `[FromBody]` or `[FromRoute]`. |
| EF Core query optimization | "Change GetRecentOrders to use AsNoTracking and a projection to OrderListItemDto." | Client evaluation, multiple enumeration, `Include` usage, and changes to tracked vs untracked behavior. |
| xUnit or NUnit tests | "Create tests for PriceCalculator using NSubstitute for dependencies and cover the four discount cases from the issue." | Over-mocking, brittle tests, missing async `Task` returns, and asserting implementation details. |
| Refactor DI registration | "Extract IEmailSender and update registrations in Program.cs according to the existing pattern." | Service lifetime changes, constructor injection mismatches, and missing registrations after moving classes. |
| EF Core migration | "Add a migration for the new `Notes` column on `Customer` in the Infrastructure project." | Generated migration content, unintended schema changes, data loss, and multiple DbContexts. |

Common .NET-specific pitfalls to watch:

- The agent may propose a NuGet package version that conflicts with your target framework or existing transitive dependencies. Ask it to check `dotnet list package` and the csproj before adding packages.
- It may generate C# that builds only if nullable is disabled or if a newer language version is available. Your CLAUDE.md should fix that.
- It may create an EF Core migration in the wrong project or with an ambiguous `--project` and `--startup-project`. Always inspect migration files and the model snapshot.
- It may assume the test command is `dotnet test` at the solution level, but a multi-project solution may run unrelated tests or fail to build. Use exact test project paths.
- It may alter async code incorrectly, for example removing `ConfigureAwait(false)` in library code or changing a synchronous method to async without changing callers. Review those changes carefully.

## Testing and verification

Make verification part of every turn. After a change, have the agent run the exact `dotnet test` command from CLAUDE.md. If the test project has a build, ask it to run `dotnet build MyApp.sln --no-restore` first or use `--no-build` only when you know the build is current. For formatting, use `dotnet format MyApp.sln --no-restore` and, in CI, `dotnet format MyApp.sln --verify-no-changes`. Do not trust the agent’s summary alone; look at the actual test output and the diff.

For ASP.NET Core work, integration tests with `WebApplicationFactory` are especially valuable because they catch DI and middleware mistakes that unit tests miss. Ask the agent to add or update an integration test for new endpoints instead of only unit testing a service. When a test fails, ask for the failing line and the stack trace, not just a guessed fix. If the agent starts changing tests to match its implementation, stop and review the intended behavior.

A useful rule for .NET verification: after any change to a shared project such as `MyApp.Core` or `MyApp.Infrastructure`, run all test projects that reference it, not only the one you were editing. A signature change in `MyApp.Core` can break tests in `MyApp.Tests` and an integration test project at the same time.

## Running several agents on one .NET project

On a .NET solution with several independent branches of work, AgentVera can run multiple Claude Code agents in parallel, each in its own git worktree, so they do not overwrite each other’s files. After each agent turn, a second model reviews the code and links findings to file:line, which is useful for catching EF Core migration or DI lifetime mistakes. Checkpoints make it possible to undo an entire turn after a bad refactor, and token budgets stop a failing test-fix loop from consuming the whole account. For details on the parallel setup, see [How to run multiple Claude Code agents in parallel](/en/blog/run-multiple-claude-code-agents/).

## Wrap-up

Claude Code becomes a practical .NET tool when you make the project rules explicit, keep changes small, and verify with dotnet test after every step. The most important .NET-specific habit is to treat EF Core migrations and solution-level changes as high-risk edits that require manual review. Start with a solid CLAUDE.md, use a plan-first loop, and only parallelize agents when each one works in an isolated worktree or a tool like AgentVera. That gives you the speed of an agent without the usual .NET project breakage.

## Frequently asked questions

**Can Claude Code work with .NET solutions and projects?** Yes. Run claude in the repository or solution directory and add a .NET-specific CLAUDE.md so it knows the exact build and test commands. It can read .sln and .csproj files, run dotnet CLI commands, and edit C# code using compiler and test output as feedback.

**How do I set up CLAUDE.md for a .NET project?** Put a CLAUDE.md at the repo root with the solution layout, restore/build/test commands, target framework, and rules for EF Core migrations, DI registration, and async naming. Use exact project paths because multi-project solutions can otherwise confuse the agent.

**Can Claude Code handle Entity Framework Core migrations safely?** It can generate migrations when you give it a clear command and project name, but you should always inspect the generated migration file and model snapshot. The most common failure is creating a migration in the wrong project or unintentionally changing the schema.

**How can I run multiple Claude Code agents on one .NET repo without conflicts?** Use separate git worktrees per agent or a tool like AgentVera that runs agents in isolated worktrees. That prevents file overwrites, and checkpoints plus token budgets make parallel work safer to manage.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/