CLAUDE.md for C# and .NET: 13 Rules That Make AI Write Modern, Idiomatic Production Code

Ask Claude Code to "add an endpoint that returns paged orders for a customer" and the output compiles. It also ignores nullable warnings, hides an async void, blocks the thread pool with .Result, wraps everything in try/catch (Exception), reaches for a static DbContext, and sprinkles IConfiguration["..."] strings like glitter. It runs fine on your laptop. It deadlocks in staging.

C# in 2026 is not the C# the model was trained on. NRTs, records, pattern matching, minimal APIs, file-scoped namespaces, and IAsyncEnumerable are table stakes. Half the model's training is .NET Framework era; half the rest is "Hello World" tutorials. A CLAUDE.md next to your .csproj is the cheapest way to drag it forward.

Get the full CLAUDE.md Rules Pack — oliviacraftlat.gumroad.com/l/skdgt. The 13 rules below are a free preview.

1. Nullable reference types on, warnings as errors

<Nullable>enable</Nullable> and <TreatWarningsAsErrors>true</TreatWarningsAsErrors> go in every .csproj for new code. Without NRTs, the model emits string parameters that secretly mean "string or null", forces you to add ?. everywhere downstream, and quietly swallows NullReferenceException at runtime.

<PropertyGroup>
  <Nullable>enable</Nullable>
  <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  <LangVersion>latest</LangVersion>
</PropertyGroup>

Annotate intent: Customer? means may be null; Customer means it never is. Don't chase warnings with ! — the null-forgiving operator is a paper-over.

2. Records for DTOs, events, and value-equal types

When the type is "data, plus equality, plus immutability", reach for record (or record struct). AI defaults to mutable classes with hand-rolled Equals/GetHashCode that drift the moment a property is added.

public sealed record OrderDto(
    Guid Id,
    Guid CustomerId,
    decimal Total,
    IReadOnlyList<OrderLine> Lines);

with-expressions handle the "modify one field" case without mutation. Use class for entities with identity and behavior (EF Core aggregates); use record for transport, requests, responses, and domain events.

3. Switch expressions over if/else chains

Pattern matching is the C# 8+ killer feature, and the model still writes if (x is Foo f && f.Bar > 0) ladders. Switch expressions are exhaustive (the analyzer flags missing cases), shorter, and read top-to-bottom.

public decimal CalculateFee(Payment p) => p switch
{
    { Method: PaymentMethod.Card, Amount: > 1000m } => p.Amount * 0.015m,
    { Method: PaymentMethod.Card }                  => p.Amount * 0.025m,
    { Method: PaymentMethod.BankTransfer }          => 0m,
    _ => throw new ArgumentOutOfRangeException(nameof(p))
};

Property patterns, list patterns, and is not null over != null — they read as English and the analyzer reasons about them.

4. async/await only — no .Result, no .Wait(), no async void

Task.Result and Task.Wait() deadlock under any sync context (ASP.NET legacy, WPF, WinForms) and starve the thread pool elsewhere. async void swallows exceptions and crashes the process. AI reaches for them whenever a sync interface needs to call async code; the fix is to make the interface async, not to block.

public async Task<Order> GetOrderAsync(Guid id, CancellationToken ct)
{
    var order = await _db.Orders
        .Include(o => o.Lines)
        .FirstOrDefaultAsync(o => o.Id == id, ct);

    return order ?? throw new OrderNotFoundException(id);
}

async void is reserved for event handlers. ConfigureAwait(false) in shared libraries; skip it in ASP.NET Core (no sync context to capture).

5. CancellationToken everywhere — propagate, don't drop

Every async method that does I/O takes a CancellationToken and passes it down. Minimal API handlers and controllers get one for free. AI omits the token and turns client disconnects into 30-second hangs.

app.MapGet("/orders/{id:guid}", async (
    Guid id,
    IOrderService svc,
    CancellationToken ct) =>
{
    var order = await svc.GetOrderAsync(id, ct);
    return Results.Ok(order);
});

Name it ct or cancellationToken, never with a default that callers ignore. EF Core, HttpClient, Stream all accept tokens — use them.

6. LINQ for transformation — but no double enumeration

