arch-check

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

验证代码是否仍符合其宣称采用的架构。架构会因一个个看似合理的微小变更而逐渐腐化——比如Domain项目引入了EF Core引用，某个模块访问了兄弟模块的内部实现，或者端点定义在了宿主项目之外。本工作流通过项目图和依赖分析来识别这些腐化问题，无需逐文件读取代码。

输出结果：一份包含严重程度、文件:行证据及具体修复方案的违规报告，或者显示架构完全合规。

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
```

触发指令："check my architecture"、"are there layer violations"、"dependency direction"
发布版本前或大型功能开发完成后
加入一个宣称采用特定架构的陌生代码库后
多人向共享模块提交代码的团队中定期执行
不适用场景：选择架构——该场景请使用
```
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.

步骤1：确定声明的架构基准

优先级顺序：项目的CLAUDE.md文件、

docs/decisions/

目录下的ADR文档，或询问用户。切勿自行推断——错误的基准会导致错误的报告。支持的四种架构基准及其规则：

架构类型	检查规则
Vertical Slice	功能模块不得引用兄弟功能模块；仅通过明确的共享文件夹/项目使用共享代码
Clean Architecture	Domain层→无依赖；Application层→仅依赖Domain层；Infrastructure层→依赖Application层；Api层→依赖Application层（禁止Api层直接引用Infrastructure层的类型，仅可进行 wiring 操作）
DDD + Clean	遵循Clean Architecture规则 + 聚合仅通过根节点引用；跨聚合操作需通过领域事件实现
Modular Monolith	模块之间除 `*.Contracts` 外不得有项目引用；跨模块调用需通过集成事件或契约实现

步骤2：项目级依赖方向检查（成本最低，覆盖大多数问题）

get_project_graph()

将每个项目引用与基准允许的依赖方向进行比对。此处出现的任何错误引用（如Domain层→Infrastructure层）均为CRITICAL级问题——这会导致后续所有下游违规问题的发生。

步骤3：循环依赖检查

detect_circular_dependencies()

循环依赖在所有架构基准中均属于违规情况。需报告完整的循环链。

步骤4：命名空间级泄露检查（抽样检查）

项目引用可能合规，但代码仍存在泄露情况。需针对风险点进行探查：

get_dependency_graph(symbolName: <a Domain entity>, depth: 2)
   -- Domain层类型是否引入了EF Core、HttpClient或Infrastructure层命名空间？
find_references(symbolName: <a module-internal type>)
   -- 是否被模块外部引用？
detect_antipatterns()
   -- 检测已知的结构坏味道作为辅助证据

根据架构基准选择探查对象：Clean Architecture→抽样3-5个Domain层实体和Application层处理器；Modular Monolith→抽样每个模块的内部类型；VSA→抽样两个或三个功能文件夹内的类型。

步骤5：展示层边界检查

get_endpoint_map()

端点必须仅存在于宿主/Api层（Clean Architecture）或所属模块内部（Modular Monolith、VSA功能文件夹）。在Application层或共享项目中定义端点属于边界违规。任何未标记权限的端点会作为附带问题报告（如需深入检查，请使用

/security-scan

）。

步骤6：生成报告

严重程度	含义
CRITICAL	错误方向的项目引用、模块间直接引用、循环依赖
HIGH	命名空间泄露（Domain层使用Infrastructure/EF类型）、端点不在指定层级
MEDIUM	共享内核逻辑蔓延、绕过聚合根直接访问成员
INFO	未标记权限的端点、检测到的值得关注的坏味道

每个问题项需包含：证据（文件:行）、违反基准的原因及修复方案（迁移代码、通过接口反转依赖、引入契约项目、发起集成事件）。可主动提出立即修复CRITICAL级问题。

MCP Tools Used

使用的MCP工具

```
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

```
get_project_graph
```
—— 引用方向审计（核心工具）
```
detect_circular_dependencies
```
—— 循环依赖检测
```
get_dependency_graph
```
/
```
find_references
```
—— 命名空间级泄露探查
```
get_endpoint_map
```
—— 展示层边界检查 + 权限状态
```
detect_antipatterns
```
—— 结构坏味道辅助证据

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?

用户: /arch-check

Claude: 从CLAUDE.md获取基准：Clean Architecture（4个项目）。

  项目图分析（get_project_graph）...
  CRITICAL  Domain → Infrastructure引用（Domain.csproj:14）
            违反依赖规则；导致Domain层无法独立测试。
            修复方案：反转依赖——在Application层定义IEmailSender，在Infrastructure层实现。
  循环依赖检测（detect_circular_dependencies）... 无。
  对4个Domain层实体进行泄露探查...
  HIGH      Order.cs:8 使用了Microsoft.EntityFrameworkCore（Domain层必须与持久化无关）。修复方案：将[Index]配置迁移至Infrastructure层的OrderConfiguration中。
  端点映射分析... 共23个端点，全部位于Api层。其中2个未标记权限（附带问题——请运行/security-scan）。

  结论：架构不符合要求——1个CRITICAL级问题，1个HIGH级问题。请优先修复引用问题；需要我立即执行修复吗？

arch-check

Original

Translation

/arch-check

/arch-check

What

功能

When

适用场景

How

执行步骤

MCP Tools Used

使用的MCP工具

Example

示例

Related

相关工具