SKILL.md
/arch-check
What
Verifies that the code still matches the architecture it claims to have. Architectures rot through small, individually-reasonable changes — a Domain project that gains an EF Core reference, a module that reaches into a sibling's internals, an endpoint defined outside the host. This workflow catches the rot using project-graph and dependency analysis, not file-by-file reading.
Output: a violation report with severity, file:line evidence, and the concrete fix — or a clean conformance pass.
When
- "check my architecture", "are there layer violations", "dependency direction"
- Before a release or after a large feature lands
- After onboarding to an unfamiliar codebase that claims an architecture
- Recurring on teams where multiple people merge to shared modules
- NOT for choosing an architecture — that is
architecture-advisor
How
Step 1: Establish the declared architecture
In order of authority: the project's CLAUDE.md, an ADR in docs/decisions/, or ask the user. Never infer silently — a wrong baseline produces a wrong report. The four supported baselines and their rules:
| Architecture | Rules checked |
|---|---|
| Vertical Slice | Features don't reference sibling features; shared code only via explicitly shared folders/projects |
| Clean Architecture | Domain → nothing; Application → Domain only; Infrastructure → Application; Api → Application (never Api → Infrastructure types, wiring only) |
| DDD + Clean | Clean rules + aggregates referenced only via roots; domain events for cross-aggregate effects |
| Modular Monolith | No project references between modules except *.Contracts; cross-module calls via integration events or contracts |
Step 2: Project-level dependency direction (cheapest, catches most)
get_project_graph()Map every project reference against the baseline's allowed arrows. A single wrong reference here (Domain → Infrastructure) is a CRITICAL finding — it makes every downstream violation possible.
Step 3: Cycles
detect_circular_dependencies()Cycles are violations in every baseline. Report the full chain.
Step 4: Namespace-level leaks (spot checks)
Project references can be clean while code still leaks. Probe the risky edges:
get_dependency_graph(symbolName: <a Domain entity>, depth: 2)
-- Domain types pulling in EF Core, HttpClient, or Infrastructure namespaces?
find_references(symbolName: <a module-internal type>)
-- referenced from outside its module?
detect_antipatterns()
-- known structural smells as supporting evidencePick probes by baseline: Clean → sample 3-5 Domain entities and Application handlers; Modular Monolith → sample each module's internal types; VSA → sample types inside two or three feature folders.
Step 5: Presentation boundary
get_endpoint_map()Endpoints must live only in the host/Api layer (Clean) or inside their owning module (Modular Monolith, VSA feature folders). An endpoint defined in an Application or shared project is a boundary violation. Unmarked auth on any endpoint is reported as a side-finding (route to /security-scan for depth).
Step 6: Report
| Severity | Meaning |
|---|---|
| CRITICAL | Wrong-direction project reference, module-to-module reference, cycle |
| HIGH | Namespace leak (Domain using Infrastructure/EF types), endpoint outside its layer |
| MEDIUM | Shared-kernel logic creep, aggregate bypassed via direct member access |
| INFO | Unmarked endpoint auth, antipattern hits worth a look |
Each finding: evidence (file:line), why it violates the baseline, and the fix (move the code, invert with an interface, introduce a contracts project, raise an integration event). Offer to fix CRITICAL items immediately.
MCP Tools Used
getprojectgraph— reference-direction audit (the backbone)detectcirculardependencies— cycle detectiongetdependencygraph/find_references— namespace-level leak probesgetendpointmap— presentation boundary + auth posturedetect_antipatterns— supporting structural evidence
Example
User: /arch-check
Claude: Baseline from CLAUDE.md: Clean Architecture (4 projects).
Project graph (get_project_graph)...
CRITICAL Domain → Infrastructure reference (Domain.csproj:14)
Breaks the dependency rule; makes Domain untestable in isolation.
Fix: invert — define IEmailSender in Application, implement in
Infrastructure.
Cycles (detect_circular_dependencies)... none.
Leak probes on 4 Domain entities...
HIGH Order.cs:8 uses Microsoft.EntityFrameworkCore (Domain must stay
persistence-ignorant). Fix: move the [Index] config to
OrderConfiguration in Infrastructure.
Endpoint map... 23 endpoints, all in Api. 2 unmarked auth (side-finding —
run /security-scan).
Verdict: NOT conformant — 1 critical, 1 high. Fix the reference first;
want me to do it now?Related
architecture-advisor— choosing a baseline (before this skill is useful)clean-architecture,vertical-slice,ddd,modular-monolithtemplate — the rules being enforced/security-scan— depth on the auth side-findings/health-check— broader report card; arch-check is its architecture dimension in depth