klod68/cqrs-standards

---

name: cqrs-standards description: "Use when implementing or reviewing CQRS with MediatR — command handlers, query handlers, pipeline behaviors, or request/response patterns in .NET projects."

Skill: CQRS via MediatR Standards

Identity

| Field | Value | |---|---| | Name | CQRS via MediatR Standards | | Domain | CQRS, MediatR, Application Layer | | Level | Feature | | Tags | cqrs, mediatr, command, query, pipeline-behavior |

When to Apply

Activate this skill when the task involves:

• Implementing command or query handlers with MediatR
• Pipeline behaviors (validation, logging, transactions)
• Request/response contracts for use cases
• Application-layer orchestration following CQRS
• Splitting reads from writes at the architecture level

Rules

These rules layer on top of base architectural standards. On conflict, these win.

<!-- SHARED:rules/cqrs.md -->

CQRS via MediatR — Standards

Apply these rules in addition to the foundational principles for projects using MediatR. CQRS (Command Query Responsibility Segregation) is enforced at the Application layer. Every use case maps to either a Command or a Query — never both.

---

Governing Principle

Commands change state. They do not return data beyond a status or a created ID. Queries return data. They do not change state. These two concerns MUST NEVER be mixed in a single handler.

Mixing the two makes it impossible to cache query results, replay commands for audit, or scale read and write paths independently. It also makes handlers harder to test — you cannot verify a state change without also verifying an expected return value, coupling two concerns in one assertion.

User Action
     │
     ▼
┌────────────────────────────────────────────┐
│              MediatR Pipeline              │
│  Logging → Validation → Transaction → ...  │
└─────────────────┬──────────────────────────┘
                  │
        ┌─────────┴─────────┐
        │                   │
   ┌────▼────┐         ┌────▼────┐
   │ Command │         │  Query  │
   │ Handler │         │ Handler │
   └────┬────┘         └────┬────┘
        │                   │
   Writes State        Reads State
   Returns Result<T>   Returns DTO/List

---

Commands

Naming Convention

| Item | Convention | Example | |---|---|---| | Command record | {Verb}{Subject}Command | Create{Entity}Command | | Handler class | {Verb}{Subject}Handler | Create{Entity}Handler | | Validator class | {Verb}{Subject}CommandValidator | Create{Entity}CommandValidator | | Return type | Result<{Id or void}> | Result<{EntityId}> |

Command Record Template

// Application/Commands/{FeatureName}/{CommandName}.cs
namespace {Solution}.Application.Commands.{FeatureName};

/// <summary>
/// Command to {verb + subject in present tense}.
/// </summary>
/// <remarks>UC-{NNN}</remarks>
public sealed record {CommandName}(
    {PropertyType} {PropertyName}   // one parameter per input, no mutable state
) : IRequest<Result<{TResult}>>;

Rules for Command records:

• Always sealed record — not class, not mutable.
• Return type is always Result<T> from FluentResults or equivalent.
• Commands that create entities return Result<{EntityId}>.
• Commands that modify or delete entities return Result (no value payload).

Command Handler Template

// Application/Commands/{FeatureName}/{CommandName}Handler.cs
namespace {Solution}.Application.Commands.{FeatureName};

public sealed class {CommandName}Handler
    : IRequestHandler<{CommandName}, Result<{TResult}>>
{
    private readonly I{AggregateRepository} _repository;

    public {CommandName}Handler(I{AggregateRepository} repository)
        => _repository = repository;

    public async Task<Result<{TResult}>> Handle(
        {CommandName} request, CancellationToken ct)
    {
        // 1. Load aggregate (if modifying existing)
        // 2. Execute domain factory or domain method — ALL business logic lives here
        // 3. Persist via repository
        // 4. await _db.SaveChangesAsync(ct)  ← exactly here, not in the repository
        // 5. Return Result<T>
        throw new NotImplementedException(); // Implementer fills this
    }
}

Rules for Command handlers:

• Maximum responsibility: orchestrate. No business logic inside the handler body.
• Business logic belongs in the domain entity (factory method or domain method).
• SaveChangesAsync is called here (or in a TransactionBehavior) — never in the repository.
• Never return the full entity — return only the ID or a status.

FluentValidation Validator Template

