# Dotnet Best Practices Repo

> Apply practical, repository-aligned .NET/C# engineering practices without forcing framework-specific or architecture-specific choices.

- Skill: `markheydon/dotnet-best-practices-repo` (Agent Skill)
- Install (CLI): `npx skillmds@latest add markheydon/dotnet-best-practices-repo`
- Raw SKILL.md: https://api.skillmd.com/api/skills/markheydon/dotnet-best-practices-repo/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: markheydon (https://skillmd.com/u/markheydon)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/markheydon/dotnet-best-practices-repo

---


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