Add Claude Code rules for architecture and coding standards

Adds nine rule files under .claude/rules/ covering C# standards, domain layer, application layer, infrastructure layer, API design, Blazor components, React frontend, testing patterns, and error handling — giving Claude Code per-topic guidance aligned with the project's Clean Architecture and DDD conventions.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: xenobiasoft

.claude/rules/api-design.md

@@ -0,0 +1,52 @@
+---
+paths:
+  - "src/backend/Sudoku.Api/**/*.cs"
+---
+
+# API Design Guidelines
+
+## CQRS Command vs Query Separation
+
+**Command endpoints** (`POST`, `PUT`, `PATCH`, `DELETE`) mutate state and **must not return domain data**:
+- `201 Created` with a `Location` header for creates
+- `204 No Content` for updates and deletes
+
+**Query endpoints** (`GET`) read state and return data.
+
+If a client needs the updated resource after a command, it issues a separate GET. Mixing the two breaks CQRS separation.
+
+## REST Controller Examples
+
+```csharp
+// COMMAND endpoint — mutates state, returns no data
+[HttpPost("{alias}/games/{difficulty}")]
+[ProducesResponseType(StatusCodes.Status201Created)]
+[ProducesResponseType(StatusCodes.Status400BadRequest)]
+public async Task<ActionResult> CreateGame(string alias, string difficulty)
+{
+    var result = await _gameService.CreateGameAsync(alias, difficulty);
+    if (!result.IsSuccess)
+        return BadRequest(result.Error);
+
+    return Created($"/api/players/{alias}/games/{result.Value.Id}", null);
+}
+
+// QUERY endpoint — reads state, returns data
+[HttpGet("{alias}/games/{gameId}")]
+[ProducesResponseType(typeof(GameDto), StatusCodes.Status200OK)]
+[ProducesResponseType(StatusCodes.Status404NotFound)]
+public async Task<ActionResult<GameDto>> GetGame(string alias, string gameId)
+{
+    var result = await _gameService.GetGameAsync(gameId);
+    if (!result.IsSuccess)
+        return NotFound();
+
+    return Ok(result.Value);
+}
+```
+
+## Rules
+- Validate all user inputs at the controller boundary
+- Use `Result<T>` from the application layer; map to HTTP status codes in the controller
+- Include XML documentation for public API endpoints
+- Never return domain data from command endpoints

.claude/rules/application-layer.md

@@ -0,0 +1,35 @@
+---
+paths:
+  - "src/backend/Sudoku.Application/**/*.cs"
+---
+
+# Application Layer Guidelines
+
+## CQRS Pattern
+```csharp
+public record CreateGameCommand(string PlayerAlias, GameDifficulty Difficulty);
+public record GetGameQuery(GameId GameId);
+```
+
+## Command/Query Handlers
+```csharp
+public class CreateGameCommandHandler : ICommandHandler<CreateGameCommand>
+{
+    private readonly IGameRepository _gameRepository;
+    private readonly IDomainEventDispatcher _eventDispatcher;
+
+    public async Task<Result> HandleAsync(CreateGameCommand command)
+    {
+        // 1. Application logic / validation
+        // 2. Domain interaction
+        // 3. Persistence
+        // 4. Dispatch domain events
+    }
+}
+```
+
+## Rules
+- All operations flow through `IMediator`
+- Handlers always return `Result<T>` — never throw exceptions for expected failures
+- Repository interfaces are defined here; implementations live in Infrastructure
+- No business logic in handlers — delegate to domain aggregates

.claude/rules/blazor-components.md

@@ -0,0 +1,46 @@
+---
+paths:
+  - "src/frontend/Sudoku.Blazor/**/*.razor"
+  - "src/frontend/Sudoku.Blazor/**/*.cs"
+---
+
+# Blazor Component Guidelines
+
+## Component Structure
+```csharp
+@page "/game/{GameId}"
+@using Sudoku.Application
+@inject IGameApplicationService GameService
+
+<PageTitle>Sudoku Game</PageTitle>
+
+<div class="sudoku-board">
+    @if (game != null)
+    {
+        <SudokuBoard Game="@game" OnMoveMade="HandleMoveMade" />
+    }
+</div>
+
+@code {
+    [Parameter] public string GameId { get; set; } = string.Empty;
+    private GameDto? game;
+
+    protected override async Task OnInitializedAsync()
+    {
+        var result = await GameService.GetGameAsync(GameId);
+        if (result.IsSuccess)
+            game = result.Value;
+    }
+
+    private async Task HandleMoveMade(int row, int column, int value)
+    {
+        // Handle move logic
+    }
+}
+```
+
+## Rules
+- Use `@inject` for dependency injection in components
+- Handle `Result<T>` from application services — don't assume success
+- Use `async/await` for all service calls
+- Blazor components are tested with bunit

.claude/rules/csharp-standards.md

