| name | code-arch-optimizer |
| description | 探索代码库，识别架构摩擦点，并通过“加深浅模块”来提升可测试性，最终输出包含多种接口设计方案的详细重构建议与GitHub Issue RFC。当用户希望改进架构、寻找重构机会、合并紧耦合模块，或让代码库更易于AI导航和理解时触发。 |
代码库架构深度重构
像 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 中的模板。不要让用户在创建前审阅——直接创建并分享链接。
