improve-codebase-architecture

改进代码库架构

像 AI 一样探索代码库，揭示架构摩擦，发现提升可测试性的机会，并提出模块深化重构 RFC。对于模块、接口、深度、接缝、适配器、杠杆效应和局部性等术语，请使用共享的 codebase-design 词汇，不要在此重新定义。

负责：对用户指定的一个领域进行有界调查、比较候选方案，并撰写相应的重构 RFC。 codebase-improver 仍是独立的、需人工把关的全仓库工作流；此技能不接手它的审计、实现或递归深化工作。

宿主可移植性

如果没有委派权限，则按顺序在线执行探索和设计阶段。在选择不同的工作者之前，先应用操作默认值。不要声称在线执行的阶段彼此独立或并行；如果结果的可靠性有赖于隔离，则应说明当前无法提供隔离。

流程

1. 探索代码库

从近期变更的热点入手：检查用户指定范围内尚未暂存的变更、已暂存的变更和近期提交。近期变更只是探索起点，并不能证明其具有架构重要性。只有当观察到的证据超出初始边界时才扩大范围，例如调用方、依赖、失败的测试或反复导航显示边界外存在耦合行为。每次扩大探索范围时，都要记录证据和新增范围。

在此边界内，默认采用自然、在线的方式探索。不要遵循僵化的启发式规则——自然探索，并记录你遇到的摩擦：

• 理解一个概念时，是否需要在许多小文件之间来回切换？
• 模块是否过于浅薄，以至于接口几乎和实现一样复杂？
• 是否只为便于测试而提取了纯函数，但真正的 bug 却隐藏在调用方式中？
• 紧密耦合的模块是否在接缝处带来了集成风险？
• 代码库的哪些部分未经测试或难以测试？

你遇到的摩擦就是信号。

2. 展示候选方案

以编号列表展示深化机会。对于每个候选方案，请说明：

• 集群：涉及哪些模块／概念
• 耦合原因：共享类型、调用模式、共同负责某个概念
• 依赖类别：使用共享的依赖类别
• 测试影响：哪些现有测试将由边界测试取代

此时不要提出接口。询问用户：“你想探索哪一个？”

默认情况下，可视化报告是可选且临时的。只有在图表或表格有助于理解候选方案之间的关系时，才在对话中使用。除非用户明确要求，否则不要创建或提交图表或表格。重构 RFC 是此工作流默认唯一的持久化产物。

3. 用户选择一个候选方案

4. 界定问题空间

在设计阶段开始之前，先面向用户说明所选候选方案的问题空间：

• 新接口需要满足的约束
• 新接口需要依赖的内容
• 一个用于具体说明约束的大致示例代码片段——这不是提案，只是帮助说明约束

向用户展示这些内容后，立即继续第 5 步。设计阶段运行期间，用户可以阅读这些内容。

5. 设计多个接口

运行 3 个或更多设计练习，默认依次内联执行。 获得明确的委派权限后，可使用不同的工作者并发执行。每个练习都应为经过深入梳理的模块提出一种截然不同的接口。

为每轮设计提供相同的技术简报（文件路径、耦合细节、依赖类别以及应隐藏的内容）。这份简报独立于第 4 步面向用户的说明。为每轮设计指定不同的约束：

• 第 1 轮：“尽量精简接口——最多设置 1 到 3 个入口点”
• 第 2 轮：“尽可能灵活——支持多种用例和扩展”
• 第 3 轮：“针对最常见的调用方优化——让默认用例简单易用”
• 第 4 轮（如适用）：“围绕端口和适配器设计，以处理跨边界依赖”

每轮设计都应输出：

1. 接口签名（类型、方法、参数）
2. 展示调用方如何使用该接口的示例
3. 接口在内部隐藏的复杂性
4. 依赖策略（如何处理依赖——参见 REFERENCE.md）
5. 权衡

依次呈现各个设计，然后用文字进行比较。

比较之后，给出你自己的建议：你认为哪种设计最出色，理由是什么。如果不同设计的某些元素可以很好地组合，请提出一个混合方案。明确表达观点——用户想要的是有力的判断，而不只是选项列表。

6. 用户选择一个接口（或接受建议）

7. 创建重构 RFC

在 docs/ 文件夹中创建一个 Markdown 文件作为重构 RFC。使用 REFERENCE.md 中的模板。创建前不要要求用户审阅；直接创建并告知文件路径。