improve-codebase-architecture

改进代码库架构

找出架构上的摩擦点，并提出加深机会：通过重构，把浅层模块变成深层模块。目标是提升可测试性和 AI 可导航性。

本命令参考项目的领域模型，并基于一套共享的设计词汇：

• 调用 Skill 工具并传入 "codebase-design"，以获取架构词汇（module、interface、depth、seam、adapter、leverage、locality）及其原则（删除测试、"interface 即测试面"、"一个 adapter 是假想的 seam，两个才是真实的 seam"）。每条建议都要严格使用这些术语，不要偏离为 "component"、"service"、"API" 或 "boundary"。
• GLOSSARY.md 中的领域语言为好的 seam 提供名称；docs/adr/ 中的 ADR 记录了本命令不应重新讨论的决策。

流程

1. 探索

扫描前先确定范围：YAGNI。 加深一个模块的收益在于让它未来更容易修改，因此要更重视近期发生过变更的部分代码库。在开始查看之前，先决定看哪里：

• 如果用户指定了方向（某个模块、某个子系统或某个痛点），就以此为准，跳过下面的推断。
• 否则，回溯一段较长的提交历史（git log --oneline），找出代码库的热点，即反复出现的文件和区域，让这些路径优先吸引你的注意力。如果变更分散、没有明显热点，就扩大搜索范围。

先阅读项目的领域术语表（GLOSSARY.md）以及你即将改动区域中的所有 ADR。

然后启动一个子 Agent 遍历代码库。不要套用僵化的启发式规则，而是有机地探索，并记录你遇到摩擦的地方：

• 理解一个概念时，是否需要在许多小模块之间来回跳转？
• 哪些模块是浅层的，即其 interface 几乎和实现一样复杂？
• 是否有纯函数仅为可测试性而被抽取，而真正的 bug 却藏在它们被调用的方式中（缺乏 locality）？
• 紧耦合的模块是否在其 seam 处发生泄漏？
• 代码库中哪些部分没有测试，或者很难通过当前的 interface 进行测试？

对任何你怀疑是浅层的东西应用删除测试：删除它会让复杂度集中，还是只是把复杂度转移走？你要寻找的信号是"是的，会集中"。

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 三者之一，以徽章形式呈现

报告末尾添加 首要推荐 一节：说明你会优先处理哪个候选方案，以及原因。

领域术语使用 GLOSSARY.md 中的词汇，架构术语使用 /codebase-design 中的词汇。 如果 GLOSSARY.md 定义了“Order”，就称之为“Order 接收模块”，而不要称为“FooBarHandler”，也不要称为“Order 服务”。

ADR 冲突：如果某个候选方案与现有 ADR 相悖，只有当阻力足够真实、值得重新审视该 ADR 时才提出。在卡片中明确标注（例如使用警告提示块：“与 ADR-0007 相悖，但值得重新审视，因为……”）。不要列出 ADR 禁止的每一种理论上的重构。

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

暂时不要提出接口方案。文件写入完成后，向用户提问：“您想探索其中哪一个方案？”

3. 追问循环

用户选定某个候选方案后，调用 Skill 工具并传入 “grilling”，与用户逐步梳理决策树：约束条件、依赖关系、加深后模块的形态、接缝之后的内容，以及哪些测试得以保留。

在决策逐渐明确的过程中，内联产生的副作用需同步处理。调用 Skill 工具并传入 “domain-modeling”，使领域模型随讨论持续更新：

• 将加深后的模块以 GLOSSARY.md 中不存在的概念命名？ 将该术语添加到 GLOSSARY.md。若文件不存在，则按需创建。
• 对话中厘清了一个模糊术语？ 立即更新 GLOSSARY.md。
• 用户以具有实质性的理由否决了候选方案？ 提议记录为 ADR，表述为：“是否需要我将其记录为 ADR，以便未来的架构审查不再重复提出该方案？” 仅当该理由确实是未来的探索者为避免重复提出同一方案所需的信息时才提议；临时性理由（如“现在不值得做”）和不言自明的理由则跳过。
• 想探索加深后模块的替代接口？ 调用 Skill 工具并传入 “codebase-design”，并使用其“设计两次”的并行子 Agent 模式。