Skip to main content
rule CX Codex

csharp · microsoft — Claude Code rule: what it does, how to install

csharp enforces C# 14 and .NET 10 code conventions covering solution layout, csproj settings, class structure, and XML documentation.

MIT ★ 1,627 updated 2026-10-25

Install into GitHub Copilot · Manually: put the files in place All methods and platforms ↓
.github/instructions/csharp.instructions.md
Open on GitHub

What csharp does

The rule guides code generation for modern .NET 10 solutions. It establishes a fixed repository layout where .sln and Dockerfile reside at the root, code lives inside src/, and test projects take the *.Tests suffix. Small projects with fewer than 16 files stay in a flat root folder. Once files multiply, code splits into domain-driven folders like Application, Domain, Infrastructure, Services, Repositories, and Controllers.

Project files target net10.0 with both ImplicitUsings and Nullable enabled. Setting LangVersion explicitly is forbidden because .NET 10 defaults to C# 14. Setting LangVersion=latest is equally disallowed.

Inside classes, members follow an exact sequence: constants, fields, constructors, properties, then methods. Primary constructors are preferred for clean dependency injection, while collection expressions replace verbose array syntax. Public and protected APIs require detailed XML doc comments. Codebases running older runtimes will fail immediately on these modern language features.

What it helps with

  • organize .NET 10 solution layouts and test project naming
  • enforce deterministic ordering for class members and modifiers
  • generate XML documentation tags for public classes and methods
  • set up csproj properties with implicit usings and nullable support

Example prompts for the agent

  • Build a user service using a primary constructor and XML documentation comments.
  • Add an xUnit test project to the solution via dotnet CLI.
  • Generate a Directory.Build.props file with shared build configurations.

How to install csharp

Manually: put the files in place

.github/instructions/csharp.instructions.md

The applyTo field sets which files it applies to

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about csharp

How to install csharp in Claude Code?

Add the rule file directly to your repository at .claude/rules/csharp.md.

What does the csharp rule do?

It instructs the assistant to write C# code matching .NET 10 and C# 14 standards, including naming schemes, folder layout, and XML comments.

Should LangVersion be defined in csproj?

No, the rule requires omitting LangVersion since .NET 10 automatically targets C# 14, and advises against LangVersion=latest.

Source text

csharp.instructions.md · MIT
---
applyTo: '**/*.cs'
description: 'C# (CSharp) code authoring conventions'
---
# C# Instructions

Conventions for C# development targeting .NET 10 and C# 14.

## Project Structure

Solutions follow a standard folder structure:

```text
Solution.sln
Dockerfile
src/
  Project/
    Project.csproj
    Program.cs
  Project.Tests/
    Project.Tests.csproj
```

* `.sln` and `Dockerfile` at repository root
* `src/` contains all project directories
* Project directories match `.csproj` names
* Test projects use `*.Tests` suffix

Project folder organization scales with complexity. Keep all files at root when fewer than 16 files exist. When folders become necessary, prefer DDD-style names: `Application`, `Domain`, `Infrastructure`, `Services`, `Repositories`, `Controllers`.

## Project Configuration

### Target Framework

| Target            | TFM                  | Use Case                          |
|-------------------|----------------------|-----------------------------------|
| Cross-platform    | `net10.0`            | Console apps, libraries, web APIs |
| Windows-specific  | `net10.0-windows`    | WinForms, WPF                     |
| Android/iOS/macOS | `net10.0-{platform}` | Mobile and desktop                |

```xml
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>
</Project>
```

Omit explicit `LangVersion` as .NET 10 defaults to C# 14. Avoid `LangVersion=latest`.

### Implicit Usings

| SDK                     | Implicit Namespaces                                                                          |
|-------------------------|----------------------------------------------------------------------------------------------|
| `Microsoft.NET.Sdk`     | `System`, `System.Collections.Generic`, `System.IO`, `System.Linq`, `System.Threading.Tasks` |
| `Microsoft.NET.Sdk.Web` | Base plus `Microsoft.AspNetCore.*`, `Microsoft.Extensions.*`                                 |

Add project-wide global usings:

```xml
<ItemGroup>
  <Using Include="System.Text.Json" />
</ItemGroup>
```

