chore(backend): install AI agent skills for the .NET stack

Run autoskills in backend/: detects .NET/C#/ASP.NET Core/Minimal API and installs 13 skills for universal (.agents) and claude-code (.claude) agents, with backend/skills-lock.json. Adds ASP.NET Core, Minimal API + OpenAPI, file-upload and containerization skills on top of the prior C#/.NET set. Removes the stale root skills from the old layout.
2026-07-05 03:48:31 +02:00
parent f2933caa90
commit 3b98a05c3b
43 changed files with 1808 additions and 0 deletions
@@ -0,0 +1,81 @@
+# APIs: Minimal And Controllers
+
+Primary docs:
+- https://learn.microsoft.com/aspnet/core/fundamentals/minimal-apis
+- https://learn.microsoft.com/aspnet/core/web-api/
+- https://learn.microsoft.com/aspnet/core/fundamentals/error-handling-api
+
+## First Decision
+
+Choose between:
+
+- Minimal APIs for focused, low-ceremony HTTP endpoints
+- controller-based APIs for richer MVC conventions and attribute-driven behavior
+
+Do not mix both styles in the same feature unless that split is genuinely useful.
+
+## Minimal API Guidance
+
+Prefer Minimal APIs when the surface is small to medium and you want concise endpoint definitions.
+
+Good defaults:
+
+- organize endpoints with route groups
+- keep route handlers thin
+- move business logic into services
+- prefer `TypedResults` over untyped results
+- use endpoint filters when cross-cutting behavior belongs at the endpoint layer
+- use built-in validation support on supported target frameworks
+
+Minimal API reminders:
+
+- handler parameters can be bound from route, query, headers, body, form, or DI
+- authorization can be applied with `RequireAuthorization`
+- return `IResult` or `TypedResults` when response shape matters
+- use OpenAPI support for discoverable contracts
+
+On .NET 10, Minimal APIs support built-in validation with `AddValidation()`. Use that instead of inventing parallel validation infrastructure when the target framework supports it.
+
+## Controller API Guidance
+
+Prefer controllers when the API needs:
+
+- `[ApiController]` behaviors
+- attribute routing and conventions
+- filters
+- custom formatters
+- mature controller organization in an existing codebase
+
+Controller defaults:
+
+- derive API controllers from `ControllerBase`
+- annotate with `[ApiController]`
+- use attribute routing
+- return ProblemDetails-compatible failures
+- let automatic model validation handle invalid requests unless there is a concrete override requirement
+
+Key `[ApiController]` behaviors:
+
+- attribute routing is required
+- invalid model state automatically becomes HTTP 400
+- binding source inference applies
+- error responses use ProblemDetails patterns
+
+## Shared API Practices
+
+- Keep request and response DTOs separate from persistence models
+- Use version-stable route and payload contracts
+- Use `CreatedAt...` patterns for resource creation
+- Prefer explicit status codes and typed results over implicit behavior
+- Apply authorization at the endpoint or controller boundary, not only inside service methods
+- Use `ProblemDetails` for errors instead of ad hoc JSON shapes
+
+## Browser-Facing Notes
+
+- Be careful with cookie-authenticated API endpoints and CORS
+- For browser-based form or file upload endpoints, account for antiforgery requirements
+- In ASP.NET Core 10, known API endpoints no longer use cookie-login redirects by default; rely on API-appropriate unauthorized responses instead
+
+## Native AOT
+
+Use `dotnet new webapiaot` only when native AOT is an explicit deployment requirement. Treat it as a constraint that affects library choice, reflection, JSON patterns, and compatibility.