skillhub-094-improve-codebase-architecture/INTERFACE-DESIGN.md

# 接口设计

当用户想要为选定的深化候选项探索替代接口时，使用此并行子代理模式。基于「设计两次」（Ousterhout）——你的第一个想法不太可能是最佳方案。

使用 [LANGUAGE.md](LANGUAGE.md) 中的词汇——**模块**、**接口**、**接缝**、**适配器**、**杠杆**。

## 流程

### 1. 界定问题空间

在生成子代理之前，为选定的候选项撰写面向用户的问题空间说明：

- 任何新接口需要满足的约束条件
- 它所依赖的依赖项，以及这些依赖项属于哪个类别（参见 [DEEPENING.md](DEEPENING.md)）
- 一个粗略的示意代码草图，用于具象化约束条件——不是提案，只是让约束条件更具体的一种方式

向用户展示此内容，然后立即进入第 2 步。用户在阅读和思考的同时，子代理并行工作。

### 2. 生成子代理

使用 Agent 工具并行生成 3 个或更多子代理。每个子代理必须为深化后的模块生成一个**截然不同**的接口。

为每个子代理提供单独的技术简报（文件路径、耦合细节、[DEEPENING.md](DEEPENING.md) 中的依赖类别、接缝背后隐藏的内容）。该简报独立于第 1 步中面向用户的问题空间说明。为每个代理指定不同的设计约束：

- 代理 1：「最小化接口——最多 1-3 个入口点。最大化每个入口点的杠杆效应。」
- 代理 2：「最大化灵活性——支持多种使用场景和扩展。」
- 代理 3：「针对最常见的调用者进行优化——让默认情况变得微不足道。」
- 代理 4（如适用）：「围绕端口和适配器设计，以处理跨接缝依赖。」

在简报中同时包含 [LANGUAGE.md](LANGUAGE.md) 词汇和 CONTEXT.md 词汇，使每个子代理的命名与架构语言以及项目的领域语言保持一致。

每个子代理输出：

1. 接口（类型、方法、参数——以及不变约束、顺序、错误模式）
2. 使用示例，展示调用者如何使用
3. 实现隐藏在接缝背后的内容
4. 依赖策略和适配器（参见 [DEEPENING.md](DEEPENING.md)）
5. 权衡——哪些地方杠杆效应高，哪些地方薄弱

### 3. 展示与比较

依次展示设计方案，以便用户逐一理解，然后用散文形式进行比较。按**深度**（接口处的杠杆效应）、**局部性**（变化集中的位置）和**接缝位置**进行对比。

比较之后，给出你自己的建议：你认为哪个设计最强，以及理由。如果不同设计中的元素可以很好地组合，提出一个混合方案。要有主见——用户想要的是一个有力的判断，而不是一份菜单。