# AGENTS.md - C# 14 / .NET 10 Expert Agent Instructions

## Purpose

This file tells AI coding agents how to work in this repository as a panel of senior C# and .NET engineers. The agent must produce correct, maintainable, testable, secure C# code and must route itself to the right skill files before changing code.

## Startup Instructions

Before working on any task:

1. Read this `AGENTS.md`.
2. Read the main skill router:

   ```text
   ./.ai/SKILLS.md
   ```

3. Identify the task type: language, library, data, web, Blazor, API, packaging, testing, security, performance, or review.
4. Load the matching skill files listed in `.ai/SKILLS.md`.
5. Inspect the existing solution before writing code:
   - `*.sln`, `*.slnx`
   - `*.csproj`, `Directory.Build.props`, `Directory.Packages.props`, `global.json`
   - existing namespaces, nullable settings, analyzers, test projects, CI scripts, and style rules
6. Do not invent project conventions. Follow the existing codebase unless the user asks to refactor.

## Core Engineering Rules

- Prefer modern .NET and modern C# features, but only when they improve clarity.
- Keep code readable before clever.
- Treat warnings as future defects.
- Prefer small functions with clear names and clear inputs and outputs.
- Prefer explicit domain types over loosely typed strings, dictionaries, or dynamic objects.
- Enable and respect nullable reference types.
- Validate external input at boundaries.
- Use guard clauses for invalid arguments and impossible states.
- Do not swallow exceptions. Either handle them meaningfully or let them propagate with context.
- Use `async`/`await` for I/O-bound operations. Avoid blocking on async code with `.Result` or `.Wait()`.
- Prefer dependency injection for services, repositories, HTTP clients, loggers, and options.
- Use unit tests for pure/domain logic and integration tests for database, file, web, or external boundaries.
- Do not add packages unless there is a clear reason and the package is actively maintained.
- Never hardcode secrets, connection strings, tokens, passwords, or environment-specific paths.

## Preferred Workflow

For every task:

1. Restate the goal internally as a concrete deliverable.
2. Identify impacted files and APIs.
3. Make the smallest safe change that satisfies the requirement.
4. Add or update tests.
5. Run or propose the exact commands:

   ```bash
   dotnet restore
   dotnet build
   dotnet test
   dotnet format
   ```

6. Explain what changed and any risks, assumptions, or follow-up tasks.

## Output Rules

When returning code:

- Show complete files or precise patches when possible.
- Include file paths.
- Include commands to build and test.
- Mention assumptions.
- Mention any behavior change.
- Keep examples aligned with the target framework and language version in the project.

## Skill Routing

Use `.ai/SKILLS.md` as the routing table. Do not load every skill for every task. Load the minimum needed files plus `00-agent-operating-rules.md` and `17-code-review-definition-of-done.md`.


## Reusable Pattern Convention: Unit of Work

When working with repository pattern, Unit of Work, EF Core CRUD/query changes, transaction boundaries, or controller/service data-access refactors, load:

```text
.ai/skills/18-unit-of-work-pattern.md
```

Use that skill to keep one shared `DbContext` per unit of work, register the pattern with an appropriate scoped lifetime, expose repositories through `IUnitOfWork`, and commit with a single `SaveChangesAsync` call per logical operation.