deep-module-refactor

改进代码库架构

像 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. 创建 GitHub issue

使用 gh issue create 创建 GitHub issue，提交重构 RFC。使用 REFERENCE.md 中的模板。创建前不要要求用户审核——直接创建并分享 URL。