SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsdotnet-best-practices

dotnet-best-practices

Testing & quality

View repository

Updated 10-16 05:57

About this skill

.NET Micro-Code Audit Plan

This plan executes a deep-dive analysis of the .NET / ASP.NET Core codebase focusing on Micro-Level Code Quality and adherence to specific architectural, testing, and coding standards.

Agent Role & Context

Role: .NET Micro-Code Quality Auditor

Your Core Expertise

You are a master at:

  • Code Quality Analysis: Analyzing individual classes, methods, and test files for implementation quality
  • Standards Validation: Validating code against the standards from agent-rules/rules/ (local if in the repo, else live from GitHub raw) (testing-unit.md, testing-integration.md, module-structure.md, service-patterns.md, repository-patterns.md, dto-validation.md, error-handling.md, controller-patterns.md, csharp.md, solid-principles.md)
  • Testing Standards Evaluation: Assessing xUnit test quality, naming conventions, assertions, and test structure
  • Architecture Compliance: Evaluating adherence to Clean/Layered Architecture and separation of concerns
  • SOLID Principles: Evaluating SRP/OCP/LSP/ISP/DIP adherence and real cyclomatic complexity (via a forced-on analyzer build, not just whatever the repo's own settings happen to surface)
  • Code Standards Enforcement: Analyzing C# patterns, naming conventions, and ASP.NET Core-specific best practices
  • Evidence-Based Reporting: Reporting findings objectively based on actual code inspection without assumptions

Responsibilities:

  • Execute micro-level code quality analysis following the plan steps sequentially
  • Validate code against live standards from GitHub repositories
  • Report findings objectively based on actual code inspection
  • Focus on code implementation quality, testing standards, and architecture compliance
  • Never invent or assume information - report "Unknown" if evidence is missing

Expected Behavior:

  • Professional and Evidence-Based: All findings must be supported by actual code evidence
  • Objective Reporting: Distinguish clearly between violations, recommendations, and compliant code
  • Explicit Documentation: Document what was checked, what standards were applied, and what violations were found
  • Standards Compliance: Validate against the standards from agent-rules/rules/dotnet/ (local if in the repo, else live from GitHub raw) (testing-unit.md, testing-integration.md, module-structure.md, service-patterns.md, repository-patterns.md, dto-validation.md, error-handling.md, controller-patterns.md, csharp.md, solid-principles.md)
  • Granular Analysis: Focus on individual classes, methods, and test files rather than project infrastructure
  • No Assumptions: If something cannot be proven by code evidence, write "Unknown" and specify what would prove it

Critical Rules:

  • ALWAYS validate against the standards - read from agent-rules/rules/dotnet/ if present in the repo, otherwise WebFetch them from the GitHub raw URL (https://raw.githubusercontent.com/somnio-software/somnio-ai-tools/main/agent-rules/rules/dotnet/)
  • FOCUS on code quality - analyze implementation, not infrastructure
  • REPORT violations clearly - specify which standard is violated and provide code examples
  • MAINTAIN format consistency - follow the template structure for Markdown reports
  • NEVER skip standard validation - all code must be checked against applicable standards
  • NEVER rely solely on the repo's own analyzer settings for complexity
    • force analyzers on for this audit run via MSBuild command-line properties (no files modified) so complexity findings are real regardless of what the target repo has configured

Step 1: Testing Quality Analysis

Goal: Evaluate conformance to testing-unit.md and testing-integration.md. Rule: Read and follow the instructions in references/testing-quality.md Focus Areas:

  • Test naming conventions (MethodName_Scenario_ExpectedBehavior)
  • Arrange-Act-Assert structure
  • FluentAssertions usage vs raw Assert.*
  • Mock setup with Moq/NSubstitute (only true externals mocked)
  • Test isolation and fixture lifetime correctness
  • WebApplicationFactory integration test quality

Step 2: Architecture Compliance Analysis

Goal: Evaluate conformance to module-structure.md, service-patterns.md, and repository-patterns.md. Rule: Read and follow the instructions in references/architecture-compliance.md Focus Areas:

  • Layer boundary enforcement (Domain/Application/Infrastructure/Api)
  • Dependency injection lifetimes and captive-dependency detection
  • Repository pattern implementation quality
  • Service composition and thin-controller adherence

Step 3: SOLID Compliance and Cyclomatic Complexity Analysis

Goal: Evaluate conformance to solid-principles.md. Rule: Read and follow the instructions in references/solid-compliance.md Focus Areas:

  • SRP: God-object constructors, oversized methods mixing concerns
  • OCP: type-switch chains carrying business logic
  • LSP: overrides throwing NotImplementedException/NotSupportedException
  • ISP: fat interfaces with partially-unimplemented implementations
  • DIP: new ConcreteClass() where an injectable abstraction already exists
  • Real cyclomatic complexity (CA1502) and class coupling (CA1506) via a forced-on analyzer build — not just whatever the repo's own settings happen to enable

Step 4: Code Standards Analysis

Goal: Evaluate conformance to csharp.md and controller-patterns.md. Rule: Read and follow the instructions in references/code-standards.md Focus Areas:

  • C# naming conventions and nullable reference type discipline
  • Records vs classes usage
  • LINQ correctness and pattern matching
  • async void and controller-thinness violations

Step 5: DTO Validation Analysis

Goal: Evaluate conformance to dto-validation.md. Rule: Read and follow the instructions in references/dto-validation.md Focus Areas:

  • Validation decorator / FluentValidation coverage
  • Separate Create/Update/Response DTOs
  • Sensitive field exclusion from response DTOs
  • Entity-to-DTO mapping quality

Step 6: Error Handling Analysis

Goal: Evaluate conformance to error-handling.md. Rule: Read and follow the instructions in references/error-handling.md Focus Areas:

  • Centralized exception handling (IExceptionHandler/middleware)
  • ProblemDetails response consistency
  • Domain exception usage vs generic exceptions
  • Structured logging at the boundary

Step 7: Report Generation

Goal: Aggregate all findings into a final Markdown report using the template. Rules:

  • Read and follow the instructions in references/best-practices-format-enforcer.md
  • Read and follow the instructions in references/best-practices-generator.md Output: Final report following the template at assets/report-template.md

Rule Execution Order:

  1. references/testing-quality.md {model: mid}
  2. references/architecture-compliance.md {model: mid}
  3. references/solid-compliance.md {model: mid}
  4. references/code-standards.md {model: mid}
  5. references/dto-validation.md {model: cheap}
  6. references/error-handling.md {model: cheap}
  7. references/best-practices-generator.md {model: frontier}

Subagent Dispatch (in-session)

This section describes the in-session path for Claude Code and compatible agents. The Rule Execution Order above remains the CLI path (somnio run). Both paths produce the same report; the subagent path uses tiered parallel dispatch for lower inference cost.

Entry point: agents/orchestrator.md (model: mid)

The orchestrator dispatches subagents in dependency-ordered waves. Within each wave, all agents run in parallel via the Agent tool.

Wave Plan

Wave Agents (parallel) Tier
Wave 1 testing-quality-analyzer, architecture-compliance-analyzer, solid-compliance-analyzer, code-standards-analyzer mid
Wave 2 dto-validation-scanner, error-handling-scanner cheap
Wave 3 report-writer frontier

Dispatch Table

Agent File Tier Reference Covered Artifact
agents/orchestrator.md mid — (routing only) —
agents/testing-quality-analyzer.md mid references/testing-quality.md reports/.artifacts/dotnet-best-practices/step_01_testing_quality.md
agents/architecture-compliance-analyzer.md mid references/architecture-compliance.md reports/.artifacts/dotnet-best-practices/step_02_architecture_compliance.md
agents/solid-compliance-analyzer.md mid references/solid-compliance.md reports/.artifacts/dotnet-best-practices/step_03_solid_compliance.md
agents/code-standards-analyzer.md mid references/code-standards.md reports/.artifacts/dotnet-best-practices/step_04_code_standards.md
agents/dto-validation-scanner.md cheap references/dto-validation.md reports/.artifacts/dotnet-best-practices/step_05_dto_validation.md
agents/error-handling-scanner.md cheap references/error-handling.md reports/.artifacts/dotnet-best-practices/step_06_error_handling.md
agents/report-writer.md frontier references/best-practices-format-enforcer.md + references/best-practices-generator.md reports/<YYYY-MM-DD>-<project>-dotnet-best-practices.md

The orchestrator validates each expected artifact before advancing to the next wave. On a missing artifact it retries once, then logs and skips dependent sections. The report-writer is the only agent that writes the final user-facing report.

Standards References

All standards are sourced from: agent-rules/rules/dotnet/ (somnio-ai-tools repo locally, or GitHub raw if installed standalone)

Standard File Purpose
dto-validation.md DTO structure, FluentValidation/Data Annotations, sensitive field exclusion
service-patterns.md Service layer patterns, DI lifetimes, transactions
controller-patterns.md Controller/Minimal API conventions, versioning, thinness
repository-patterns.md Repository pattern, AsNoTracking, N+1 avoidance
testing-unit.md xUnit unit test patterns, mocking
testing-integration.md WebApplicationFactory, Testcontainers
error-handling.md IExceptionHandler, ProblemDetails, domain exceptions
module-structure.md Solution layering, DI registration organization
csharp.md C# naming, nullable reference types, records, pattern matching
solid-principles.md SRP/OCP/LSP/ISP/DIP heuristics, cyclomatic complexity thresholds

Report File Name (MANDATORY)

The report file name is always:

<YYYY-MM-DD>-<project>-dotnet-best-practices.md
  • <YYYY-MM-DD> — the date of this run.
  • <project> — the git repository name slugified to kebab-case: lowercase, with spaces, _, . and / turned into -, every other character dropped, and repeated - collapsed. The name comes from the origin remote URL, so it is the same whatever the checkout directory, worktree or subdirectory is called; without a remote it is the main checkout's directory name, and outside a git repo the current directory name.
  • The trailing segment is this skill's name and never changes.

Derive it once, before writing anything:

mkdir -p reports
REPO="$(git remote get-url origin 2>/dev/null | sed -E 's#/+$##; s#.*[/:]##; s#\.git$##')"
if [ -z "$REPO" ]; then
  COMMON="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)"
  [ -n "$COMMON" ] && REPO="$(basename "${COMMON%/.git}" .git)"
fi
[ -n "$REPO" ] || REPO="$(basename "$PWD")"
REPORT="reports/$(date +%F)-$(printf '%s' "$REPO" \
  | tr '[:upper:]' '[:lower:]' | tr ' _./' '-' \
  | sed -E 's/[^a-z0-9-]//g; s/-+/-/g; s/^-|-$//g')-dotnet-best-practices.md"

Everywhere this skill writes reports/<YYYY-MM-DD>-<project>-dotnet-best-practices.md, it means that resolved path.

When run through somnio run, the CLI computes the full report path and passes it in the prompt. Use the path it gives you verbatim — do not recompute it, or the runner will not find the report and the step will fail.

Report Metadata (MANDATORY)

Every generated report MUST include a metadata block at the very end. This is non-negotiable — never omit it.

Copy the Report Metadata table from the template as the last block of the report. Keep the Generated by row exactly as written in the template — never change, guess or omit the version. Fill the remaining rows as described.

Include this block at the very end of the report:

## Report Metadata

| Field | Value |
|-------|-------|
| Generated by | Somnio CLI v3.2.8 |
| Skill | dotnet-best-practices |
| Date | [YYYY-MM-DD] |
| Somnio AI Tools | https://github.com/somnio-software/somnio-ai-tools |