Use `Directory.Build.props` for shared configuration across multi-project solutions.

## Managing Projects

Essential `dotnet` CLI commands:

```bash
dotnet new list                             # Available templates
dotnet new xunit -n Project.Tests           # Create from template
dotnet sln add ./src/Project/Project.csproj # Add to solution
dotnet add reference ./src/Shared/Shared.csproj
dotnet add package Newtonsoft.Json --version 13.0.3
dotnet build && dotnet test
```

Reuse existing package versions when adding packages already present in the solution.

## Coding Conventions

### Naming

| Element            | Convention       | Example               |
|--------------------|------------------|-----------------------|
| Classes/Files      | `PascalCase`     | `UserService.cs`      |
| Interfaces         | `IPascalCase`    | `IRepository`         |
| Methods/Properties | `PascalCase`     | `ProcessAsync`        |
| Fields             | `camelCase`      | `_logger`, `isActive` |
| Base classes       | `PascalCaseBase` | `WidgetBase`          |
| Type parameters    | `TName`          | `TEntity`             |

### Class Structure

Member ordering:

1. `const` → `static readonly` → `readonly` → instance fields
2. Constructors
3. Properties
4. Methods

Within categories, order: `public` → `protected` → `private` → `internal`.

Access modifier keyword order: `[access] [static] [readonly] [async] [override|virtual|abstract] [partial]`

### Variable Declarations and Primary Constructors

Use `var` when type is obvious from the right side. Use target-typed `new()` when type is declared on left:

```csharp
var service = new UserService();
Dictionary<string, int> lookup = new();
```

Primary constructors are preferred when initialization is straightforward:

```csharp
public class UserService(ILogger<UserService> logger, IRepository repo)
{
    public void Process() => logger.LogInformation("Processing");
}
```

Use traditional constructors when validation runs before assignment or multiple overloads exist.

Collection expressions: `int[] nums = [1, 2, 3];` and spread: `[..existing, 4, 5]`.

Prefer early returns over deep nesting.

## Code Documentation

Public and protected members require XML documentation.

Guidelines:

* Use `<see cref="..."/>` for inline type and member references
* Use `<inheritdoc/>` on implementations and overrides
* Use `<inheritdoc cref="..."/>` when default resolution is insufficient
* Document exceptions with `<exception cref="...">` when methods throw
* Include `<param>` for all parameters and `<returns>` for non-void methods

```csharp
/// <summary>
/// Provides operations for managing user accounts.
/// </summary>
/// <remarks>
/// This service requires a configured <see cref="IUserRepository"/> and validates
/// all inputs before persistence. Thread-safe for concurrent access.
/// </remarks>
public class UserService(IUserRepository repository, ILogger<UserService> logger)
{
    /// <summary>
    /// Retrieves a user by their unique identifier.
    /// </summary>
    /// <param name="userId">The unique identifier of the user to retrieve.</param>
    /// <param name="cancellationToken">Token to cancel the operation.</param>
    /// <returns>
    /// The <see cref="User"/> if found; otherwise, <see langword="null"/>.
    /// </returns>
    /// <exception cref="ArgumentException">
    /// Thrown when <paramref name="userId"/> is empty or whitespace.
    /// </exception>
    public async Task<User?> GetUserAsync(string userId, CancellationToken cancellationToken = default)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(userId);
        return await repository.FindByIdAsync(userId, cancellationToken);
    }

    /// <summary>
    /// Creates a new user with the specified details.
    /// </summary>
    /// <param name="name">The display name for the user.</param>
    /// <param name="email">The email address for the user.</param>
    /// <param name="cancellationToken">Token to cancel the operation.</param>
    /// <returns>The created <see cref="User"/> with assigned identifier.</returns>
    /// <exception cref="InvalidOperationException">
    /// Thrown when a user with the same <paramref name="email"/> already exists.
    /// </exception>
    /// <example>
    /// <code>
    /// var user = await userService.CreateUserAsync("Jane Doe", "[email protected]");
    /// Console.WriteLine($"Created user: {user.Id}");
    /// </code>
    /// </example>
    public async Task<User> CreateUserAsync(
        string name,
        string email,
        CancellationToken cancellationToken = default)
    {
        var existing = await repository.FindByEmailAsync(email, cancellationToken);
        if (existing is not null)
            throw new InvalidOperationException($"User with email '{email}' already exists.");

        var user = new User { Name = name, Email = email };
        await repository.AddAsync(user, cancellationToken);
        logger.LogInformation("Created user {UserId}", user.Id);
        return user;
    }
}

/// <summary>
/// Represents a user account in the system.
/// </summary>
/// <typeparam name="TMetadata">The type of additional metadata associated with the user.</typeparam>
public class User<TMetadata> where TMetadata : class
{
    /// <summary>Gets or sets the unique identifier.</summary>
    public required string Id { get; set; }

    /// <summary>Gets or sets the display name.</summary>
    public required string Name { get; set; }

    /// <summary>Gets or sets optional metadata.</summary>
    public TMetadata? Metadata { get; set; }
}
```