LINQ is idiomatic, but IEnumerable<T> from LINQ is deferred: enumerating twice runs the source twice. Materialize with .ToList() / .ToArray() once when crossing a layer boundary. AI defaults to repeated .Count() and .Any() against the same query — on EF Core that's N extra round-trips.

var unpaid = await db.Orders
    .AsNoTracking()
    .Where(o => o.Status == OrderStatus.Pending)
    .OrderBy(o => o.CreatedAt)
    .Select(o => new OrderDto(o.Id, o.CustomerId, o.Total, o.Lines))
    .ToListAsync(ct);

if (unpaid.Count == 0) return Results.NoContent();
return Results.Ok(unpaid);

EF Core: AsNoTracking() for reads, Include deliberately, project to DTOs with Select instead of fetching whole entities. Never call .ToList() mid-query and then keep filtering — that materialises the world.

7. Dependency injection via constructor — no Service.Instance, no static state

Every collaborator is injected through the constructor. No HttpClient.SharedInstance, no static readonly DbContext, no ServiceLocator.Get<T>(). AI loves singletons because tests are out of scope; you live with them when those services need to be replaced for tests, integration runs, or per-tenant overrides.

public sealed class OrderService(
    AppDbContext db,
    IClock clock,
    ILogger<OrderService> logger) : IOrderService
{
    public async Task<Order> CreateAsync(CreateOrderCommand cmd, CancellationToken ct)
    {
        logger.LogInformation("Creating order for {CustomerId}", cmd.CustomerId);
        // ...
    }
}

Primary constructors keep wiring tight. Lifetimes: Scoped for request-bound work, Singleton for stateless utilities, Transient only when justified.

8. Minimal APIs with typed results — not anonymous-object soup

