AGENTS.md for .NET

# AGENTS.md

Instructions for coding agents working in this .NET repository. Cursor, Claude Code, Codex, Copilot, and other agents should follow this file before they guess.

## Stack

This repository is a .NET application. Nullable reference types stay enabled. Match minimal APIs or controllers, whichever the project already uses, and ship schema changes as migrations.

## Layout

- Endpoints or controllers stay next to the feature folder the repo uses.
- EF Core DbContext and configurations stay in the data project if there is one.
- Do not add a second hosting model.

## Commands

- Test: `dotnet test`
- Run: `dotnet run`
- Format: `dotnet format`

Use the script the repo already defines when it differs from the command above.

## Conventions

- Respect nullable annotations. Do not silence them with `!` unless the value was just checked.
- Validate input with the project's data annotations or fluent validation.
- Use async all the way. Do not block on `.Result`.
- Migrations ship with model changes. Do not hand-edit a snapshot to hide a mistake.
- Inject dependencies through the constructor. Do not service-locate in a loop.
- Log with ILogger. Do not use Console.WriteLine for request failures.

## Testing

Add or update tests when behavior changes.

Add an xUnit, NUnit, or MSTest test matching the repo. Cover the validation failure.

## Style

- Optimize for the next reader over the shortest diff.
- Comment only when the why is non-obvious.
- Name things the way neighboring files already do.
- Do not reformat code you did not change.

## Errors

- Fail at the boundary. Do not swallow errors.
- Return a ProblemDetails or the project's error type for expected failures. Unexpected exceptions hit the exception handler.

## Scope

- Do the requested task. Do not refactor unrelated code.
- Match the rigor already in the repo. Fix what you touch.
- Ask one clarifying question only when the task cannot be finished without it. Otherwise state the assumption and continue.

## Avoid

- Do not catch Exception and return Ok.
- Do not use dynamic to dodge a type.
- Do not query inside a serializer loop. Shape the response in the handler.
- Do not store secrets in appsettings that are committed.

## Done when

- The requested behavior works.
- `dotnet test` passes and `dotnet format` leaves the diff clean.
- The diff stays inside the task.
- You list anything you could not run.