improve-codebase-architecture

Improve Codebase Architecture

暴露 architectural friction，并提出 deepening opportunities：把 shallow modules 变成 deep modules 的 refactors。目标是 testability 和 AI-navigability。

这个命令由项目的 domain model 提供信息，并建立在共享 design vocabulary 上：

• 运行 /codebase-design skill，获取 architecture vocabulary（module、interface、depth、seam、adapter、leverage、locality）及其 principles（deletion test、"the interface is the test surface"、"one adapter = hypothetical seam, two = real"）。每条建议都准确使用这些术语，不要漂移到 "component"、"service"、"API" 或 "boundary"。
• CONTEXT.md 中的 domain language 会为好的 seams 命名；docs/adr/ 中的 ADRs 记录这个命令不应重新争论的 decisions。

Process

1. Explore

先划定扫描范围——YAGNI。 深化 module 的收益在于让未来修改更容易，因此要更关注最近仍在变化的 codebase 区域。开始探索前先决定去哪里看：

• 如果用户点名了方向——module、subsystem 或 pain point——就按该方向探索，跳过下面的推断。
• 否则，向前回看一段足够长的 commit history（git log --oneline），找出反复出现的 files 和 areas，让这些 hot spots 成为首要关注点。如果变更分散、没有明显 hot spot，再扩大范围。

先读取项目 domain glossary（CONTEXT.md）以及你将触碰区域的 ADRs。

然后 spawn 一个 sub-agent 来遍历 codebase。不要套死板 heuristics；自然探索，并记录你感到 friction 的地方：

• 理解一个概念是否需要在许多小 modules 之间来回跳？
• 哪些 modules 是 shallow 的，即 interface 几乎和 implementation 一样复杂？
• 是否存在为了 testability 抽出的 pure functions，但真正 bugs 藏在它们如何被调用之处（没有 locality）？
• 哪些 tightly-coupled modules 泄漏到了 seams 之外？
• Codebase 的哪些部分未测试，或很难通过当前 interface 测试？

对任何你怀疑 shallow 的东西应用 deletion test：删除它会让复杂度集中，还是只把复杂度移动到别处？"yes, concentrates" 才是你要的 signal。

2. Present candidates as an HTML report

把 self-contained HTML file 写到 OS temp directory，避免任何内容落进 repo。Temp dir 从 $TMPDIR 解析，fallback 到 /tmp（Windows 用 %TEMP%），写到 <tmpdir>/architecture-review-<timestamp>.html，让每次运行都有新文件。为用户打开它：Linux 用 xdg-open <path>，macOS 用 open <path>，Windows 用 start <path>，并告诉用户 absolute path。

Report 使用 Tailwind via CDN 做 layout/styling，用 Mermaid via CDN 做能可靠传达结构的 diagrams。Mermaid 和手写 CSS/SVG visuals 可以混用：关系是 graph-shaped（call graphs、dependencies、sequences）时用 Mermaid；需要 editorial 表达（mass diagrams、cross-sections、collapse animations）时用手写 divs/SVG。每个 candidate 都要有 before/after visualisation。要视觉化。