Minimal APIs (or controllers — pick one per project, don't mix) own routing, model binding, and validation. AI sprinkles Results.Ok(new { ... }) and anonymous types; lock it down with Results<Ok<T>, NotFound> so OpenAPI generation and client codegen actually match what you return.

app.MapGet("/orders/{id:guid}",
    async Task<Results<Ok<OrderDto>, NotFound>> (
        Guid id, IOrderService svc, CancellationToken ct) =>
    {
        var order = await svc.FindAsync(id, ct);
        return order is null
            ? TypedResults.NotFound()
            : TypedResults.Ok(OrderDto.From(order));
    })
.WithName("GetOrder")
.WithOpenApi();

Group endpoints with MapGroup, share auth and validation with IEndpointFilter, and return ValidationProblem for 400s — not by sprinkling ifs inside the handler.

9. Exceptions are specific — no catch (Exception) Pokémon catches

Catch the exception you can handle: DbUpdateConcurrencyException, HttpRequestException, OperationCanceledException. Anything else bubbles to the global handler. AI wraps every block in try/catch (Exception ex) { _logger.LogError(ex, ...); return null; } and you spend Friday debugging silent failures.

try
{
    await db.SaveChangesAsync(ct);
}
catch (DbUpdateConcurrencyException ex)
{
    logger.LogWarning(ex, "Concurrency conflict on {Id}", id);
    return TypedResults.Conflict();
}

Re-throw with throw; — never throw ex;, which resets the stack trace. OperationCanceledException propagates; don't swallow it, or you'll mask client cancellations as success.

10. Configuration via IOptions<T> — no IConfiguration["Key"] strings

String-keyed configuration scattered across services is untyped, untestable, and validated nowhere. Bind to a typed options class once, register with AddOptions<T>().BindConfiguration(...).ValidateDataAnnotations().ValidateOnStart(), and inject IOptions<T> (or IOptionsSnapshot<T> for reload).

public sealed class StripeOptions
{
    [Required] public string ApiKey { get; init; } = "";
    [Range(1, 60)] public int TimeoutSeconds { get; init; } = 10;
}

builder.Services
    .AddOptions<StripeOptions>()
    .BindConfiguration("Stripe")
    .ValidateDataAnnotations()
    .ValidateOnStart();

Bad config crashes startup, not the first paid request at 2 a.m.

11. Structured logging via ILogger<T> — message templates, not interpolation

logger.LogInformation($"User {userId} did {action}") boxes the values into a single string and destroys structured search. Use the message template form: positional placeholders, named parameters preserved as fields in JSON logs.

logger.LogInformation(
    "Order {OrderId} settled in {ElapsedMs} ms for {CustomerId}",
    order.Id, elapsed.TotalMilliseconds, order.CustomerId);

Levels: Information for business events, Warning for handled anomalies, Error for unhandled failures, Debug for noisy local-only output. No Console.WriteLine in production paths. Use LoggerMessage source generators on hot loops.

12. Tests use xUnit + FluentAssertions — and exercise the public surface

xUnit ([Fact], [Theory]), FluentAssertions for readable failures, and WebApplicationFactory<TProgram> for HTTP-level integration tests. AI writes 200 unit tests against private helpers and zero tests that boot the actual app; flip the ratio.

public class GetOrderTests(OrdersWebAppFactory factory)
    : IClassFixture<OrdersWebAppFactory>
{
    [Fact]
    public async Task Returns_404_when_order_missing()
    {
        var client = factory.CreateClient();
        var resp = await client.GetAsync($"/orders/{Guid.NewGuid()}");
        resp.StatusCode.Should().Be(HttpStatusCode.NotFound);
    }
}

Mock at the seam (IOrderService, IClock), not at DbContext. Use Testcontainers for real Postgres in CI when the schema matters. Snapshot tests for response shapes are fine.

13. Build hygiene: analyzers on, warnings on, formatting enforced

Add Microsoft.CodeAnalysis.NetAnalyzers, enable EnforceCodeStyleInBuild, drop an .editorconfig with the team's rules, and run dotnet format --verify-no-changes in CI. AI will silence analyzers with #pragma warning disable to "ship" — don't let it.

<PropertyGroup>
  <AnalysisMode>AllEnabledByDefault</AnalysisMode>
  <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
  <ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>

# .editorconfig
[*.cs]
csharp_style_namespace_declarations = file_scoped:error
dotnet_style_qualification_for_field = false:warning
dotnet_diagnostic.CA1062.severity = error  # validate args in public APIs

File-scoped namespaces, ImplicitUsings, and Nullable enabled in every new project template. Suppressing analyzer rules requires a justification comment, reviewed in PR.

A starter CLAUDE.md snippet

# CLAUDE.md — .NET service

## Stack
- C# 13 / .NET 9, NRTs on, warnings as errors, file-scoped namespaces
- ASP.NET Core minimal APIs, EF Core, xUnit + FluentAssertions

## Hard rules
- NRTs enabled; no `!` to silence warnings; warnings = errors.
- Records for DTOs/events/value types; classes for entities and behavior.
- Switch expressions and pattern matching over `if`/`else` chains.
- async/await only. No `.Result`, no `.Wait()`, no `async void` outside event handlers.
- Every async I/O method takes and propagates `CancellationToken`.
- LINQ materialised once at layer boundaries; EF reads use `AsNoTracking`.
- Constructor DI only. No `static` state, no service locator.
- Minimal APIs return `TypedResults`; `MapGroup` + `IEndpointFilter` for shared concerns.
- Catch specific exceptions; rethrow with `throw;`; let `OperationCanceledException` bubble.
- `IOptions<T>` for config with `ValidateDataAnnotations().ValidateOnStart()`.
- Structured logging via `ILogger<T>`; message templates, not interpolation.
- Tests: xUnit, FluentAssertions, `WebApplicationFactory<T>` for HTTP tests.
- Analyzers + `dotnet format --verify-no-changes` in CI.

What Claude gets wrong without these rules

• Ignores nullability, sprinkles !, ships an NRE on the first edge case.
• Returns mutable classes with hand-rolled equality that breaks on the next field.
• Calls .Result inside a sync wrapper and deadlocks the request pipeline.
• Catches Exception, logs, returns null — silent failure, no signal.
• Reads config via IConfiguration["Stripe:ApiKey"] in three different services.
• Writes 200 tests for private helpers and zero tests against the real app.

Drop these 13 rules into CLAUDE.md and the next AI PR looks like a 2026 .NET service, not a 2017 ASP.NET MVC tutorial. Your CI stops failing on warnings and your staging stops deadlocking.

Want this for 20+ stacks with 200+ rules ready to paste? Grab the CLAUDE.md Rules Pack at oliviacraftlat.gumroad.com/l/skdgt.

— Olivia (@OliviaCraftLat)