CLAUDE.md for .NET: A Project Instructions Template

A CLAUDE.md file in your .NET project tells Claude Code how your solution is structured, which commands to use for building and testing, what the rules are around data changes, and which boundaries it must not cross without asking. Without it, Claude Code may suggest commands that only work for a different project type, or miss the fact that your project uses a specific code generation step before building.

Tools like fenbs are a useful place for the decisions that underlie the project structure: which architectural pattern was chosen, why a particular NuGet package was selected, which refactoring decisions have been recorded. Your CLAUDE.md carries the commands and constraints; fenbs carries the reasoning and the current tasks. This page gives you a template to copy and adapt.

What belongs in a CLAUDE.md for .NET

.NET projects vary significantly: a small console app, a multi-project ASP.NET Core API, a library targeting multiple frameworks, a microservice with a specific CI pipeline. The more projects in your solution, the more helpful it is to describe the layout and the purpose of each one. Claude Code cannot tell from a file listing alone which project is the entry point and which is a shared library.

• The solution file location and a short description of each project in it.
• Commands to build, run, and test — including any required pre-build steps.
• The test framework in use (xUnit, NUnit, MSTest) and any special setup needed to run tests.
• Rules for database changes: migration approach, who approves schema changes, which commands are safe to run locally.
• Environment configuration: which settings come from environment variables, which secrets store is used, and what must not be hardcoded.

The template

Copy this into a CLAUDE.md at your solution root. Remove or adjust sections that do not apply, and add project-specific rules at the end. The .NET documentation↗ (opens in a new tab) is the right reference for command details.

# [Solution name] — .NET project

## Solution structure
```
[SolutionName].sln
  src/
    [ProjectName].Api/         — ASP.NET Core web API, entry point
    [ProjectName].Core/        — Business logic, domain types, interfaces
    [ProjectName].Data/        — EF Core DbContext, repositories, migrations
    [ProjectName].Tests/       — xUnit test project
```

## Commands
```
# Build the solution
dotnet build

# Run the API (development)
dotnet run --project src/[ProjectName].Api

# Run all tests
dotnet test

# Run a specific test project
dotnet test src/[ProjectName].Tests

# Watch for changes (development)
dotnet watch --project src/[ProjectName].Api
```

## Target framework
This solution targets [net8.0 / net9.0 / other]. Do not change TargetFramework
in any .csproj file without an approved decision.

## Database and migrations
Database: [SQL Server / PostgreSQL / SQLite]. Migrations use [EF Core / Flyway / manual SQL].

EF Core migration rules:
- Generate a new migration with: `dotnet ef migrations add [MigrationName] --project src/[ProjectName].Data`
- Never modify an existing migration file. Add a new migration instead.
- Apply to a local dev database with: `dotnet ef database update --project src/[ProjectName].Data`
- Production migrations require review from [name] before applying.

## Environment and secrets
- Connection strings and API keys are in environment variables or .NET User Secrets.
  They are NOT in appsettings.json or appsettings.Development.json.
- Local dev secrets: `dotnet user-secrets set "[Key]" "[Value]" --project src/[ProjectName].Api`
- Production secrets: [describe your secrets store, e.g., Azure Key Vault]

## Testing
- Test framework: xUnit.
- Tests are in `src/[ProjectName].Tests/`. Unit tests mock dependencies; integration tests
  use WebApplicationFactory<Program> or a test database.
- Run all tests before committing. All tests must pass.
- Do not delete or skip existing tests without an approved reason.

## NuGet packages
Check with [name or team] before adding a new NuGet package.
Current approved package sources: nuget.org only (no private feeds).

## What Claude Code must not do without asking
- Modify an existing EF Core migration file.
- Change TargetFramework or LangVersion in a .csproj.
- Add a NuGet package that has not been approved.
- Apply database migrations to staging or production.

Migration rules are the most important constraint

For .NET projects that use Entity Framework Core or another migration tool, the rules around schema changes are critical. An assistant that edits an existing migration file instead of creating a new one can introduce hard-to-diagnose inconsistencies between environments that have already applied the original migration.

Be explicit: "Never modify an existing migration file. Create a new migration instead." Add the correct command for generating a migration so Claude Code uses the right project flag and project path rather than guessing. For projects with a database-first approach, state that clearly and tell Claude Code the correct process for schema changes in your setup.

Multi-project solutions need layout documentation

In a multi-project .NET solution, the folder layout tells Claude Code which project does what. A brief description of each project — "domain types and interfaces, no external dependencies," "EF Core DbContext and repositories," "xUnit tests with integration test setup" — saves it from reading every .csproj file to understand the dependency direction.

Include the dependency rules if they matter: "Core has no dependency on Data or API. API depends on Core and Data." These rules are architectural decisions that are easy to violate accidentally when adding a new feature. A clear statement in CLAUDE.md makes the constraint visible before Claude Code starts adding a new file.

Environment configuration also benefits from an explicit rule. .NET projects often have an appsettings.json for application settings, a appsettings.Development.json for local overrides, and environment variables or a secrets store for production. A common mistake is adding a connection string to a settings file that should not be committed. Add a rule: "Connection strings and API keys are in environment variables or User Secrets, not in any settings file." The dotnet user-secrets command stores development secrets outside the project folder so they are never committed.

Project decisions alongside the code

Every .NET project accumulates decisions: why the team chose xUnit over MSTest, which serializer was selected and why, which authentication approach was approved, whether CQRS was adopted for a part of the codebase. Those decisions belong somewhere durable alongside the tasks that implement them.

How to do this with fenbs

1. Create a free account. Start a project for your solution and add the current development tasks.
2. Record architectural decisions — library selections, migration strategy, layer dependency rules — as Decisions and rules in fenbs.
3. Connect Claude Code to fenbs from Integrations. Ask it to read the project context at the start of each session to get the current rules and open tasks.
4. Copy the CLAUDE.md template above into your solution root and fill in the project names, framework version, commands, and migration rules.
5. When a decision changes — a new package approved, a migration approach updated, a target framework bumped — record the change in fenbs and update CLAUDE.md so both reflect the current state of the project.

For a broader look at CLAUDE.md structure across project types, see CLAUDE.md examples. For instructions spanning multiple services in one workspace, see Claude Code with multiple projects and CLAUDE.md. If CLAUDE.md instructions are not being followed, CLAUDE.md not working covers the most common causes.