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、实质影响、证据，否则不报。
• 平衡理想与现实：考虑团队现状和项目阶段，不要拿理想架构碾压可用代码。