health-check（健康检查）

Health Check

Core Principles

1. Data-driven assessment — Use MCP tools for every dimension. get_diagnostics for build health, detect_antipatterns for code quality, detect_circular_dependencies for architecture, get_test_coverage_map for testing, find_dead_code for dead code. Gut feeling is not a grade.
2. Letter grades with justification — Every dimension gets A (90+), B (80+), C (70+), D (60+), or F (<60). Every grade includes the specific data points that produced it. "B in Code Quality" means nothing. "B in Code Quality: 3 anti-patterns in 2,400 lines (1.25 per 1K)" is actionable.
3. Actionable recommendations — Every grade below A comes with specific, prioritized fix suggestions. "Improve test coverage" is not actionable. "Add test classes for OrderService, PaymentProcessor, and ShippingCalculator (3 production types without tests)" is.
4. Comparative baselines — Grade against.NET best practices, not perfection. Zero warnings is aspirational. Fewer than 1 warning per 1K lines of code is excellent. Context matters.
5. Non-judgmental tone — Health checks are diagnostic, not punitive. A project with a C grade has a clear improvement path. Frame findings as opportunities, not failures.

Patterns

8-Dimension Health Assessment

Run all dimensions. Each uses specific MCP tools and produces a letter grade.

Dimension 1: Build Health

Tool: dotnet build --no-restore
Metric: Error count, warning count

Dimension 2: Code Quality

Tool: MCP detect_antipatterns(projectFilter: each project)
Metric: Anti-pattern count per 1K lines of code

Common anti-patterns detected: async void, sync-over-async, new HttpClient(), DateTime.Now, broad catch blocks, string interpolation in logging, missing CancellationToken.

Dimension 3: Architecture

Tool: MCP get_project_graph — check dependency direction
Tool: MCP detect_circular_dependencies(scope: "projects") — find cycles
Tool: MCP detect_circular_dependencies(scope: "types", projectFilter: each) — type-level cycles

Dimension 4: Test Coverage

Tool: MCP get_test_coverage_map(projectFilter: each production project)
Metric: Percentage of production types with corresponding test classes

Note: This is structural coverage (test class exists), not runtime line coverage. A test class existing does not guarantee thorough testing, but its absence guarantees none.

Dimension 5: Dead Code

Tool: MCP find_dead_code(scope: "solution", kind: "all", maxResults: 50)
Metric: Count of unused types, methods, and properties

Note: Some false positives are expected (reflection, DI conventions). Verify before penalizing.

Dimension 6: API Surface

Tool: MCP get_public_api(typeName: each public type) — review public API design
Tool: MCP find_references(symbolName: public members) — check for overexposed APIs

Check for:

• Services that should be internal but are public
• Methods returning Task instead of Task<Result<T>> for operations that can fail
• Inconsistent return types across similar endpoints (some TypedResults, some IResult)
• Public setters on types that should be immutable

Dimension 7: Security Posture

Tool: dotnet list package --vulnerable --include-transitive
Tool: MCP detect_antipatterns — filter for security-related patterns
Scan: Hardcoded secrets, connection strings in code, missing auth attributes

Dimension 8: Documentation

Scan: XML docs on public API types and methods
Check: README exists, is current, covers setup and architecture

Report Card Format

## Project Health Report

**Project:** MyApp | **Date:** 2026-03-04 | **Assessed by:** Claude (MCP-assisted)

### Grades

| Dimension | Grade | Score | Key Finding |
|-----------|-------|-------|-------------|
| Build Health | A | 95 | 0 errors, 2 pre-existing warnings |
| Code Quality | B | 82 | 3 anti-patterns in 4.2K lines |
| Architecture | A | 92 | Clean dependency direction, 0 circular deps |
| Test Coverage | C | 68 | 34/50 production types have test classes |
| Dead Code | B | 85 | 5 unused methods identified |
| API Surface | B | 80 | 2 overexposed service types |
| Security | A | 94 | 0 vulnerable packages, auth coverage complete |
| Documentation | D | 55 | 12/30 public APIs have XML docs |

