improve-codebase-architecture

改进代码库架构

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

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

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

流程

1. 探索

先确定范围，再扫描：YAGNI。 深化模块的价值在于让未来对它的修改更容易，因此应格外关注近期有变动的代码库部分。先决定查看哪里：

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

先阅读项目的领域术语表（CONTEXT.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>），并告知用户其绝对路径。

报告使用 Tailwind via CDN 进行布局和样式设计；如果图表能可靠地表达结构，则使用 Mermaid via CDN 绘制图表，包括图形、流程或时序。将 Mermaid 与手工制作的 CSS/SVG 视觉元素结合使用：适合图形结构的关系（调用图、依赖关系、时序）使用 Mermaid；更具编辑感的内容（质量图、剖面图、折叠动画）则使用手工制作的 div/SVG。每个候选方案都要配有改造前/改造后可视化。注重视觉呈现。

为每个候选方案绘制一张卡片，包含：

• 文件：涉及的文件/模块
• 问题：当前架构为何造成摩擦
• 解决方案：用通俗语言描述需要改动什么
• 收益：从内聚性和杠杆效应的角度说明收益，以及测试将如何改进
• 改造前 / 改造后图表：并排展示自定义绘制的图表，体现模块的浅化与加深
• 推荐强度：从 Strong、Worth exploring、Speculative 中选择一个，并以徽章形式显示

报告结尾处添加 Top recommendation 部分：说明你会优先处理哪个候选方案以及原因。

领域术语请使用 CONTEXT.md 中的词汇，架构术语请使用 /codebase-design 中的词汇。 如果 CONTEXT.md 将某个概念定义为 “Order”，就称其为 “Order intake module”，而不是 “FooBarHandler” 或 “Order service”。

ADR 冲突：如果某个候选方案与现有 ADR 冲突，只有在摩擦确实严重到值得重新审视 ADR 时才提出。请在卡片中明确标注（例如，警告提示：“与 ADR-0007 冲突，但值得重新讨论，因为……”）。不要列出 ADR 禁止的每一种理论上的重构。

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

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

3. 深入讨论流程

用户选定候选方案后，调用 Skill 工具并传入 "grilling"，与用户一起按决策树逐步讨论约束、依赖关系、加深模块的形态、边界之后的内容，以及哪些测试会保留。

随着决策逐渐明确，直接进行相应的副作用；调用 Skill 工具并传入 "domain-modeling"，以便随讨论持续更新领域模型：

• 以 CONTEXT.md 中不存在的概念为加深后的模块命名？ 将该术语添加到 CONTEXT.md。如果文件不存在，则按需创建。
• 在讨论中明确了某个模糊术语的含义？ 立即更新 CONTEXT.md。
• 用户基于关键理由否决了候选方案？ 提议记录为 ADR，并这样询问：“要我把这个决定记录为 ADR，以免未来的架构评审再次提出同一方案吗？” 仅当未来的探索者确实需要这个理由来避免再次提出相同方案时才提议；对于“现在不值得做”之类的临时理由，以及不言自明的理由，则跳过。
• 想探索加深模块的其他接口方案？ 调用 Skill 工具并传入 "codebase-design"，并使用其双方案并行子代理模式。