improve-codebase-architecture

改进代码库架构

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

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

• 使用代码库自身的词汇，找出模块接口、实现复杂度和行为边界。优先考虑能用更小的接口隐藏实际复杂性的机会。
• GLOSSARY.md 中的领域语言为良好的边界提供了名称；docs/adr/ 中的 ADR 记录了此命令不应重新讨论的决策。

流程

1. 探索

先确定范围，再开始扫描：YAGNI。 深化模块的价值在于让今后修改它更容易，因此应重点关注近期有过变更的代码。先决定去哪里查看：

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

先阅读项目的领域词汇表（GLOSSARY.md），以及你将要处理区域中的任何 ADR。

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

• 要理解某个概念，是否需要在许多小模块之间来回切换？
• 是否存在浅层模块，其接口几乎和实现一样复杂？
• 是否为了可测试性而提取了纯函数，但真正的 bug 却藏在调用方式中（缺乏局部性）？
• 紧密耦合的模块是否会跨越边界泄漏？
• 代码库中哪些部分没有测试，或难以通过现有接口进行测试？

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

2. 展示候选方案

默认情况下，在对话中以 Markdown 展示候选方案——下面的内容才是评审的重点，用纯文本呈现也很清晰。只有在用户要求 HTML 报告，或只有前后对比可视化才能清楚呈现候选方案结构时，才编写自包含的 HTML 报告。

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

HTML 报告使用 Tailwind via CDN 进行布局和样式设计；对于能够可靠传达结构的图表、流程图或时序图，使用 Mermaid via CDN。将 Mermaid 与手工制作的 CSS/SVG 可视化结合使用：关系呈图形结构（调用图、依赖关系、时序）时使用 Mermaid；需要更具编辑感的可视化（质量图、剖面图、折叠动画）时使用手工制作的 div/SVG。每个候选方案都需要前后对比可视化。要注重视觉呈现。两种 CDN 在离线环境或脚本被拦截时都会静默失效，因此如果环境无法访问它们，就将 CSS 内联并手工制作 SVG。

每个候选方案都要涵盖：

• 文件 — 涉及哪些文件/模块
• 问题 — 当前架构为何造成阻碍
• 解决方案 — 用通俗语言描述将有哪些变化
• 收益 — 从局部性和杠杆效应的角度说明收益，以及测试会如何改进
• 之前 / 之后 — 并列展示浅化与深化；在 HTML 中使用自定义绘制的图示，在 Markdown 中以文字呈现同样的对比
• 推荐力度 — 从 Strong、Worth exploring、Speculative 中选择一个，并以徽章形式呈现

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

使用 GLOSSARY.md 中的词汇描述领域，并用通俗语言解释架构术语。 如果 GLOSSARY.md 定义了“Order”，就应称其为“Order 接单模块”，而不是“FooBarHandler”或“Order 服务”。

与 ADR 冲突：如果候选方案与现有 ADR 矛盾，只有在确实存在足够大的阻碍、值得重新审议 ADR 时才提出来。在卡片中明确标注（例如警示提示：“与 ADR-0007 冲突，但由于……，值得重新审议”）。不要罗列 ADR 禁止的所有理论性重构方案。

如果采用 HTML 方案，请参阅 HTML-REPORT.md，了解完整的 HTML 框架、图示模式和样式指南。

暂时不要提出接口。 展示完候选方案后，询问用户：“你想进一步探讨哪一个方案？”

3. 深入探讨循环

用户选定候选方案后，调用 Skill 工具并传入“grilling”，与用户一起逐步梳理决策树：约束、依赖、深化后模块的形态、边界之后的内容，以及哪些测试会保留下来。

随着决策逐步明确，相关操作会同步进行；调用 Skill 工具并传入“domain-modeling”，随时更新领域模型：

• 将深化后的模块命名为 GLOSSARY.md 中尚未定义的概念时？ 将该术语添加到 GLOSSARY.md。如果文件不存在，则按需创建。
• 在对话中厘清含糊术语时？ 立即更新 GLOSSARY.md。
• 用户以影响重大决策的理由否决候选方案时？ 提议记录为 ADR，措辞如下：“要我把这个决定记录为 ADR，避免未来的架构评审再次提出同一方案吗？” 只有当未来的探索者确实需要该理由来避免重复提出同一方案时才提出；如果理由只是暂时不值得做，或显而易见，则跳过。
• 想探索深化后模块的其他接口方案时？ 直接比较不同接口方案，并说明与该模块相关的权衡。