public sealed class {CommandName}Validator
    : AbstractValidator<{CommandName}>
{
    public {CommandName}Validator()
    {
        RuleFor(x => x.{PropertyName})
            .NotEmpty()
            .WithMessage("{PropertyName} is required.")
            .MaximumLength({N})
            .WithMessage("{PropertyName} must not exceed {N} characters.");
    }
}

---

Queries

Naming Convention

| Item | Convention | Example | |---|---|---| | Query record | Get{Subject}By{Criterion}Query or Get{Subjects}Query | Get{Entity}ByIdQuery | | Handler class | Get{Subject}By{Criterion}Handler | Get{Entity}ByIdHandler | | Result DTO | {Subject}Dto or {Subject}Response | {Entity}Dto | | Return type | {ResultDto} or IReadOnlyList<{ResultDto}> or {ResultDto}? | |

Query Handler Template

public sealed class {QueryName}Handler
    : IRequestHandler<{QueryName}, {QueryResult}>
{
    private readonly I{ReadRepository} _repository;

    public {QueryName}Handler(I{ReadRepository} repository)
        => _repository = repository;

    public async Task<{QueryResult}> Handle(
        {QueryName} request, CancellationToken ct)
    {
        // 1. Retrieve data via repository (read-only, AsNoTracking)
        // 2. Map domain entity → DTO  (never return the entity directly)
        // 3. Return DTO
        throw new NotImplementedException(); // Implementer fills this
    }
}

Rules for Query handlers:

• NEVER modify state. NEVER call a write repository method.
• NEVER return domain entities — always map to DTOs.
• Repository calls use AsNoTracking() — always.
• If the resource is not found, return null — do NOT throw.

---

MediatR Pipeline Behaviors (Order Enforced)

| Order | Behavior | Scope | Purpose | |---|---|---|---| | 1 | LoggingBehavior<,> | All requests | Structured request/response logging | | 2 | ValidationBehavior<,> | All requests with a validator | FluentValidation execution, short-circuit on failure | | 3 | TransactionBehavior<,> | Commands only | Wrap handler in a DB transaction, dispatch domain events post-commit |

---

SaveChangesAsync — The Unit of Work

SaveChangesAsync is called in exactly ONE place per request: the Command handler or in the TransactionBehavior. Never in a repository method.

// Correct: in the handler
public async Task<Result<{EntityId}>> Handle(
    Create{Entity}Command request, CancellationToken ct)
{
    var result = {Entity}.Create(request.{Property});
    if (result.IsFailure) return result.ToResult<{EntityId}>();

    await _repository.AddAsync(result.Value, ct);
    await _db.SaveChangesAsync(ct);  // ← exactly here
    return Result.Success(result.Value.Id);
}

// Wrong: in the repository — VIOLATION
public async Task AddAsync({Entity} entity, CancellationToken ct)
{
    await _db.AddAsync(entity, ct);
    await _db.SaveChangesAsync(ct); // BLOCKER
}

---

CQS Enforcement Checklist (Reviewer Fitness Functions)

| Check | Violation | Severity | |---|---|---| | Command returns entity data | Command handler returns domain entity or full DTO | BLOCKER | | Query modifies state | Query handler calls write repository or SaveChangesAsync | BLOCKER | | Mixed handler | Single handler implements both command and query behavior | BLOCKER | | SaveChangesAsync in repository | Write operation committed inside repository method | BLOCKER | | Domain entity in query result | Handler returns entity instead of DTO | MAJOR | | No validator for command | Command record with no corresponding AbstractValidator<> | MAJOR |

Common Anti-Patterns

| Anti-Pattern | Fix | |---|---| | Handler that queries and commands | Split into separate Command + Query handlers | | SaveChangesAsync in repository | Move to handler or TransactionBehavior | | Returning full domain entity from query handler | Map to dedicated DTO | | Validator with business rule logic | Move business rules to domain entity; keep validator for input shape/format | | Re-ordering pipeline behaviors | Behaviors are position-sensitive; add to the end |

---

See Also

• api-contracts.md — Interface-first design, return type abstractions, contract versioning
• design-patterns.md — Approved GoF patterns: Factory, Repository, Decorator, Strategy, Specification
• result-error-handling.md — Result object pattern, error constants, exception boundaries
• ef-core.md — EF Core entity design, migrations, DbContext, querying, repository pattern
• naming.md — Naming conventions for types, methods, properties, namespaces
• tdd.md — Test-driven development with xUnit, FluentAssertions, NSubstitute