/arch-check

name: arch-check
description: >
  Architecture conformance check: verifies an existing codebase against its
  declared architecture (VSA, Clean Architecture, DDD, Modular Monolith) —
  dependency direction, layer violations, module boundary leaks, and cycles —
  using token-cheap Roslyn MCP analysis. Invoke when: "check architecture",
  "architecture violations", "layer violations", "dependency direction",
  "module boundaries", "arch check", "is my architecture clean", "enforce
  architecture", "conformance check". For CHOOSING an architecture, use
  architecture-advisor instead.

/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 evidence

Pick 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

• `get_project_graph` — reference-direction audit (the backbone)
• `detect_circular_dependencies` — cycle detection
• `get_dependency_graph` / `find_references` — namespace-level leak probes
• `get_endpoint_map` — presentation boundary + auth posture
• `detect_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-monolith` template — 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