改善代码库架构
以AI的方式探索代码库,发现架构中的摩擦点,寻找改善可测试性的机会,并将模块深化重构提议作为GitHub issue RFC提出。
一个深度模块(John Ousterhout,《软件设计哲学》)的特点是:接口小而实现复杂。深度模块更易于测试,更利于AI导航,并且允许你在边界处而不是内部进行测试。
流程
1. 探索代码库
使用 Agent 工具,并设置 subagent_type=Explore 来自如地导航代码库。不要遵循僵化的启发式规则——而是有机地探索,并记录下你遇到摩擦的地方:
- 哪里需要你在多个小文件之间来回跳转才能理解一个概念?
- 哪些模块的接口和实现几乎一样复杂,显得过于“浅薄”?
- 哪些纯函数仅仅为了可测试性而被提取出来,但真正的bug却隐藏在它们的调用方式中?
- 哪些紧密耦合的模块在它们之间的接缝处带来了集成风险?
- 代码库的哪些部分未被测试,或者难以测试?
你所遇到的摩擦本身就是信号。
2. 呈现候选方案
列出一个编号的深化机会列表。对于每个候选方案,展示:
- 集群:涉及哪些模块/概念
- 耦合原因:共享的类型、调用模式、对某个概念的共同所有权
- 依赖类别:参见 REFERENCE.md 中的四个类别
- 测试影响:哪些现有测试将被边界测试所取代
不要在此阶段提出接口。询问用户:“你想深入探讨这些中的哪一个?”
3. 用户选择一个候选方案
4. 勾勒问题空间
在生成子代理之前,为用户撰写一份关于所选候选方案的问题空间说明:
- 任何新接口必须满足的约束条件
- 它需要依赖的依赖项
- 一个粗略的、用于说明约束的代码草图——这并非提案,只是让约束具体化的方式
向用户展示这些内容,然后立即进入第5步。用户在阅读、思考问题的同时,子代理们会并行工作。
5. 设计多种接口
使用 Agent 工具并行生成3个或以上的子代理。每个子代理都必须为深化后的模块设计一个完全不同的接口。
为每个子代理提供一个独立的技术简报(包含文件路径、耦合细节、依赖类别、以及要隐藏的内容)。这个简报与第4步中面向用户的说明无关。为每个代理指定不同的设计约束:
- 代理1:“最小化接口——目标是最多1-3个入口点”
- 代理2:“最大化灵活性——支持多种用例和扩展”
- 代理3:“为最常见的调用方优化——让默认情况变得简单明了”
- 代理4(如适用):“围绕端口与适配器模式设计跨边界依赖”
每个子代理输出:
- 接口签名(类型、方法、参数)
- 使用示例,展示调用方如何使用
- 它内部隐藏的复杂性
- 依赖策略(如何处理依赖项——参见 REFERENCE.md)
- 权衡取舍
将设计方案依次呈现,然后用文字进行比较。
比较之后,给出你自己的推荐:你认为哪个设计最强,以及原因。如果不同设计的元素可以很好地组合,提出一个混合方案。要有主见——用户想要的是一个有力的观点,而不仅仅是一个菜单供选择。
6. 用户选择一个接口(或接受推荐)
7. 创建GitHub issue
使用 gh issue create 创建一个重构RFC作为GitHub issue。使用 REFERENCE.md 中的模板。不要在创建之前要求用户审核——直接创建并分享URL。