C_SHARP_SKILLS/AGENTS.md

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:

   ./.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:

   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:

.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.