需要扫描代码库发现架构深化机会时：识别浅模块并产出可视化重构…

适用于想系统发现并讨论代码库架构深化机会、且能运行 AI 技能/子代理与查看 HTML 报告的场景。

适用场景

解决思路

1. 先调用 Skill tool 的「codebase-design」获取架构词汇：module、interface、depth、seam、adapter、leverage、locality，以及其原则（deletion test、「the interface is the test surface」、「one adapter = hypothetical seam, two = real」）。
2. 在每条建议中严格使用上述术语，不要漂移到「component」「service」「API」「boundary」。
3. 用 `CONTEXT.md` 中的领域语言命名好的 seam；用 `docs/adr/` 中的 ADR 记录那些本命令不应重新争论的决策。
4. 扫描前先限定范围：遵循 YAGNI；因为深化模块的回报来自让未来修改更容易，所以要额外重视最近变更过的代码区域。
5. 在开始看之前决定「看哪里」：如果用户指定了方向（某个 module、子系统、痛点），采用它，并跳过下面的推断。
6. 否则回看足够长的提交历史（`git log --oneline`），找出代码库热点、反复出现的文件和区域，让这些路径优先吸引注意力。
7. 如果变更很分散、没有明显热点，则扩大搜索范围。
8. 先阅读项目领域词汇表（`CONTEXT.md`）和你要触碰区域的任何 ADR。
9. 然后启动 sub-agent 遍历代码库；不要遵循僵硬启发式，要有机探索并记录你在哪里感到摩擦。
10. 记录：理解一个概念是否需要在许多小 module 之间来回跳转？
11. 记录：哪些 module 是 shallow 的，interface 几乎和实现一样复杂？
12. 记录：哪些地方只是为了可测试性抽出了纯函数，但真正的 bug 藏在调用方式里（缺少 locality）？
13. 记录：哪些紧耦合 module 跨 seam 泄漏？
14. 记录：代码库哪些部分未测试，或通过当前 interface 很难测试？
15. 对任何疑似 shallow 的东西应用 deletion test：删除它会集中复杂度，还是只是移动复杂度？答案是「会集中」才是想要的信号。
16. 把候选写入自包含 HTML 文件，放到操作系统临时目录，避免落入仓库。
17. 从 `$TMPDIR` 解析临时目录，失败则用 `/tmp`（Windows 用 `%TEMP%`），写入 `<tmpdir>/architecture-review-<timestamp>.html`，确保每次运行都有新文件。
18. 为用户打开它（Linux 用 `xdg-open <path>`，macOS 用 `open <path>`，Windows 用 `start <path>`），并告诉用户绝对路径。
19. 报告用 Tailwind via CDN 做布局和样式，用 Mermaid via CDN 画图，当 graph/flow/sequence 能可靠传达结构时使用。
20. 混合使用 Mermaid 与手工 CSS/SVG 视觉：关系是图状（call graphs、dependencies、sequences）时用 Mermaid；想要更编辑式表达（mass diagrams、cross-sections、collapse animations）时用手工 div/SVG。
21. 每个候选都要有 before/after 可视化；要视觉化。
22. 为每个候选渲染一张卡片，包含 Files：涉及哪些文件/module。
23. 卡片包含 Problem：当前架构为什么造成摩擦。
24. 卡片包含 Solution：用平实英语描述会改变什么。
25. 卡片包含 Benefits：用 locality 和 leverage 解释，以及测试会如何改善。
26. 卡片包含 Before / After diagram：并排、手绘式，说明 shallow 和 deepening。
27. 卡片包含 Recommendation strength：`Strong`、`Worth exploring`、`Speculative` 之一，渲染成 badge。
28. 报告结尾加 Top recommendation 部分：先处理哪个候选以及为什么。
29. 领域词汇使用 `CONTEXT.md`，架构词汇使用 `/codebase-design`。如果 `CONTEXT.md` 定义了「Order」，就说「the Order intake module」，而不是「the FooBarHandler」，也不是「the Order service」。
30. ADR 冲突：如果候选与现有 ADR 矛盾，只有在摩擦足够真实、值得重新审视 ADR 时才提出。
31. 在卡片中清楚标记 ADR 冲突（例如 warning callout：「contradicts ADR-0007, but worth reopening because…」）。
32. 不要列出 ADR 禁止的每一个理论重构。
33. 参见 `HTML-REPORT.md` 获取完整 HTML scaffold、diagram patterns 和 styling guidance。
34. 此时不要提出 interface。文件写完后，问用户：「Which of these would you like to explore?」
35. 用户选中候选后，调用 Skill tool 的「grilling」，和他们一起走决策树：constraints、dependencies、deepened module 的形状、seam 后面是什么、哪些测试能存活。
36. 决策成形时内联产生副作用；调用 Skill tool 的「domain-modeling」，随着进展保持领域模型最新。
37. 如果要用 `CONTEXT.md` 中没有的概念命名 deepened module，就把该术语加入 `CONTEXT.md`；如果文件不存在，惰性创建。
38. 如果在对话中把模糊术语打磨得更精确，立即更新 `CONTEXT.md`。
39. 如果用户以承重理由拒绝候选，提议写 ADR，措辞为：「Want me to record this as an ADR so future architecture reviews don't re-suggest it?」
40. 只在未来探索者确实需要该理由来避免重新建议同一件事时才提议写 ADR；跳过短暂理由（「not worth it right now」）和不言自明理由。
41. 如果想探索 deepened module 的替代 interface，调用 Skill tool 的「codebase-design」，并使用它的 design-it-twice 并行 sub-agent 模式。

适用边界 · 注意事项

• 当用户只需要快速修复 bug 或添加小功能，不需要架构发现与深化时，不要启动完整流程。
• 当项目中的 ADR 已明确记录决策，且没有真实摩擦足以重开该决策时，不要提出与之冲突的重构。
• 当无法启动 sub-agent、无法生成或查看 HTML 报告，或没有近期变更/热点可参考时，收益有限，不适合使用。