improve-codebase-architecture

改进代码库架构

找出架构摩擦，并提出深化机会——将浅模块改造成深模块的重构。目标是提升可测试性和 AI 导航能力。

此命令以项目的领域模型为依据，并基于一套共享的设计词汇：

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

流程

1. 探索

先确定范围，再开始扫描——YAGNI。 深化 module 能让今后对其进行修改更容易，因此应更加关注近期有变动的代码库部分。在查看代码之前，先决定查看哪里：

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

先阅读项目的领域术语表（CONTEXT.md）以及与你要处理的区域相关的 ADR。

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

• 理解一个概念是否需要在许多小 module 之间来回跳转？
• 哪些 module 是浅的——接口几乎和实现一样复杂？
• 是否有纯函数仅为便于测试而被提取出来，但真正的 bug 隐藏在它们的调用方式中（缺少locality）？
• 紧密耦合的 module 是否会跨越各自的 seam 泄漏？
• 代码库中哪些部分未经测试，或难以通过当前接口进行测试？

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

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 中选择一个，并以徽章形式呈现

报告最后添加 首要建议 部分：指出你会优先处理哪个候选方案，以及原因。

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

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

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

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

3. 深入讨论循环

用户选定候选方案后，使用“grilling”调用 Skill 工具，与用户一起梳理决策树——包括约束、依赖、深化后模块的形态、接口边界之后的内容，以及哪些测试会保留。

随着决策逐步明确，立即处理副作用——使用“domain-modeling”调用 Skill 工具，及时更新领域模型：

• 以 CONTEXT.md 中不存在的概念为深化后的模块命名？ 将该术语添加到 CONTEXT.md。如果文件不存在，则按需创建。
• 在对话中明确模糊术语的含义？ 立即更新 CONTEXT.md。
• 用户因关键理由拒绝候选方案？ 提议记录为 ADR，并这样询问：“要我把这点记录为 ADR 吗？这样未来进行架构评审时就不会再次推荐它了。” 只有当该理由能帮助未来的探索者避免重复提出同一建议时才提出；略过暂时性的理由（“目前不值得”）和不言自明的理由。
• 想探索深化后模块的替代接口？ 使用“codebase-design”调用 Skill 工具，并采用其 design-it-twice 并行子 Agent 模式。