Arch Check

---
name: arch-check
description: >-
  架构与实现审查 —— 基于「概念建模 → 职责划分 → 机制/策略分离 → 因果与不变量 → 属性建模 → 模块化 → SOLID → GRASP → YAGNI」的全维度审查，带置信度门控与假阳性抑制（对抗"过度工程建议"这类 AI slop）。触发于：要求 review/审查架构、检查目录结构/依赖关系/职责划分、重构前评估、技术债盘点、判断是否过度设计，或问「这个设计合理吗 / 该怎么拆 / 有没有循环依赖 / 这个改动架构上 OK 吗」。一律按最高强度审查。用法：`arch-check [范围] [--fix|--plan]`。范围可为目录/文件/PR；缺省审当前分支相对基线的全部变更。
---

# Arch Check —— 架构与实现审查

把架构审查做成与代码审查相同的**操作流程**，而不是一份让人逐条挑刺的清单。核心纪律：**只报有把握、有实质影响的问题；架构审查最常见的失败是"建议加更多抽象"——这本身就是要被滤掉的 AI slop。**

## 调用解析

从用户输入里解析两件事（缺省值见下）：

- **范围 (scope)**：目录 / 文件 / PR 号 / 「当前分支变更」。
- **动作**：缺省出报告；`--plan` 出可勾选的重构任务清单；`--fix` 直接应用低风险重构。

**强度恒定**：始终按最高强度审——全部 lens（A–E）、fan-out 并行子 agent、依赖图/环检测、对每条 finding 做对抗式复核。不存在"轻审"模式。

## 两种作用域模式

| 模式 | 何时用 | 审什么 |
|---|---|---|
| **diff（分支变更）** | 在 git 仓库里且用户没给路径 | **当前分支相对基线的全部变更**的架构影响：新概念是否放对位置、职责归属、是否引入新耦合/环、是否把策略硬编码进机制、是否破坏既有不变量 |
| **audit（全量）** | 用户给了目录/文件/模块，或明确要"审整个 X" | 该范围的**完整架构体检**（下方全部维度） |

**diff 范围 = 当前分支相对基线的所有变更**（不是只看未提交的）。取变更集：
```
BASE=$(git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD main 2>/dev/null || git merge-base HEAD master)
git diff --stat $BASE...HEAD          # 已提交的分支变更
git diff --stat                       # 叠加未提交的工作区改动
git diff $BASE...HEAD                 # 完整 diff
```
基线优先级：`origin/main` → `main` → `master` →（都没有则问用户或退回 `HEAD~N`）。在 base/main 分支本身上、无分叉时，退回审未提交改动；仍为空则提示无变更可审。

缺省判定：给了路径 → audit；没给路径、在 git 仓库 → diff（当前分支全部变更）；不在仓库且没给路径 → 询问要审的范围。

## 审查 lens（对应 references/，按需加载——不要一次性全读）

审查时**只读当前 lens 对应的 reference 文件**，不要把全部 reference 一次性读进上下文。

| Lens | 关注 | Reference |
|---|---|---|
| **A. 概念建模** | 概念识别/命名、抽象质量、封装、实体关系 | `references/concept-modeling.md` |
| **B. 职责与因果** | 职责划分、机制/策略分离、因果与不变量、属性三分(identity/value/derived) | `references/responsibility-causality.md` |
| **C. 结构与依赖** | 目录结构、模块化、依赖方向、循环依赖 | `references/structure-modularity.md` |
| **D. 经典原则** | SOLID、GRASP、YAGNI | `references/solid-grasp-yagni.md` |
| **E. 时间/churn** | 共变更耦合、变更热点（上帝文件）、不稳定抽象（仅 git 仓库） | `references/cochange-churn.md` |

优先级（冲突/取舍时的让步顺序，**前者压过后者**）：
`概念正确性 > 职责归属 > 因果与不变量 > 属性建模 > 依赖方向/环 > 模块内聚 > 文件大小/命名风格`
（Lens E 的发现不单独成档，归并到它指向的问题：共变更→概念边界/耦合，热点→职责过载，不稳定抽象→依赖方向。）

## 接地原则（反幻觉，最高优先）

**结构性断言必须先 grep 再下结论，并在 finding 里附 `file:line` 证据；写不出证据 = 幻觉，不报（置信度封顶 25）。** 适用于：依赖/跨层、循环依赖、single-writer/多写者、概念散落、derived 无 invalidation、上帝文件、职责扩散。各语言的依赖/环/写入点探测命令见 `references/evidence-and-detection.md`。

## 工作流程

被显式调用即视为值得审，直接开审，不做"值不值得"的门控。

