dotnet-best-practices

# .NET/C# Best Practices (Neutral Baseline) Your goal is to help produce maintainable, production-ready .NET code while respecting the repository’s existing conventions and technology choices. ## Core Rule - Follow the repository’s established conventions first. - If conventions are unclear, prefer standard modern .NET practices. - Avoid introducing new frameworks, patterns, or architecture unless requested. ## Scope and Change Discipline - Keep changes focused and minimal for the requested outcome. - Reuse existing abstractions before creating new ones. - Do not change target framework, SDK version, or global project structure unless explicitly asked. - Do not edit generated files. ## API and Design - Use clear names and cohesive methods. - Prefer the least required visibility (`private` > `internal` > `protected` > `public`). - Validate inputs at boundaries. - Throw precise exceptions with actionable messages. - Prefer composition and simple designs over speculative abstractions. ## Async and Reliability - Use async for I/O-bound work end-to-end. - Avoid blocking async calls (`.Result`, `.Wait()`). - Propagate `CancellationToken` where appropriate. - Add timeouts and retries only where they are operationally justified. ## Configuration and Observability - Prefer strongly-typed configuration and validate required settings. - Use structured logging with useful context. - Avoid logging secrets or sensitive data. - Preserve existing telemetry/logging patterns in the repository. ## Security and Data Handling - Validate and sanitize untrusted input. - Use parameterized data access patterns. - Apply least-privilege principles for credentials and access. - Keep secrets out of source code and logs. ## Testing Guidance (Framework-Neutral) - Follow the testing framework already used by the solution. - Add or update tests for changed behaviour, especially public-facing behaviour. - Prefer deterministic tests that run independently. - Use clear Arrange-Act-Assert structure. - Mock only external dependencies when necessary. ## Documentation - Document non-obvious behaviour and important design decisions. - For public APIs, add or maintain XML docs where the repository expects them. - Keep comments focused on intent and rationale, not restating code. ## Performance - Prefer simple, readable implementations first. - Optimize only when justified by measured evidence. - Avoid unnecessary allocations in hot paths when practical. - Stream large payloads when possible instead of buffering entire content. ## Decision Priority When guidance conflicts, use this order: 1. User request 2. Repository conventions 3. This skill 4. General .NET defaults