MyAiConfiguration/shared/rules/csharp.md

# C# Code Guidelines

* Write clear, readable, maintainable code first.
* Optimize only based on measurements and profiling.
* Prefer simple solutions over clever abstractions.
* Follow current C# and .NET conventions.
* Prefer immutable data where practical.
* Keep methods small and focused.
* Keep classes focused on a single responsibility.
* Avoid unnecessary inheritance.
* Prefer composition over inheritance.
* Use `sealed` when inheritance is not intended.
* Avoid unnecessary abstractions and wrapper layers.
* Avoid premature generalization.
* Prefer explicit code over hidden magic.
* Avoid unnecessary reflection.
* Avoid unnecessary runtime type checks.
* Avoid unnecessary allocations in hot paths.
* Avoid unnecessary collection copies.
* Avoid unnecessary string allocations.
* Avoid unnecessary LINQ in performance-critical paths.
* Use LINQ where it improves readability and performance is irrelevant.
* Choose collections based on access patterns.
* Preallocate collection capacity when the expected size is known.
* Avoid large mutable structs.
* Use `Span<T>` and related APIs only when they provide a measurable benefit.
* Prefer `Task` over `ValueTask` unless `ValueTask` is justified by profiling.
* Use async only for genuinely asynchronous operations.
* Keep async code async throughout the call chain.
* Avoid `.Result`, `.Wait()` and synchronous blocking of async operations.
* Propagate `CancellationToken` through asynchronous APIs.
* Do not create unnecessary background tasks.
* Limit concurrency when processing large workloads.
* Avoid uncontrolled `Task.WhenAll` over large collections.
* Avoid exceptions for normal control flow.
* Fail fast on invalid arguments and invalid state.
* Avoid swallowing exceptions.
* Preserve meaningful exception context.
* Use dependency injection where dependencies require substitution or lifecycle management.
* Avoid service locator patterns.
* Avoid excessive constructor dependencies.
* Keep application, domain and infrastructure concerns separated.
* Avoid unnecessary cross-layer coupling.
* Prefer explicit dependencies.
* Minimize global and static mutable state.
* Design APIs with clear contracts.
* Prefer strongly typed models over loosely typed dictionaries or dynamic objects.
* Validate input at system boundaries.
* Avoid duplicate validation deep inside trusted internal code.
* Treat external input as untrusted.
* Do not expose internal implementation details through public APIs.
* Avoid leaking sensitive information through logs or exceptions.
* Use structured logging.
* Avoid excessive logging in hot paths.
* Avoid logging sensitive data.
* Prefer database-side filtering, projection and aggregation.
* Do not load data that is not needed.
* Avoid N+1 database queries.
* Use no-tracking queries for read-only EF Core operations where appropriate.
* Keep database round trips minimal.
* Avoid unnecessary serialization and deserialization.
* Reuse expensive resources such as HTTP clients and database infrastructure correctly.
* Do not optimize micro-level CPU operations before fixing architectural, database or I/O bottlenecks.
* Prefer algorithms and data structures with appropriate complexity.
* Measure allocations, GC pressure, CPU usage and latency when investigating performance.
* Write code that is easy to test.
* Avoid tests coupled to implementation details.
* Prefer deterministic behavior.
* Avoid hidden side effects.
* Keep naming consistent and descriptive.
* Avoid abbreviations unless they are established domain terminology.
* Remove dead code instead of keeping it as commented-out code.
* Do not add comments or API documentation unless the user explicitly requests them.
* Follow existing project conventions unless there is a strong reason to change them.
* Do not introduce new libraries when the BCL or existing dependencies already solve the problem adequately.
* Prefer fewer dependencies.
* Keep dependency versions current and supported.
* Treat warnings seriously.
* Do not suppress analyzers without a concrete reason.
* Keep performance improvements readable unless the hot path clearly justifies additional complexity.
* Prefer correctness, maintainability and predictable behavior over theoretical micro-optimizations.

## C# Style & Safety

* Prefer modern, readable C# syntax and current .NET conventions.
* Prefer simple, explicit code over outdated or unnecessarily verbose patterns.
* Prefer concrete collection types for parameters, properties and local APIs when no abstraction is required.
* Avoid interface collection types such as `IDictionary<TKey, TValue>`, `IList<T>` or `ICollection<T>` unless polymorphism or API abstraction is actually needed.
* Prefer `Dictionary<TKey, TValue>`, `List<T>`, arrays or other concrete types when the implementation type is known and intentional.
* Prefer strongly typed models over `object`, `dynamic`, loosely typed dictionaries or string-based contracts.
* Validate external input at system boundaries.
* Fail fast on invalid arguments and impossible states.
* Avoid unsafe code unless explicitly required.
* Avoid reflection when a strongly typed solution is practical.
* Avoid hidden side effects and implicit global state.
* Prefer immutable or readonly data where practical.
* Avoid exposing mutable internal collections directly.
* Prefer safe framework APIs over custom low-level implementations.
* Never weaken validation, authorization, certificate checks, encryption or other security controls for convenience.
* Do not log secrets, tokens, credentials or sensitive data.
* Treat all external data as untrusted.
* Prefer correctness and security over minor convenience or micro-optimizations.

## Performance Priority

Prioritize performance work in this order:

* Architecture
* Database access
* Network and I/O
* Algorithms and data structures
* Concurrency
* Allocations and GC pressure
* CPU micro-optimizations

Never optimize based purely on assumptions.