improve-codebase-architecture

改进代码库架构

呈现架构摩擦，提出深化机会：把浅模块变成深模块（deep module）的重构。目标是可测试性与 AI 可导航性。

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

• 调用 Skill 工具并传入 "codebase-design"，获取架构词汇表（模块（module）、接口（interface）、深度（depth）、接缝（seam）、适配器（adapter）、杠杆（leverage）、局部性（locality））及其原则（删除测试（deletion test）、「接口即测试面」、「一个适配器 = 假想接缝，两个 = 真实接缝」）。在每条建议中精确使用这些术语，不要漂移到 "component"、"service"、"API" 或 "boundary"。
• CONTEXT.md 中的领域语言为好的接缝命名；docs/adr/ 中的 ADR（架构决策记录）记录了本命令不应重新翻案的决策。

流程

1. 探索

**扫描前先定范围：YAGNI。**深化一个模块的回报在于让未来对它的变更更容易，因此要格外看重代码库中最近变更过的部分。在看之前，先决定看哪里，并写下本轮不可扩大的业务范围和必须保持的外部行为：

• 如果用户指定了方向（某个模块、某个子系统、某个痛点），直接采纳，并跳过下面的推断。
• 否则，回溯相当长的一段提交历史（git log --oneline），找出代码库的热点——反复出现的文件和区域——让这些路径最先吸引你的注意。如果变更分散、没有明确热点，就扩大撒网范围。

先读项目的领域词汇表（CONTEXT.md）以及你将触及区域内的所有 ADR。

然后生成一个子代理去走查代码库。不要遵循僵化的启发式规则；自然地探索，并记下你遇到摩擦的地方：

• 哪里理解一个概念需要在许多小模块之间来回跳转？
• 哪里的模块很浅，接口几乎和实现一样复杂？
• 哪里只是为了可测试性抽出了纯函数，而真正的 bug 藏在它们的调用方式里（没有局部性）？
• 哪里有紧耦合模块跨接缝泄漏？
• 代码库哪些部分没有测试，或者难以通过当前接口进行测试？
• 哪里存在已经达到删除条件的兼容层、旧接口或双轨实现？

对任何你怀疑很浅的东西应用删除测试：删掉它会让复杂度集中，还是只是挪个地方？「会集中」才是你想要的信号。

2. 以 HTML 报告呈现候选

把一个自包含的 HTML 文件写入操作系统临时目录，这样仓库里不会落下任何东西。从 $TMPDIR 解析临时目录，回退到 /tmp（Windows 上是 %TEMP%），写入 <tmpdir>/architecture-review-<timestamp>.html，让每次运行都得到一个新文件。替用户打开它（Linux 用 xdg-open <path>，macOS 用 open <path>，Windows 用 start <path>），并告知绝对路径。

报告用 Tailwind（经 CDN 引入） 做布局和样式，用 Mermaid（经 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 所禁止的每一个理论上的重构。