improve-codebase-architecture

改进代码库架构

像 AI 一样探索代码库，发现架构摩擦点，寻找提升可测试性的机会，并将模块深化重构方案整理为 GitHub issue RFC。

深模块（John Ousterhout，《A Philosophy of Software Design》）通过小型接口隐藏大型实现。深模块更易测试、更便于 AI 导航，也能让你在边界处而非内部进行测试。

流程

1. 探索代码库

使用 Agent 工具并设置 subagent_type=Explore，自然地浏览代码库。不要遵循僵化的启发式规则——自由探索，并记录你遇到摩擦的地方：

• 要理解一个概念，是否需要在许多小文件之间来回切换？
• 模块是否过于浅薄，以至于接口几乎和实现一样复杂？
• 是否为了可测试性而抽取了纯函数，但真正的 bug 却藏在这些函数的调用方式中？
• 紧密耦合的模块是否在彼此的交界处带来集成风险？
• 代码库中哪些部分没有测试，或难以测试？

你遇到的摩擦就是信号。

2. 提出候选方案

列出编号的模块深化机会。对于每个候选方案，说明：

• 集群：涉及哪些模块／概念
• 耦合原因：共享类型、调用模式、共同拥有的概念
• 依赖类别：参见 REFERENCE.md 中的四种类别
• 测试影响：哪些现有测试将由边界测试取代

暂时不要提出接口。询问用户：“你想探索其中哪一个？”

3. 用户选择一个候选方案

4. 界定问题空间

在启动子 Agent 之前，先面向用户说明所选候选方案的问题空间：

• 新接口需要满足哪些约束
• 需要依赖哪些依赖项
• 提供一个粗略的示意代码片段，具体说明这些约束——这不是提案，只是为了让约束更清晰

向用户展示这些内容，然后立即进入第 5 步。子 Agent 并行工作时，用户可以阅读并思考。

5. 设计多个接口

使用 Agent 工具并行启动 3 个以上的子 Agent。每个子 Agent 都必须为深化后的模块设计一种截然不同的接口。

为每个子 Agent 提供单独的技术简报（文件路径、耦合细节、依赖类别、需要隐藏的内容）。这份简报独立于第 4 步面向用户的说明。为每个 Agent 设定不同的设计约束：

• Agent 1：“尽量精简接口——最多设计 1 到 3 个入口点”
• Agent 2：“尽可能灵活——支持多种用例并便于扩展”
• Agent 3：“针对最常见的调用方进行优化——让默认用例变得简单明了”
• Agent 4（如适用）：“针对跨边界依赖，围绕端口与适配器模式进行设计”

每个子 Agent 应输出：

1. 接口签名（类型、方法、参数）
2. 用法示例，展示调用方如何使用接口
3. 接口在内部隐藏的复杂性
4. 依赖策略（如何处理依赖项——参见 REFERENCE.md）
5. 权衡

依次展示各个设计，然后用文字进行比较。

比较之后，给出你自己的建议：你认为哪个设计最出色，以及原因。如果不同设计中的某些元素适合组合，可以提出混合方案。明确表达观点——用户需要的是有力的判断，而不只是选项列表。

6. 用户选择一个接口（或接受建议）

7. 编写 issue 文件

根据 REFERENCE.md 中的模板，将重构 RFC 写入 issues/ 下的本地 Markdown 文件。不要在写入前征求用户审阅——直接写入并告知文件路径。