code-arch-optimizerlisted

# 代码库架构深度重构 像 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) 中的模板。不要让用户在创建前审阅——直接创建并分享链接。