improve-codebase-architecture

改进代码库架构

发现架构摩擦，并提出加深机会：将浅模块重构为深模块。目标是提升可测试性和 AI 导航能力。

此命令_以_项目的领域模型为依据，并建立在一套共享的设计词汇之上：

• 使用精确的架构词汇（模块、接口、深度、接缝、适配器、杠杆、局部性）及其原则（删除测试、“接口就是测试面”、“一个适配器＝假设的接缝，两个＝真实的接缝”）。每条建议都要准确使用这些术语：不要改用“组件”、“服务”、“API”或“边界”。
• 测试替身也算第二种实现：如果一个接口有一个生产适配器，而测试会替换它，那么这就是真实接缝，而非假设的接缝。只有在一个接口只有一个调用方且_没有_替换时，才会因此无法通过删除测试。（这与 /setup-solid 写入 CLAUDE.md 的规则相同，两者不得相互矛盾。）
• GLOSSARY.md 中的领域语言为良好的接缝命名；docs/adr/ 中的 ADR 记录了此命令不应重新讨论的决策。

流程

1. 探索

扫描前先确定范围：YAGNI。 加深模块的价值在于让未来对其进行修改更容易，因此应重点关注近期有过改动的代码库部分。先决定_去哪里_查看，再开始查看：

• 如果用户指定了方向（某个模块、子系统或痛点），就按此方向进行，并跳过以下推断步骤。
• 否则，沿着提交历史往回查看一段时间（git log --oneline），找出代码库中的热点，也就是反复出现的文件和区域，并优先关注这些路径。如果改动分散，没有明显热点，就扩大搜索范围。

首先阅读项目的领域词汇表（GLOSSARY.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，以徽章形式呈现

报告末尾添加首选建议部分，说明你会优先处理哪个候选方案，以及原因。

领域术语使用 GLOSSARY.md 中的词汇，架构术语使用上述架构词汇。 如果 GLOSSARY.md 定义了 “Order”，请使用“Order 接入模块”，而不是 “FooBarHandler” 或 “Order 服务”。

ADR 冲突：如果某个候选方案与现有 ADR 相矛盾，只有当实际阻碍严重到值得重新审议该 ADR 时，才展示该方案。在卡片中明确标记（例如警告提示：“与 ADR-0007 相矛盾，但值得重新审议，因为……”）。不要列出 ADR 禁止的所有理论性重构方案。

完整的 HTML 框架、图表模式和样式指南请参见 HTML-REPORT.md。

此时不要提出接口方案。写完文件后，询问用户：“你想进一步探讨哪个方案？”

3. 深入探讨循环

用户选定一个候选方案后，调用 Skill 工具并使用 “grilling”，与用户一起走完决策树：约束条件、依赖项、加深后的模块形态、边界背后的内容，以及哪些测试会保留。

随着决策逐渐明确，副作用也会随之发生：在过程中持续更新领域模型：

• 要用 GLOSSARY.md 中尚未定义的概念为加深后的模块命名？ 将该术语添加到 GLOSSARY.md。如果文件不存在，则按需创建。
• 在对话中明确了模糊术语的含义？ 立即更新 GLOSSARY.md。
• 用户基于关键原因否决了候选方案？ 提议记录为 ADR，措辞如下：“要我将此记录为 ADR，以便今后的架构评审不会再次建议这个方案吗？”只有当未来的探索者确实需要这个原因来避免重复提出该方案时才提出；如果理由是暂时性的（“现在不值得做”）或不言自明，则跳过。
• 想要探索加深后模块的替代接口？ 使用双重设计方法：启动并行子 Agent 起草不同的接口方案，然后进行比较。