1. **采集上下文 + 接地**：读取范围内的 `AGENTS.md`、`CLAUDE.md` 或仓库提供的等价指令文件（仅记录路径与要点）、列出范围内文件；用 `references/evidence-and-detection.md` 里的命令**实跑**依赖/环检测、写入点定位、文件体量。优先用真实工具输出，别凭空想象结构。
2. **（仅 audit + 大范围）map-first 分诊**：先建模块地图，按"最大 / in-degree 最高 / churn 最高"挑出热点，**只对热点深挖全 lens**，其余轻扫。避免在大仓库里平均用力淹死。
3. **按 lens 审查**：走全部 lens A–E（E 仅 git 仓库），按优先级顺序，按需加载对应 reference。**每个 lens 派一个并行子 agent**，各自返回 findings；并发槽不足时分批 fan-out，保持每个 lens 的上下文独立，不得因此跳过 lens。
4. **置信度评分 + 复核**：对每条 finding 用下方 0–100 细则打分，**滤掉 < 80 分的**（无证据的结构性断言封顶 25，自动出局）。**每条再派独立子 agent 对抗式复核**（默认倾向"假阳性"）；并发不足时分批复核。
5. **排序**：按 `严重度 × 置信度` 排序。没有过线 finding 就如实说"未发现实质架构问题"。
6. **产出**：见「输出」。

## 置信度评分细则（逐条打分，给子 agent 时原样传递）

- **0 — 毫无把握**：经不起推敲的假阳性，或是范围外/改动未触及的既有结构。
- **25 — 略有把握**：可能是真问题，但无法验证；或是纯风格偏好、团队并未要求的"理想模式"。
- **50 — 中等把握**：已确认是真问题，但相对整个范围不重要，或很少在实践中触发。
- **75 — 较高把握**：已复核，很可能在实践中造成可维护性/正确性损害；现有结构确实不足。
- **100 — 完全确定**：已复核并有直接证据，必然造成问题（如确凿的循环依赖、多写者破坏不变量、概念被实现散落到多处导致改一处漏三处）。

**只保留 ≥ 80 分。**

## 严重度定义（决定 🔴/🟡/🟢，与置信度正交）

置信度回答"是不是真的"，严重度回答"有多要紧"——两者独立。

- **🔴 严重**：会造成 bug（多写者/竞态/derived 读旧值/破坏不变量），或**挡住已知的下一步改动**，或正在扩散（concept 已散落多处、churn 热点持续恶化）。
- **🟡 建议**：拖慢开发的摩擦——耦合偏高、职责轻微错位、目录与依赖不一致，但暂不致命。
- **🟢 打磨**：锦上添花，命名/小重构，不修也能正常演进。

## 假阳性清单（架构审查专属——这些一律不报）

- **「再加一层抽象会更好」**：没有 ≥2 个真实实现/真实变化点的抽象建议 = YAGNI 违规，**不报**。
- **命名洁癖**：不会造成真实歧义的改名建议。
- **团队没要求的"理想架构"**：把 DDD/六边形/Clean 架构强加到一个并不需要的项目上。
- **pre-existing**：diff 模式下，问题在用户没改的行/模块里。
- **linter/编译器/类型检查能抓的**：import、类型、格式。
- **风格偏好冒充架构问题**：除非造成耦合/职责/不变量的实质损害。
- **资深工程师不会拎出来说的吹毛求疵。**
- **看着像问题但其实是有意为之**、且与本次改动方向一致的设计选择。

## 输出

**默认（报告）**：简短、引用 `file:line`、按严重度分组。不要堆砌通过项；聚焦真问题 + 可操作修复。范围较大或用户要"完整报告"时用 `references/report-format.md` 的大模板；范围小用下面的精简格式即可。

精简版格式：
```
## 架构审查（<范围>）

发现 N 个问题（已滤除 <M> 个低置信/假阳性）：

🔴 严重
1. <一句话问题> — `path/to/file.ts:120`
   影响：<对可维护性/扩展性/正确性的实质影响>
   证据：<关键 file:line 或工具输出片段，可一键核对>
   修复：<具体步骤>

🟡 建议
2. ...

✅ 健康：<一句话说哪些维度是好的，可选>
```

**`--plan`**：把上面每条 finding 转成可勾选的重构任务清单（使用当前客户端可用的任务或清单机制；不可用时输出 Markdown checklist），按 Phase（概念澄清 → 结构重组 → 依赖治理）分组，标工作量 S/M/L。

**`--fix`**：仅对 🟢/🟡 中**低风险、机械、不改公共契约**的项直接改（如改名、移动文件归位、提取明显的策略参数）。🔴 概念/职责级重构**不自动改**——这类需要人确认设计意图，只在报告里给方案。改完逐条说明改了什么。

## 重要提示

- **先 grep 再下结论**：结构性断言（依赖/环/写入点/概念散落）必须有真实代码证据，否则是幻觉，不报。
- **概念优先于结构**：先问"概念识别对不对"，再谈文件怎么放。
- **过度工程 = YAGNI 同样危险**：审查者的天职不是推销抽象。建议加抽象前先证明有 ≥2 个真实变化点。
- **每条 finding 必须带 `file:line`、实质影响、证据**，否则不报。
- **平衡理想与现实**：考虑团队现状和项目阶段，不要拿理想架构碾压可用代码。