improve-codebase-architecture

1# 改进代码库架构
2 
3暴露 architectural friction，并提出 **deepening opportunities**：把 shallow modules 变成 deep modules 的 refactors。目标是 testability 和 AI-navigability。
4 
5这个命令由项目的 domain model 提供信息，并建立在共享 design vocabulary 上：
6 
7- 调用 Skill 工具并指定 `codebase-design`，获取 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"。
8- `GLOSSARY.md` 中的 domain language 会为好的 seams 命名；`docs/adr/` 中的 ADRs 记录这个命令不应重新争论的 decisions。
9 
10## 流程
11 
12### 1. 探索
13 
14**先划定扫描范围：YAGNI。** 深化 module 的收益在于让未来修改更容易，因此要更关注最近仍在变化的 codebase 区域。开始探索前先决定去哪里看：
15 
16- 如果用户点名了方向（module、subsystem 或 pain point），就按该方向探索，跳过下面的推断。
17- 否则，向前回看一段足够长的 commit history（`git log --oneline`），找出反复出现的 files 和 areas，让这些 hot spots 成为首要关注点。如果变更分散、没有明显 hot spot，再扩大范围。
18 
19先读取项目 domain glossary（`GLOSSARY.md`）以及你将触碰区域的 ADRs。
20 
21然后 spawn 一个使用全新 context window 的 sub-agent 来遍历 codebase。不要套死板 heuristics；自然探索，并记录你感到 friction 的地方：
22 
23- 理解一个概念是否需要在许多小 modules 之间来回跳？
24- 哪些 modules 是 **shallow** 的，即 interface 几乎和 implementation 一样复杂？
25- 是否存在为了 testability 抽出的 pure functions，但真正 bugs 藏在它们如何被调用之处（没有 **locality**）？
26- 哪些 tightly-coupled modules 泄漏到了 seams 之外？
27- Codebase 的哪些部分未测试，或很难通过当前 interface 测试？
28 
29对任何你怀疑 shallow 的东西应用 **deletion test**：删除它会让复杂度集中，还是只把复杂度移动到别处？"yes, concentrates" 才是你要的 signal。
30 
31### 2. 用 HTML 报告呈现候选项
32…