improve-codebase-architecture

改进代码库架构

找出架构上的摩擦点，并提出加深机会——将浅层 module 重构为深层 module。目标是提升可测试性和 AI 导航能力。

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

• 运行 /codebase-design skill，了解架构词汇（module、interface、depth、seam、adapter、leverage、locality）及其原则（删除测试、“interface 就是测试面”、“一个 adapter = 假设的 seam，两个 = 真正的 seam”）。每条建议都要准确使用这些术语——不要改用“组件”“服务”“API”或“边界”。
• CONTEXT.md 中的领域语言为良好的 seam 命名；docs/adr/ 中的 ADR 记录了此命令不应重新讨论的决策。

流程

1. 探索

扫描前先确定范围——YAGNI。 加深 module 的价值在于让未来对其进行更改时更轻松，因此要格外关注近期有过更改的代码库部分。先决定查看哪里，再开始查看：

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

先阅读项目的领域术语表（CONTEXT.md）以及所涉及区域的任何 ADR。

然后启动一个子 Agent，让它遍历代码库。不要遵循僵化的启发式规则——自然地探索，并记录遇到摩擦的地方：

• 理解一个概念是否需要在许多小 module 之间来回切换？
• 哪些 module 是浅层的——interface 几乎和实现一样复杂？
• 是否为了便于测试而提取了纯函数，但真正的 bug 却隐藏在其调用方式中（缺乏 locality）？
• 紧密耦合的 module 是否跨 seam 泄漏？
• 代码库中哪些部分未经测试，或难以通过当前的 interface 进行测试？

对任何你怀疑是浅层的 module 应用删除测试：删除它是否会集中复杂性，还是只会把复杂性转移到别处？如果答案是“会集中”，这就是你要找的信号。

2. 将候选方案呈现为 HTML 报告

将独立的 HTML 文件写入操作系统的临时目录，确保仓库中不会留下任何文件。通过 $TMPDIR 获取临时目录；如果没有，则回退到 /tmp（Windows 上为 %TEMP%），并写入 <tmpdir>/architecture-review-<timestamp>.html，确保每次运行都会生成新文件。为用户打开该文件：Linux 上使用 xdg-open <path>，macOS 上使用 open <path>，Windows 上使用 start <path>，并告知用户绝对路径。

报告使用通过 CDN 加载的 Tailwind 进行布局和样式设计，并在图表能可靠地表达结构时，使用通过 CDN 加载的 Mermaid 绘图。将 Mermaid 与手工制作的 CSS/SVG 可视化结合起来——关系呈图形结构时（调用图、依赖关系、时序）使用 Mermaid；更具编辑风格时（质量图、剖面图、折叠动画）则使用手工构建的 div/SVG。每个候选方案都要有改造前/后的可视化。要注重视觉呈现。

对于每个候选方案，渲染一张卡片，包含：

• 文件 — 涉及的文件/模块
• 问题 — 当前架构为何造成阻碍
• 解决方案 — 用通俗语言描述将要做出的改动
• 收益 — 从局部性和杠杆效应的角度说明收益，以及测试将如何改进
• 改造前/后图示 — 并排展示自定义绘制的图示，说明结构的浅薄之处及如何加深
• 推荐强度 — 以下三者之一：Strong、Worth exploring、Speculative，并以徽章形式呈现

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

**领域术语使用 CONTEXT.md 中的词汇，架构术语使用 /codebase-design 中的词汇。**如果 CONTEXT.md 定义了“Order”，就称其为“Order 接入模块”，而不是“FooBarHandler”或“Order 服务”。

与 ADR 冲突：如果某个候选方案与现有 ADR 矛盾，只有在确实存在足以重新审议该 ADR 的阻碍时才提出。并在卡片中明确标出（例如，添加警告提示：“与 ADR-0007 冲突——但值得重新审议，因为……”）。不要列出 ADR 所禁止的每一种理论性重构。

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

暂时不要提出接口。文件写好后，询问用户：“你想进一步探讨其中的哪项方案？”

3. 反复探讨

用户选定候选方案后，运行 /grilling 技能，与用户一起沿决策树逐步探讨约束、依赖关系、加深后模块的形态、接缝背后的内容，以及哪些测试会保留。

随着决策逐渐明确，立即同步产生的副作用——运行 /domain-modeling 技能，确保领域模型保持最新：

• **将加深后的模块命名为 CONTEXT.md 中没有的概念？**将该术语添加到 CONTEXT.md。如果文件不存在，则按需创建。
• **在对话中明确了含糊不清的术语？**立即更新 CONTEXT.md。
• **用户基于关键原因拒绝了候选方案？**提出记录为 ADR，并这样询问：“要我将此记录为 ADR，避免后续架构评审再次提出它吗？”只有当未来探索者确实需要知道该原因，以免重复提出同一方案时才提出；跳过一时性的理由（“目前不值得做”）以及不言自明的理由。
• **想进一步探索加深后模块的替代接口？**运行 /codebase-design 技能，并采用其并行子 Agent 的双方案设计模式。