dotnet-boundaries

name	dotnet:boundaries
description	Analyze project/namespace boundaries, detect circular refs and layering violations via dotnet-depends and solution graph. Use before major refactors or to validate Clean Architecture.
argument-hint	<optional: project name or path>
effort	medium

boundaries

Inspect and validate module boundaries in a .NET solution — project references, namespace layering, and dependency direction.

What to Check

1. Project references in .csproj — who depends on what
2. Namespace traffic — using statements crossing layer boundaries (UI → Infrastructure, Domain → Infrastructure, etc.)
3. Circular references — EF/DI containers mask these
4. Public API surface — internal vs public leakage across assembly lines
5. InternalsVisibleTo — should be test-only, rarely prod

Flow

1. Parse all .csproj files for <ProjectReference> + package refs
2. Build dependency DAG; flag cycles
3. Grep using in each project; check against layering rules:
   • Domain/Core → must NOT reference Infrastructure, UI, Web
   • Application → MAY reference Domain; MUST NOT reference UI, Web
   • Infrastructure → MAY reference Domain, Application
   • Web/UI → MAY reference Application + Domain; MUST NOT reference Infrastructure internals directly (use Application interfaces)
4. Report boundary violations with file:line + offending using
5. Suggest refactor direction (interface extraction, DI inversion, moved types)

Iron Laws

• Don't fix a boundary violation by making an internal type public (that's spreading, not fixing)
• Don't introduce a new project just to satisfy the analyzer — ensure cohesion is real
• Preserve Iron Laws — refactor must not break async, disposal, or auth guarantees

Tools

# Dependency listing
dotnet list reference
dotnet list package --format json

# Solution graph (if installed)
dotnet-depends -p src/MyApp.sln

# Namespace scan
rg "^using [A-Z][^;]*;" --type cs -o | sort | uniq -c | sort -rn

Layering Rules (Clean Architecture default)

┌─────────────────────────┐
│  Presentation / Web     │ ─┐
├─────────────────────────┤  │
│  Application (UseCases) │  │ references flow downward
├─────────────────────────┤  │
│  Domain (Entities)      │ <┘ (Domain depends on nothing)
├─────────────────────────┤
│  Infrastructure         │ references Domain + Application
└─────────────────────────┘

Customize via .claude/boundaries.yml if project uses different layering (Vertical Slice, Hexagonal, etc.).

Output

.claude/audit/boundaries.md:

# Boundary Report

## Violations

### 1. Domain → Infrastructure
- src/MyApp.Domain/Entities/User.cs:3
- `using MyApp.Infrastructure.Email;`
- Fix: inject an `IEmailService` abstraction in Domain, implement in
  Infrastructure

## Cycles

### 1. MyApp.Api ↔ MyApp.Application
- Api → Application (controller uses use-case)
- Application → Api (injects `HttpContext` for tenant resolution)
- Fix: introduce `ITenantContext` in Application; implement in Api

Integration

/dotnet:boundaries → .claude/audit/boundaries.md
        ↓
/dotnet:plan "Fix boundary violations"
        ↓
/dotnet:work

References

• ${CLAUDE_SKILL_DIR}/references/clean-architecture.md — layering rules + common refactors
• ${CLAUDE_SKILL_DIR}/references/cycle-breaking.md — DI inversion, interface extraction, events
• ${CLAUDE_SKILL_DIR}/references/namespace-hygiene.md — internal vs public, InternalsVisibleTo policy

Anti-patterns

• "Fix" by making types public (spreads coupling)
• Flagging every cross-layer using without context (some are intentional)
• Ignoring cycles ("they work at runtime") — they mask compile-time signals