Interface implementations use `<inheritdoc/>`:

```csharp
public interface IProcessor
{
    /// <summary>Processes the input and returns the result.</summary>
    /// <param name="input">The input to process.</param>
    /// <returns>The processed result.</returns>
    string Process(string input);
}

public class UpperCaseProcessor : IProcessor
{
    /// <inheritdoc/>
    public string Process(string input) => input.ToUpperInvariant();
}
```

## Namespaces

File-scoped namespaces are preferred:

```csharp
namespace Company.Project.Feature;

public class Example { }
```

Namespaces align with folder structure.

## Nullable Reference Types

Enable at project level with `<Nullable>enable</Nullable>`.

### Annotations

* Use `?` for nullable types: `string? GetName()`
* Use `[NotNull]`, `[MaybeNull]`, `[NotNullWhen(bool)]` for complex scenarios
* Prefer `required` modifier for non-nullable properties without defaults

### Null-Forgiving Operator

Avoid `!` except when:

* Framework APIs lack nullable annotations
* Test code asserts non-null conditions
* Preceding validation guarantees non-null

```csharp
if (!dict.TryGetValue(key, out var value))
    throw new KeyNotFoundException(key);
return value!.ToUpper();
```

## Additional Conventions

* Prefer `Span<T>` and `ReadOnlySpan<T>` for array operations
* Use `out var` pattern: `dict.TryGetValue("key", out var value)`
* Use `System.Threading.Lock` with `EnterScope()` for synchronization
* Omit types on lambda parameters

## Complete Example

Demonstrates naming, structure, generics, primary constructors, nullable annotations, access modifier ordering, `Lock` type, and `field` keyword:

```csharp
namespace Company.Project.Widgets;

using ItemCache = Dictionary<string, object>;

/// <summary>Defines folding behavior for widgets.</summary>
public interface IWidget
{
    Task StartFoldingAsync(CancellationToken cancellationToken);
}

/// <summary>Base for widgets processing data into collections.</summary>
public abstract class WidgetBase<TData, TCollection>(
    ILogger logger,
    IReadOnlyList<string> prefixes)
    where TData : class
    where TCollection : IEnumerable<TData>
{
    protected static readonly int DefaultProcessCount = 10;
    protected readonly ILogger Logger = logger;
    private readonly Lock _lock = new();
    private readonly IReadOnlyList<string> _prefixes = prefixes;

    protected int nextProcess;

    public IReadOnlyList<string> Prefixes => _prefixes;

    public string? LastProcessedId
    {
        get => field;
        protected set => field = value?.Trim();
    }

    public int ApplyFold(TData item)
    {
        if (item is null) return 0;

        using (_lock.EnterScope())
        {
            var folds = ProcessFold(item);
            nextProcess += [..folds].Count;
            return nextProcess;
        }
    }

    protected abstract TCollection ProcessFold(TData item);
}

/// <summary>Widget using stack-based collection.</summary>
public class StackWidget<TData>(
    ILogger<StackWidget<TData>> logger,
    IRepository<TData> repository)
    : WidgetBase<TData, Stack<TData>>(logger, ["first", "second"]), IWidget
    where TData : class
{
    private readonly IRepository<TData> _repository = repository;

    /// <inheritdoc/>
    public async Task StartFoldingAsync(CancellationToken cancellationToken)
    {
        if (cancellationToken.IsCancellationRequested) return;

        var items = await _repository.GetAllAsync(cancellationToken);
        foreach (var item in items)
            ApplyFold(item);

        Logger.LogInformation("Processed {Count} items", nextProcess);
    }

    /// <inheritdoc/>
    protected override Stack<TData> ProcessFold(TData item)
    {
        Stack<TData> result = new();
        result.Push(item);
        LastProcessedId = item.GetHashCode().ToString();
        return result;
    }
}
```