@@ -0,0 +1,44 @@
+# C# Coding Standards & Conventions
+
+## Naming Conventions
+- PascalCase for public members, classes, and methods
+- camelCase for private fields and local variables
+- UPPER_CASE for constants
+- Prefix private fields with underscore: `_fieldName`
+
+## File Organization
+- One public class per file
+- File name should match class name
+- Group related classes in appropriate namespaces
+
+## Code Style
+- Use expression-bodied members when appropriate
+- Prefer `var` for local variables when type is obvious
+- Use `readonly` for immutable fields
+- Use primary constructors when possible
+- Always use curly braces for code blocks
+
+## Dependency Injection
+Register services via extension methods:
+
+```csharp
+public static class ServiceCollectionExtensions
+{
+    public static IServiceCollection AddSudokuServices(this IServiceCollection services)
+    {
+        services.AddScoped<IGameRepository, CosmosDbGameRepository>();
+        services.AddScoped<ICommandHandler<CreateGameCommand>, CreateGameCommandHandler>();
+        services.AddScoped<IGameApplicationService, GameApplicationService>();
+        return services;
+    }
+}
+```
+
+## Anti-Patterns to Avoid
+- **Anemic Domain Models**: don't create entities that are just data containers
+- **Tight Coupling**: avoid direct dependencies between layers
+- **God Objects**: don't create classes with too many responsibilities
+- **Primitive Obsession**: use value objects instead of primitives for domain concepts
+- **Magic Numbers**: use constants or enums
+- **Long Methods**: keep methods focused and under 20 lines when possible
+- **Deep Nesting**: avoid deeply nested conditionals and loops

.claude/rules/domain-layer.md

@@ -0,0 +1,69 @@
+---
+paths:
+  - "src/backend/Sudoku.Domain/**/*.cs"
+---
+
+# Domain Layer Guidelines
+
+## Entity Structure
+```csharp
+public class SudokuGame : AggregateRoot
+{
+    private readonly List<Cell> _cells;
+    private readonly List<DomainEvent> _domainEvents;
+
+    public GameId Id { get; private set; }
+    public PlayerAlias PlayerAlias { get; private set; }
+    public GameDifficulty Difficulty { get; private set; }
+    public GameStatus Status { get; private set; }
+
+    private SudokuGame() { } // Private constructor for EF Core
+
+    public static SudokuGame Create(PlayerAlias playerAlias, GameDifficulty difficulty)
+    {
+        // Validation and creation logic
+    }
+
+    public void MakeMove(int row, int column, int value)
+    {
+        // Business validation → state changes → raise domain event
+    }
+}
+```
+
+## Value Objects
+```csharp
+public record GameId(Guid Value)
+{
+    public static GameId New() => new(Guid.NewGuid());
+    public static GameId FromString(string value) => new(Guid.Parse(value));
+}
+```
+
+## Domain Events
+```csharp
+public record GameCreatedEvent(GameId GameId, PlayerAlias PlayerAlias, GameDifficulty Difficulty) : DomainEvent;
+public record MoveMadeEvent(GameId GameId, int Row, int Column, int Value) : DomainEvent;
+```
+
+## Specifications
+```csharp
+public interface ISpecification<T>
+{
+    Expression<Func<T, bool>> Criteria { get; }
+}
+
+public class GameByPlayerSpecification : ISpecification<Game>
+{
+    private readonly PlayerAlias _playerAlias;
+
+    public Expression<Func<Game, bool>> Criteria =>
+        game => game.PlayerAlias == _playerAlias;
+}
+```
+
+## Rules
+- No business logic in controllers or handlers — all invariants enforced inside aggregates
+- Raise domain events for every significant state change
+- Use private setters; expose state only through domain methods
+- Use factory methods (`Create()`) instead of public constructors

.claude/rules/error-handling.md

@@ -0,0 +1,31 @@
+# Error Handling Patterns
+
+## Domain Exceptions
+```csharp
+public class InvalidMoveException : DomainException
+{
+    public InvalidMoveException(int row, int column, int value)
+        : base($"Invalid move: {value} at position ({row}, {column})")
+    {
+    }
+}
+```
+
+## Result Pattern
+```csharp
+public class Result<T>
+{
+    public bool IsSuccess { get; }
+    public T? Value { get; }
+    public string? Error { get; }
+
+    public static Result<T> Success(T value) => new(true, value, null);
+    public static Result<T> Failure(string error) => new(false, default, error);
+}
+```
+
+## Rules
+- Use `Result<T>` for expected failures — never throw exceptions for them
+- Use domain exceptions only for invariant violations inside aggregates
+- Validate at system boundaries (user input, external APIs); trust internal code
+- Don't add error handling for scenarios that can't happen

.claude/rules/infrastructure-layer.md

@@ -0,0 +1,28 @@
+---
+paths:
+  - "src/backend/Sudoku.Infrastructure/**/*.cs"
+---
+
+# Infrastructure Layer Guidelines
+
+## Repository Implementations
+```csharp
+public class AzureBlobGameRepository : IGameRepository
+{
+    private readonly BlobServiceClient _blobServiceClient;
+    private readonly ILogger<AzureBlobGameRepository> _logger;
+
+    public async Task<Game?> GetByIdAsync(GameId id)
+    {
+        // Implementation with proper error handling
+    }
+}
+```
+
+## Rules
+- Implement interfaces defined in the Application layer — never the reverse
+- `CosmosDbGameRepository` is the primary persistent store
+- `InMemoryPuzzleRepository` is for puzzle generation only (performance optimization, not persisted)
+- `IDomainEventDispatcher` dispatches domain events after persistence
+- Use `async/await` consistently throughout
+- Dispose of resources properly