改进代码库架构

浮现架构摩擦，并提出深化机会——把浅模块变成深模块的重构。目标是可测试性和 AI 可导航性。

这条命令受项目领域模型的启发，并建立在一套共享的设计词汇之上：

• 运行 /codebase-design 技能获取架构词汇（模块、接口、深度、接缝、适配器、杠杆、局部性）及其原则（删除测试、「接口就是测试面」、「一个适配器 = 假想的接缝，两个 = 真实的接缝」）。在每条建议里都精确使用这些术语——不要漂移到「组件」、「服务」、「API」或「边界」。
• CONTEXT.md 里的领域语言给好接缝命名；docs/adr/ 里的 ADR 记录了这条命令不应重新翻案的决策。

流程

1. 探索

扫描之前先界定范围——YAGNI。 深化一个模块的回报，来自让它未来的改动更容易，所以对代码库中近期改动过的部分给予额外权重。在看之前先决定往哪看：

• 如果用户指定了一个方向——一个模块、一个子系统、一个痛点——就采用它，跳过下面的推断。
• 否则，往回走一大段 commit 历史（git log --oneline），找出代码库的热点——那些反复出现的文件和区域——让这些路径先吸引你的注意力。如果改动零散、没有明显热点，就把网撒得更宽。

先读项目的领域词汇表（CONTEXT.md）以及你正在触碰的区域里的任何 ADR。

然后派发一个子 agent 走一遍代码库。不要遵循僵硬的启发式——有机地探索，并记下你在哪里感到摩擦：

• 在哪里理解一个概念需要在许多小模块之间来回跳？
• 在哪里模块是浅的——接口几乎和实现一样复杂？
• 在哪里纯函数只是为了可测试性而被提取出来，但真正的 bug 藏在它们如何被调用之中（没有局部性）？
• 在哪里紧耦合的模块跨越它们的接缝泄漏？
• 代码库的哪些部分未经测试，或难以通过其当前接口测试？

对任何你怀疑是浅的东西施加删除测试：删掉它会让复杂度集中，还是只是把它挪走？「会，会集中」就是你想要的信号。

2. 以 HTML 报告呈现候选项

把一个自包含的 HTML 文件写到操作系统临时目录，这样什么都不会落进仓库。从 $TMPDIR 解析临时目录，回退到 /tmp（或 Windows 上的 %TEMP%），并写入 <tmpdir>/architecture-review-<timestamp>.html，这样每次运行都得到一个新文件。为用户打开它——Linux 上 xdg-open <path>、macOS 上 open <path>、Windows 上 start <path>——并告诉他们绝对路径。

报告用 Tailwind via CDN 做布局和样式，用 Mermaid via CDN 在图/流程/时序能可靠传达结构的地方画图。把 Mermaid 与手工打造的 CSS/SVG 视觉元素混用——当关系是图状的（调用图、依赖、时序）时用 Mermaid，当你想要更有编辑意味的东西（体量图、剖面图、坍缩动画）时用手工搭的 div/SVG。每个候选项都配一张前后对比可视化。要有视觉表现力。

为每个候选项渲染一张卡片，包含：

• 文件 — 涉及哪些文件/模块
• 问题 — 为什么当前架构在造成摩擦
• 方案 — 用平实的英语描述会改变什么
• 收益 — 用局部性和杠杆来解释，以及测试会如何改善
• 前 / 后 图 — 并排、自定义绘制，说明浅处和深化
• 推荐强度 — Strong、Worth exploring、Speculative 三者之一，渲染成一个徽章

以一个 Top recommendation 段落收尾报告：你会先着手哪个候选项以及为什么。

领域用 CONTEXT.md 词汇，架构用 /codebase-design 词汇。 如果 CONTEXT.md 定义了 "Order"，就说「the Order intake module」——而不是「the FooBarHandler」，也不是「the Order service」。

ADR 冲突：如果一个候选项与现有 ADR 相抵触，只在摩擦真实到值得重新审视该 ADR 时才浮现它。在卡片里清楚标出（例如一个警告标注：「与 ADR-0007 相抵触——但值得重开，因为……」）。不要罗列一条 ADR 所禁止的每一个理论上的重构。

参见 HTML-REPORT.md 了解完整的 HTML 脚手架、图表模式和样式指南。

现在还不要提出接口。文件写好后，问用户：「这些里面你想探索哪一个？」

3. 拷问循环

一旦用户挑好一个候选项，运行 /grilling 技能与他们一起走一遍决策树——约束、依赖、深化后模块的形状、接缝背后是什么、哪些测试能存活。

副作用随着决策结晶而就地发生——运行 /domain-modeling 技能，让领域模型随进展保持最新：

• 要用一个不在 CONTEXT.md 里的概念给深化后的模块命名？ 把这个术语加进 CONTEXT.md。文件不存在就懒创建。
• 在对话中磨锐了一个模糊的术语？ 当场更新 CONTEXT.md。
• 用户以一个起承重作用的理由拒绝了该候选项？ 提出记一条 ADR，措辞为：「要我把这个记成一条 ADR，好让未来的架构审查不再重新提议它吗？」 只在这个理由确实会被未来的探索者用来避免重新提议同一件事时才提出——跳过一次性的理由（「现在不值得」）和不言自明的理由。
• 想为深化后的模块探索备选接口？ 运行 /codebase-design 技能，使用它的「设计两遍」并行子 agent 模式。