© microsoft · MIT · microsoft/hve-core

Similar IDE rules

All IDE rules for Programming languages →

csharp by other authors comes first.

csharp official github csharp — a rule that pins Copilot to one C# style: naming, nullable types, formatting and ASP.NET Core patterns. Useful when the agent writes differently in every file. CX Codex +1 ★ 41,430repo stars csharp-developer https://github.com/Jeffallan csharp-developer enforces .NET 8 and C# 12 development practices for ASP.NET Core APIs and Blazor apps. Useful when writing asynchronous services with EF Core and MediatR. CX Codex +1 5,200installs modern-csharp codewithmukesh modern-csharp teaches the agent C# 14 syntax: primary constructors, collection expressions, the field keyword, extension blocks. Useful when you write new C# or modernize old code. CX Codex +1 4,100installs csharp-refactoring dotnet csharp-refactoring is a skill for Claude Code that refactors C#/.NET code without changing behavior. It uses Roslyn bindings rather than text search for structurally correct renames and extractions. CX Codex +1 3,000installs modern-csharp-coding-standards Aaronontheweb modern-csharp-coding-standards enforces modern C# 12+ coding standards, including immutable records, pattern matching, Span<T>, zero-allocation buffers, and async best practices. CX Codex +1 2,300installs csharp-expert dotnet csharp-expert — a skill for Claude Code, Codex, Cursor and other agents that routes C# and .NET requests to the right specialist or locates the missing plugin in the dotnet/skills marketplace. CX Codex +1 2,200installs csharp-concurrency-patterns Aaronontheweb csharp-concurrency-patterns guides AI agents in selecting the right .NET concurrency abstractions, from async/await to Channels and Akka.NET. Useful when refactoring work queues and eliminating thread locks. CX Codex +1 1,600installs

From the same set148

The whole set →
PowerPoint Subagent PowerPoint Subagent executes PowerPoint operations: extracts slide content to YAML, builds decks from YAML and styles, validates quality using vision checks. Use it to automate presentation creation in Claude Code. CX Codex +1 ★ 1,627repo stars hve-slides hve-slides is a Claude Code skill for creating, updating, and auditing interactive HTML presentations in HVE Core, with presenter controls and keyboard navigation. CX Codex +1 ★ 1,627repo stars licensing-posture The licensing-posture rule guides how contributors quote, paraphrase, and attribute third-party standards. It applies to reference material in skills and .copilot-tracking. CX Codex +1 ★ 1,627repo stars Skill Assessor Skill Assessor is a Claude Code subagent that scans code for vulnerabilities against OWASP, Secure by Design, and MCSB. It reports findings with statuses and fix examples. CX Codex +1 ★ 1,627repo stars cspell-config This skill resolves the cspell configuration used by a project command and adds project vocabulary or ignored paths. Use it when spell-checking flags terms your codebase relies on. CX Codex +1 ★ 1,627repo stars tts-voiceover tts-voiceover turns PowerPoint speaker notes in YAML into voice-over WAV files using Azure AI Speech neural voices with SSML control. Use it when you need automatic narration for slides without manual recording. CX Codex +1 ★ 1,627repo stars Issue Triage Agent Issue Triage Agent — a subagent for triaging individual GitHub issues. It categorizes tickets, assigns component labels, and sets priority levels based on repository guidelines. CX Codex +1 ★ 1,627repo stars architecture-diagrams architecture-diagrams creates ASCII or Mermaid diagrams from infrastructure files and declared data catalogs. Use it to map system boundaries and relationships for reviews or design discussions. CX Codex +1 ★ 1,627repo stars

Project sponsors

Companies that keep this analytics open