用途
code-arch-optimizer 用于对代码库进行架构层面的深度重构探索:发现架构摩擦点,识别可测试性改进机会,并以 GitHub Issue RFC 的形式提出“加深浅模块”的重构方案。它适合在用户希望改进架构、寻找重构机会、合并紧耦合模块,或让代码库更易于 AI 导航和理解时使用。
核心理念
深模块(出自 John Ousterhout《软件设计哲学》)指接口简洁但隐藏大量实现细节的模块。深模块更易测试、更便于 AI 导航,并且可以在边界处测试,而无需深入内部。
主要流程
1. 探索代码库
使用 Agent 工具(subagent_type=Explore)自然地浏览代码库,以有机方式探索,留意遇到摩擦的地方,例如:
- 理解一个概念需要在许多小文件之间来回跳转;
- 模块过于浅薄,接口几乎和实现一样复杂;
- 纯函数仅为可测试性被提取,真正的 bug 却藏在调用方式中;
- 紧耦合模块在接缝处产生集成风险;
- 代码库部分区域缺少测试或难以测试。
2. 展示候选项
以编号列表展示深化机会,每个候选项说明:聚类(涉及的模块/概念)、耦合原因(共享类型、调用模式、概念共同归属)、依赖类别(参见 REFERENCE.md 中的四种分类)、测试影响(哪些现有测试将被边界测试替代)。此时不提出接口设计,并询问用户想深入探索哪一个。
3. 用户选择候选项
4. 描述问题空间
在启动子代理前,为用户编写所选候选项的问题空间说明:新接口需满足的约束条件、需要依赖的外部依赖、一个粗略的示意代码草图(用于让约束可感知,并非正式方案)。展示后立即进入第 5 步,用户可在阅读思考的同时让子代理并行工作。
5. 设计多种接口方案
使用 Agent 工具并行启动 3 个以上子代理,每个子代理为深化后的模块产出截然不同的接口方案,并获得独立的技术简报(文件路径、耦合细节、依赖类别、需要隐藏的内容)。不同代理设定不同设计约束:
- 代理 1:最小化接口,目标最多 1-3 个入口点;
- 代理 2:最大化灵活性,支持多种用例和扩展;
- 代理 3:针对最常见调用方优化,让默认场景极简;
- 代理 4(如适用):围绕端口与适配器模式设计跨边界依赖。
每个子代理输出:接口签名(类型、方法、参数)、使用示例、内部隐藏的复杂度、依赖策略(参见 REFERENCE.md)、权衡取舍。随后依次展示各方案,进行文字对比分析,并给出自己的推荐与理由;若元素可组合,可提出混合方案。
6. 用户选择接口方案(或接受推荐)
7. 创建 GitHub Issue
使用 gh issue create 创建重构 RFC 的 GitHub Issue,使用 REFERENCE.md 中的模板。按流程不要求用户在创建前审阅,直接创建并分享链接。
适用场景
- 改进现有代码库架构;
- 寻找并评估重构机会;
- 合并紧耦合模块;
- 提升代码库可测试性与 AI 可导航性。
限制与说明
关于收费、支持平台、具体安装方式等事实暂未提供;依赖分类细节与 GitHub Issue 模板需参考其 REFERENCE.md。