### Overall GPA: 3.0 (B-)

### Priority Recommendations

1. **Test Coverage (C -> B):** Add test classes for these 16 untested types:
   - `OrderService`, `PaymentProcessor`, `ShippingCalculator` (critical path)
   - `EmailNotifier`, `InventoryChecker`, ... (supporting services)
   Estimated effort: 2-3 days

2. **Documentation (D -> C):** Add XML docs to public API types:
   - Start with the 8 controller/endpoint classes (user-facing APIs)
   - Then cover the 10 public service interfaces
   Estimated effort: 1 day

3. **Code Quality (B -> A):** Fix 3 anti-patterns:
   - `OrderService.cs:47` — Replace `DateTime.Now` with `TimeProvider.GetUtcNow()`
   - `PaymentClient.cs:23` — Replace `new HttpClient()` with `IHttpClientFactory`
   - `NotificationHandler.cs:12` — Replace `async void` with `async Task`
   Estimated effort: 1 hour

GPA Calculation

Convert letter grades to points: A=4.0, B=3.0, C=2.0, D=1.0, F=0.0 GPA = average of all 8 dimension scores.

Quick Health Check

For a rapid assessment, run dimensions 1-4 only:

QUICK HEALTH (4 dimensions):
1. Build Health — dotnet build
2. Code Quality — detect_antipatterns
3. Architecture — get_project_graph + detect_circular_dependencies
4. Test Coverage — get_test_coverage_map

Use when:
- Mid-sprint checkpoint
- Quick status before a demo
- Onboarding to an unfamiliar codebase
- After a major merge

Trend Tracking

If a previous health report exists, compare grades:

### Trend

| Dimension | Previous | Current | Change |
|-----------|----------|---------|--------|
| Build Health | B | A | Improved — fixed 4 warnings |
| Code Quality | C | B | Improved — resolved 7 anti-patterns |
| Test Coverage | C | C | No change — still 68% |
| Dead Code | B | B | No change |

Track trends to show progress over time. Improving grades validate cleanup efforts.

Anti-patterns

Grading Without MCP Tools

# BAD — gut-feeling assessment
"The code looks pretty clean, I'd give it a B overall."
# No data. No specific findings. No actionable recommendations.

# GOOD — MCP-driven assessment with data
MCP: detect_antipatterns → 3 findings
MCP: get_diagnostics → 2 warnings
MCP: get_test_coverage_map → 68% coverage
"Code Quality: B (3 anti-patterns in 4.2K lines = 0.71 per 1K).
 Specific anti-patterns: DateTime.Now in OrderService.cs:47, ..."

Only Checking Build Health

# BAD — build passes, ship it
"dotnet build succeeded with 0 errors. The project is healthy!"
# Misses: 12 anti-patterns, 3 circular dependencies, 30% test coverage, 2 CVEs

# GOOD — all 8 dimensions for a complete picture
Build passes, but Architecture is D (circular deps), Test Coverage is F (15%),
and Security is D (high-severity CVE). Overall GPA: 2.1 — Needs Work.

Inflated Grades

# BAD — grading on a curve to make the project look good
15 warnings → "That's pretty good for a project this size" → Grade: B
# Absolute standards exist for a reason

# GOOD — consistent grading against defined thresholds
15 warnings → Grade C (6-15 warnings bracket)
"15 warnings puts this in the C range. Here are the 5 highest-priority
 warnings to fix to reach B (under 6 warnings)."

Recommendations Without Specifics

# BAD — vague improvement suggestions
"Improve test coverage."
"Fix code quality issues."
"Address security concerns."

# GOOD — specific, prioritized, estimated
"Add test classes for OrderService, PaymentProcessor, ShippingCalculator.
 These are on the critical path and have 0 test coverage.
 Start with OrderService — it has the most complex logic.
 Estimated effort: 4 hours for all three."

Decision Guide