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。 深化 module 能让今后更轻松地修改它，因此应重点关注近期变更过的代码库部分。先决定去哪里查看：

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

先阅读项目的领域术语表（GLOSSARY.md）以及你要处理区域中的所有 ADR。

然后启动一个使用全新上下文窗口的子 Agent，探索代码库。不要拘泥于固定启发式；自然地进行探索，并记录遇到的摩擦：

• 理解一个概念是否需要在许多小 module 之间来回跳转？
• 是否有 shallow 的 module，其 interface 几乎和实现一样复杂？
• 是否仅为可测试性而提取了纯函数，但真正的 bug 却隐藏在调用方式中（缺乏 locality）？
• 紧密耦合的 module 是否会跨越各自的 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 模式。