Code Arch Optimizer

---
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](REFERENCE.md) 中的四种分类
- **测试影响**：哪些现有测试将被边界测试替代

此时不要提出接口设计。问用户："你想深入探索哪一个？"

### 3. 用户选择候选项

### 4. 描述问题空间

在启动子代理之前，为用户编写所选候选项的问题空间说明：

- 任何新接口需要满足的约束条件
- 需要依赖的外部依赖
- 一个粗略的示意代码草图，使约束条件更加具体——这不是正式方案，只是用来让约束可感知

向用户展示后，立即进入第 5 步。用户可以在阅读和思考问题的同时，让子代理并行工作。

### 5. 设计多种接口方案

使用 Agent 工具并行启动 3 个以上子代理。每个子代理必须为深化后的模块产出一个**截然不同**的接口方案。

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

- 代理 1："最小化接口——目标是最多 1-3 个入口点"
- 代理 2："最大化灵活性——支持多种用例和扩展"
- 代理 3："针对最常见的调用方优化——让默认场景极简"
- 代理 4（如适用）："围绕端口与适配器模式设计跨边界依赖"

每个子代理输出：

1. 接口签名（类型、方法、参数）
2. 使用示例，展示调用方如何使用
3. 内部隐藏了哪些复杂度
4. 依赖策略（如何处理依赖——参见 [REFERENCE.md](REFERENCE.md)）
5. 权衡取舍

依次展示各方案，然后用文字进行对比分析。

对比完成后，给出你自己的推荐：你认为哪个方案最优，理由是什么。如果不同方案中的元素可以很好地组合，提出一个混合方案。要有立场——用户需要的是有力的判断，而不仅仅是一份菜单。

### 6. 用户选择接口方案（或接受推荐）

### 7. 创建 GitHub Issue

使用 `gh issue create` 创建重构 RFC 的 GitHub Issue。使用 [REFERENCE.md](REFERENCE.md) 中的模板。不要让用户在创建前审阅——直接创建并分享链接。