ai-agents csharp.instructions.md

C# and .NET Rules

These rules apply when you write or review C#. Baseline is C# 13 on .NET 9 (the target for new work). Where a newer feature helps, name the version so the reader can check their SDK. Defer to the repo's .editorconfig, Directory.Build.*, and any analyzer config over personal preference.

Language Level

• Prefer modern syntax that reduces noise: collection expressions ([1, 2, 3]), primary constructors, required members, target-typed new, pattern matching, and switch expressions. They state intent with less ceremony.
• Use record for immutable value-like data; record struct when the value is small and copied often. Use class when identity or mutability is the point.
• Make reference types non-nullable by default. Keep <Nullable>enable</Nullable> on and treat nullable warnings as errors. A ? is a contract, not decoration.
• Use file-scoped namespaces and global using for the handful of namespaces every file needs. Do not hide domain types behind global usings.

Allocation and Performance

• Operate on Span<T> / ReadOnlySpan<T> and Memory<T> for slicing without copying. Rent large transient buffers from ArrayPool<T>.Shared and return them in a finally.
• Avoid allocations on hot paths: no LINQ in tight loops, no params arrays per call, no closures captured in inner loops. Measure with BenchmarkDotNet before and after; do not optimize on a hunch.
• Prefer struct for small, short-lived values to keep them off the heap, but pass large structs by in to avoid defensive copies. A struct over ~16 bytes passed by value is usually a mistake.
• Use StringBuilder or string.Create for multi-step string building; interpolation is fine for one-shot formatting.

Async

• Every awaitable that crosses an I/O or process boundary takes a CancellationToken and honors it. A method that ignores its token is a bug.
• Return ValueTask only for hot paths that frequently complete synchronously; default to Task. Never await a ValueTask twice.
• In libraries, use ConfigureAwait(false) on every await. In app or test code with a synchronization context you control, you may omit it.
• Never block on async with .Result or .Wait(); that deadlocks under a synchronization context and wastes a thread otherwise. Make the caller async.