What goes in a CLAUDE.md for a C# / .NET project (with a copy-paste template)

Claude Code reads your CLAUDE.md before it touches a single file. For a .NET project, getting this file right is the single highest-leverage setup step you can take. A well-written CLAUDE.md is the difference between an agent that produces idiomatic C# on the first attempt and one that invents patterns you never asked for.

What is a CLAUDE.md and why does Claude Code read it automatically?

A CLAUDE.md is a Markdown file at your repo root (or in any subdirectory) that Claude Code loads into context at the start of every session - without being asked. It is the mechanism Claude Code provides for persistent, project-wide instructions.

Think of it as the onboarding document you would hand a new senior engineer: architecture overview, the commands they need to run, the conventions the team has agreed on, and a clear definition of what “done” means. An agent that has read this file does not need to guess your folder structure, does not run dotnet build with the wrong arguments, and does not leave the test suite red when it commits.

The Anthropic best-practices page for Claude Code is explicit: include things Claude cannot infer from reading the code. Anything Claude would figure out on its own is noise that dilutes the signal - and a bloated CLAUDE.md causes Claude to start ignoring the rules buried at the bottom.

You can place CLAUDE.md files in several locations:

• Repo root - loaded every session, shared via git.
• Subdirectory (e.g. src/Api/CLAUDE.md) - loaded on demand when Claude works in that folder. Good for project-specific rules in a monorepo.
• Home folder (~/.claude/CLAUDE.md) - your personal overrides, not committed to git.

Start with /init inside Claude Code. It inspects your codebase and generates a starter file. Then refine it.

What should a .NET CLAUDE.md include - and what should NOT be there?

What belongs in CLAUDE.md

Architecture overview. Two or three sentences describing the solution shape: how many projects, which ones are the entry points, which layer owns what. An agent that knows Api/ is thin endpoints delegating to Application/ will not add business logic to the controller.

The command set. Every command the agent is allowed to run, spelled out exactly:

dotnet build src/MySolution.sln
dotnet test src/MySolution.sln --no-build
dotnet format src/MySolution.sln
dotnet ef migrations add <Name> --project src/Infrastructure --startup-project src/Api

Pre-approving these in .claude/settings.json means the agent does not pause to ask permission. List them in CLAUDE.md so the agent knows which commands are sanctioned.

Architectural decisions that are not obvious from code. Why you chose in-memory storage over a database in the starter. Why you use records for all commands and queries. Why endpoints are thin and slice-specific. These are the decisions an agent would otherwise make differently on instinct.

Definition of done. An explicit checklist: build passes, tests are green, dotnet format shows no diff. This is what the agent checks before it stops.

Non-obvious gotchas. Environment variables the project requires, a local secret that must be set, a quirk in the test setup.

What does NOT belong in CLAUDE.md

Code style. Indentation, brace style, using-directive order, and naming conventions belong in .editorconfig, enforced by dotnet format. Put them there - not in CLAUDE.md - and the toolchain enforces them mechanically. Claude does not need to re-read a rule the formatter already enforces.

Standard .NET conventions. Claude already knows that async methods return Task, that IDisposable should be wrapped in using, and that ArgumentNullException.ThrowIfNull is the modern null check. Writing these out is noise.

File-by-file descriptions of the codebase. The agent reads files directly. A prose description of every class is both stale on day two and a waste of context tokens.

Information that changes frequently. If a section of CLAUDE.md needs updating every sprint, it belongs in a comment in the code or in a README section, not in the agent instructions.

How long should a CLAUDE.md be?

Aim for 50-100 lines in the root file. Anthropic’s best-practices documentation says to keep it short and human-readable. The ceiling before signal starts getting lost in noise is around 200 lines for a single file. Path-scoped files (subdirectory CLAUDE.md files) can go up to 200 lines because they are only loaded when relevant.

For each line, apply the test: would removing this cause Claude to make a mistake? If not, cut it.

The four sections that survive this test on almost every .NET project:

1. Tech overview - runtime, framework, key packages, solution shape.
2. Architecture reasoning - the decisions that are not obvious from the code.
3. Command set - the exact commands the agent may run.
4. Definition of done - the checklist the agent verifies before stopping.

A sample CLAUDE.md for a .NET 10 minimal API

The following template is adapted from the conventions and definition-of-done used in the free starter repo at github.com/Khavel/dotnet-claude-starter. Clone the repo to see it in context.

# CLAUDE.md - MyProject

## Tech overview
- .NET 10 minimal API, C# 13, nullable reference types enabled
- Packages: MediatR (CQRS), FluentValidation, Serilog
- In-memory data store in this starter; production kit adds EF Core + PostgreSQL
- Solution: src/Api (entry point), src/Application, src/Domain, tests/Api.Tests

## Architecture
- Vertical slice: each feature lives in one folder under src/Api/Features/<Feature>/
- Endpoints are thin: validate, dispatch a MediatR command/query, return the result
- All commands and queries are C# records; handlers live in the same feature folder
- No cross-feature dependencies; shared code goes to src/Application/Common/

## Commands (pre-approved in .claude/settings.json)
- Build: dotnet build src/MySolution.sln
- Test: dotnet test src/MySolution.sln --no-build --logger "console;verbosity=minimal"
- Format check: dotnet format src/MySolution.sln --verify-no-changes
- Format apply: dotnet format src/MySolution.sln

## Definition of done
A change is complete when ALL of the following hold:
1. dotnet build exits 0
2. dotnet test exits 0 (no skipped tests without a comment)
3. dotnet format --verify-no-changes exits 0
4. The new or changed feature has at least one contract test

## Non-obvious gotchas
- Tests use WebApplicationFactory<Program>; Program.cs must be partial
- Set ASPNETCORE_ENVIRONMENT=Development for local runs (see .env.example)

This template is intentionally lean. The agent reads the actual source files for everything else. The CLAUDE.md provides only what the agent cannot safely infer on its own.

FAQ

What is a CLAUDE.md file? CLAUDE.md is a Markdown file that Claude Code reads automatically at the start of every session. It gives the agent persistent context it cannot infer from code alone: your architecture decisions, command set, conventions, and definition of done.

Where should I place CLAUDE.md in a .NET solution? Put one root-level CLAUDE.md in the repo root for project-wide rules. You can add additional CLAUDE.md files in subdirectories (e.g. src/Api/) that Claude loads on demand when it works in those folders. Keep the root file under 100 lines.

Should code style rules go in CLAUDE.md? No. Code style belongs in .editorconfig and is enforced by dotnet format. Put only things in CLAUDE.md that dotnet format cannot enforce: architectural decisions, workflow commands, and the definition of done.

How long should a CLAUDE.md be? Aim for 50-100 lines in the root file. Each line should pass the test: would removing this cause Claude to make a mistake? If not, cut it.

Does the dotnet-claude-starter repo include a CLAUDE.md? Yes. github.com/Khavel/dotnet-claude-starter ships a fully annotated CLAUDE.md for a .NET 10 minimal API. Clone it to see the conventions and definition-of-done in context, then adapt it to your solution.

---

Building a production .NET SaaS, agent-first?

The dotnet-claude-starter repo gives you the shape. Sharpyard is the production kit: a .NET 10 and Angular SaaS starter with auth, multi-tenancy, billing, and the full agent operating layer (CLAUDE.md, MCP config, contract tests, pre-approved command set) wired throughout. Join the founding waitlist for early access and the founding price.