improve-codebase-architecture

# 改进代码库架构

像 AI 一样探索一整个代码库：暴露架构摩擦点（architectural friction），发现提升可测试性的机会，并以 GitHub issue/RFC 的形式提出“模块加深（module-deepening）”的重构建议。

所谓**深模块（deep module）**（John Ousterhout，《A Philosophy of Software Design》）具有“小接口（small interface）+ 大量实现隐藏”的特征。深模块更容易测试、更便于 AI 导航，并能让你在边界处测试，而不是在内部内部测。

## 流程（Process）

### 1. 探索代码库

使用 Agent 工具（subagent_type=Explore）自然地浏览代码库。不要使用僵硬的启发式规则（heuristics）——要“有机探索”，并记录你在理解过程中感受到的摩擦：

- 理解一个概念往往需要在很多很小的文件之间来回跳转，这种情况在哪里？
- 哪些模块过于“浅”（shallow）导致接口几乎和实现一样复杂？
- 是否曾经抽出了纯函数让它们更易测试，但真正的 bug 藏在“它们如何被调用”之中？
- 哪些强耦合模块在彼此的缝隙（seams）处制造了集成风险？
- 代码库中哪些部分没有被测试，或者很难测试？

你遇到的摩擦点就是信号（the friction IS the signal）。

### 2. 给出候选项

以“编号列表”的形式呈现深化（deepening）的机会。对每个候选项，展示：

- **聚类（Cluster）**：涉及哪些模块/概念
- **为什么耦合**：共享类型、调用模式、对某一概念的共同所有（co-ownership）
- **依赖类别（Dependency category）**：依赖类别的划分见 [REFERENCE.md](REFERENCE.md) 的四种分类
- **测试影响（Test impact）**：哪些现有测试会被边界测试（boundary tests）替代

目前**不要**提出具体接口设计。先问用户：`你想要进一步探索这些候选项里的哪一个？`

### 3. 用户选择候选项

### 4. 刻画问题空间

在启动子 agent 之前，先给出一个面向用户的问题空间说明（user-facing explanation），用于所选候选项：

- 新接口需要满足的约束条件
- 新接口需要依赖的内容
- 一个粗略的示意代码草图，用来把约束落到具体形态上——这不是提案，只是为了让约束更具体

把这些内容展示给用户，然后立刻进入第 5 步：让用户阅读并思考的同时，子 agent 会并行工作。

### 5. 设计多个接口方案

使用 Agent 工具并行启动 3 个以上的子 agent。每个子 agent 都必须为“深模块（deepened module）”输出一种**根本不同（radically different）**的接口设计。

为每个子 agent 提供独立的技术简报（文件路径、耦合细节、依赖类别、需要隐藏的复杂度等）。该简报与第 4 步面向用户的解释互相独立。并确保每个 agent 的设计约束不同：

- Agent 1：`尽量缩小接口——目标是最多 1-3 个入口点`
- Agent 2：`尽量提升灵活性——支持尽可能多的用例与扩展`
- Agent 3：`优化最常见的调用者——让默认场景变得非常简单`
- Agent 4（若适用）：`围绕 ports & adapters 模式为跨边界依赖进行设计`

每个子 agent 的输出应包含：

1. 接口签名（types、方法、参数）
2. 使用示例（展示调用方如何使用）
3. 内部隐藏了哪些复杂度
4. 依赖策略（如何处理依赖——见 [REFERENCE.md](REFERENCE.md)）
5. 方案的取舍（trade-offs）

把这些设计方案按顺序呈现，然后用文字进行对比分析。

对比之后，给出你自己的推荐：你认为哪一种设计最强，并说明原因。如果不同设计的要素有组合空间，可以提出混合方案。要“有主见”——用户想要的是有分量的判断，而不只是菜单式列举。

### 6. 用户选择接口（或接受推荐）

### 7. 创建 GitHub issue

使用 `gh issue create` 把一次“重构 RFC（refactor RFC）”创建成 GitHub issue。并使用 [REFERENCE.md](REFERENCE.md) 中的模板。

**不要**要求用户在创建之前先审核——直接创建并把 URL 发给用户。