From 9d332b4ac5ea7d8e443137194e53cede31218632 Mon Sep 17 00:00:00 2001
From: Adam Hathcock <adam@hathcock.uk>
Date: Mon, 13 Oct 2025 11:52:18 +0100
Subject: [PATCH] add agents file

---
 AGENTS.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..a47fa029
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,64 @@
+---
+description: 'Guidelines for building C# applications'
+applyTo: '**/*.cs'
+---
+
+# C# Development
+
+## C# Instructions
+- Always use the latest version C#, currently C# 13 features.
+- Write clear and concise comments for each function.
+
+## General Instructions
+- Make only high confidence suggestions when reviewing code changes.
+- Write code with good maintainability practices, including comments on why certain design decisions were made.
+- Handle edge cases and write clear exception handling.
+- For libraries or external dependencies, mention their usage and purpose in comments.
+
+## Naming Conventions
+
+- Follow PascalCase for component names, method names, and public members.
+- Use camelCase for private fields and local variables.
+- Prefix interface names with "I" (e.g., IUserService).
+
+## Code Formatting
+
+- Use CSharpier for all code formatting to ensure consistent style across the project.
+- Install CSharpier globally: `dotnet tool install -g csharpier`
+- Format files with: `dotnet csharpier format .`
+- Configure your IDE to format on save using CSharpier.
+- CSharpier configuration can be customized via `.csharpierrc` file in the project root.
+- Trust CSharpier's opinionated formatting decisions to maintain consistency.
+
+## Project Setup and Structure
+
+- Guide users through creating a new .NET project with the appropriate templates.
+- Explain the purpose of each generated file and folder to build understanding of the project structure.
+- Demonstrate how to organize code using feature folders or domain-driven design principles.
+- Show proper separation of concerns with models, services, and data access layers.
+- Explain the Program.cs and configuration system in ASP.NET Core 9 including environment-specific settings.
+
+## Nullable Reference Types
+
+- Declare variables non-nullable, and check for `null` at entry points.
+- Always use `is null` or `is not null` instead of `== null` or `!= null`.
+- Trust the C# null annotations and don't add null checks when the type system says a value cannot be null.
+
+## Testing
+
+- Always include test cases for critical paths of the application.
+- Guide users through creating unit tests.
+- Do not emit "Act", "Arrange" or "Assert" comments.
+- Copy existing style in nearby files for test method names and capitalization.
+- Explain integration testing approaches for API endpoints.
+- Demonstrate how to mock dependencies for effective testing.
+- Show how to test authentication and authorization logic.
+- Explain test-driven development principles as applied to API development.
+
+## Performance Optimization
+
+- Guide users on implementing caching strategies (in-memory, distributed, response caching).
+- Explain asynchronous programming patterns and why they matter for API performance.
+- Demonstrate pagination, filtering, and sorting for large data sets.
+- Show how to implement compression and other performance optimizations.
+- Explain how to measure and benchmark API performance.