improve-codebase-architecture

改进代码库架构（Improve Codebase Architecture）

暴露架构上的摩擦，并提出 加深机会（deepening opportunities）——把浅模块变为深模块的重构。目标是可测试性与对 AI 友好的可导航性。

这条命令 受 项目领域模型 启发，并构建在一套共享的设计词汇之上：

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

流程

1. 探索

在扫描之前先划定范围——YAGNI。 加深一个模块的回报，来自让它未来更易于改动，所以要对代码库中近期变动过的部分格外看重。在动手看之前先决定 看哪里：

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

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

然后用 Agent 工具（subagent_type=Search）来遍历代码库。不要遵循僵化的启发式规则——有机地探索，并记下你感到摩擦的地方：

• 哪里为了理解一个概念，需要在许多小模块之间来回跳转？
• 哪里的模块是 浅 的——接口的复杂度几乎和实现一样？
• 哪里为了可测试性而抽取了纯函数，但真正的 bug 却藏在它们 如何被调用 之中（缺乏 局部性）？
• 哪里紧耦合的模块跨越各自的接缝发生泄漏？
• 代码库的哪些部分未被测试，或难以通过其当前接口进行测试？

对任何你怀疑是浅的东西，施加 删除测试：删掉它会让复杂度 集中，还是仅仅把它 挪走？一个"会集中"的"是"，正是你想要的信号。

2. 把候选项呈现为一份 HTML 报告

将一个自包含的 HTML 文件写入操作系统的临时目录，这样就不会有东西落进仓库。从 $TMPDIR 解析临时目录，回退到 /tmp（Windows 上为 %TEMP%），并写入 <tmpdir>/architecture-review-<timestamp>.html，使每次运行都得到一个全新文件。为用户打开它——在 macOS 上用 open <path>——并告诉他们绝对路径。

报告使用 通过 CDN 引入的 Tailwind 进行布局和样式设计，并在图/流程/时序能可靠传达结构的地方使用 通过 CDN 引入的 Mermaid 绘制图表。把 Mermaid 与手工打造的 CSS/SVG 视觉元素混用——当关系呈图状（调用图、依赖、时序）时用 Mermaid，当你想要更有编排感的东西（体量图、剖面图、坍缩动画）时用手工构建的 div/SVG。每个候选项都配一张 前/后对比可视化图。要富有视觉表现力。

对每个候选项，渲染一张卡片，包含：

• Files（文件）——涉及哪些文件/模块
• Problem（问题）——为什么当前架构在制造摩擦
• Solution（方案）——用平实的语言描述会改变什么
• Benefits（收益）——用局部性与杠杆的角度来解释，以及测试会如何改善
• Before / After diagram（前/后对比图）——并排、手工绘制，展现浅与加深
• Recommendation strength（推荐强度）——Strong、Worth exploring、Speculative 之一，以徽章形式呈现

在报告末尾放一个 Top recommendation（首推）小节：你会最先着手哪个候选项，以及为什么。

领域方面使用 CONTEXT.md 的词汇，架构方面使用 /codebase-design 的词汇。 如果 CONTEXT.md 定义了 "Order"，就谈 "the Order intake module（订单接收模块）"——而不是 "the FooBarHandler"，也不是 "the Order service"。