improve-codebase-architecture

改进代码库架构

揭示架构摩擦点并提出深化机会——将浅层 module 转变为深层 module 的重构。目标是可测试性和 AI 可导航性。

本命令参考项目的领域模型，并基于共享的设计词汇：

• 调用 Skill 工具并传入 "codebase-design" 获取架构词汇（module、interface、depth、seam、adapter、leverage、locality）及其原则（deletion test、"interface 就是 test surface"、"一个 adapter = 假设性 seam，两个 = 真实的"）。在每个建议中严格使用这些术语——不要偏离到 "component"、"service"、"API" 或 "boundary"。
• CONTEXT.md 中的领域语言为好的 seam 提供了命名；docs/adr/ 中的 ADR 记录了本命令不应重新讨论的决策。

流程

1. 探索

先确定范围再扫描——YAGNI。 加深一个模块的回报在于使未来对该模块的修改更容易，因此对最近变更的代码区域给予额外权重。在查看之前先决定看哪里：

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

首先阅读项目的领域术语表（CONTEXT.md）以及你将要接触的区域内任何 ADR。

然后生成一个子代理来遍历代码库。不要遵循僵化的启发式规则——有机地探索，并记录你在哪里遇到了摩擦：

• 在哪些地方，理解一个概念需要在多个小模块之间来回跳转？
• 哪些 module 是shallow的——interface 几乎和 implementation 一样复杂？
• 哪些地方纯粹为了可测试性而提取了纯函数，但真正的 bug 却隐藏在它们的调用方式中（缺乏 locality）？
• 哪些紧密耦合的 module 跨越了它们的 seam？
• 代码库的哪些部分未经测试，或难以通过当前 interface 进行测试？

对你怀疑是 shallow 的任何内容应用deletion test：删除它会集中复杂性，还是仅仅移动它？"集中了"就是你想要的信号。

2. 将候选方案呈现为 HTML 报告

编写一个自包含的 HTML 文件到 OS 临时目录，这样不会在仓库中留下任何文件。从 $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，当你想要更具编辑性的效果时（mass 图、截面图、折叠动画）使用手工构建的 div/SVG。每个候选方案都要有前后对比可视化。要有视觉冲击力。

每个候选方案渲染一张卡片，包含：

• 文件——涉及哪些文件/module
• 问题——当前架构为何造成摩擦
• 方案——用通俗语言描述会发生什么变化
• 收益——用 locality 和 leverage 的术语解释，以及测试会如何改进
• 前后对比图——并排展示，自定义绘制，说明 shallowness 和 deepening 效果
• 推荐强度——Strong（强烈推荐）、Worth exploring（值得探索）、Speculative（推测性），渲染为 badge

报告以最佳推荐部分结尾：你会先处理哪个候选方案以及原因。

对 CONTEXT.md 使用领域词汇，对架构使用 /codebase-design 词汇。 如果 CONTEXT.md 定义了 "Order"，就说 "Order intake module"——而不是 "FooBarHandler"，也不是 "Order service"。