design-an-interface

# 设计一个接口（Design an Interface）

基于《A Philosophy of Software Design》里的 “Design It Twice（把它设计两遍）”：你的第一个想法通常不会是最好的。生成多个根本不同的设计方案，然后进行对比。

## 工作流（Workflow）

### 1. 收集需求（Gather Requirements）

在开始设计前先理解：

- [ ] 这个模块解决什么问题？
- [ ] 谁会作为调用方？（其他模块、外部用户、测试）
- [ ] 关键操作是什么？
- [ ] 有哪些约束？（性能、兼容性、既有模式）
- [ ] 应当隐藏什么、暴露什么？

提问：`这个模块需要做什么？谁会使用它？`

### 2. 生成设计方案（并行子代理 Parallel Sub-Agents）

使用 Task 工具并行启动 3 个以上的子 agent。每个子 agent 都必须产出**根本不同（radically different）**的方案。

```
给每个子 agent 的提示模板：

为以下内容设计一个接口：[模块描述]

需求：[已收集到的需求]

为这个设计分配约束：[给每个 agent 设定不同的约束]

- Agent 1: "尽量减少方法数量——目标是最多 1-3 个方法"
- Agent 2: "尽量提升灵活性——支持很多用例"
- Agent 3: "为最常见的场景优化"
- Agent 4: "借鉴 [特定范式/库] 的思路"

输出格式：
1. 接口签名（types/methods）
2. 用法示例（调用方如何使用）
3. 该设计内部隐藏了什么复杂度
4. 采用该方式的取舍（trade-offs）
```

### 3. 展示设计方案

分别展示每个设计：

1. **接口签名**：类型、方法、参数
2. **使用示例**：调用方在实践里如何使用
3. **隐藏了什么**：将复杂度保留在内部

让用户在对比之前先逐个理解每种方案的含义，因此展示顺序应按方案逐一给出。

### 4. 对比设计方案

在展示完全部设计后，从这些维度进行对比：

- **接口简洁性**：更少的方法、更简单的参数
- **通用型 vs 专用型**：灵活性 vs 专注度
- **实现效率**：这种形状是否允许高效实现？
- **深度（Depth）**：小接口隐藏显著复杂度（好） vs 大接口但实现很薄（坏）
- **正确使用的容易度** vs **被误用的容易度**

请用文字（prose）讨论取舍，而不是用表格。重点指出不同设计最分歧的地方。

### 5. 归纳（Synthesize）

通常最好的设计会融合多个选项的洞见。追问：

- 哪个设计最符合你的主要使用场景？
- 是否有来自其他设计、值得纳入的元素？

## 评价标准（Evaluation Criteria）

来自《A Philosophy of Software Design》：

- **接口简洁性（Interface simplicity）**：方法更少、参数更简单 => 更容易学习与正确使用。
- **通用型（General-purpose）**：在不改动接口的前提下能覆盖未来用例。但要警惕过度通用。
- **实现效率（Implementation efficiency）**：接口的形状是否能让实现变得高效？还是迫使你在内部做尴尬的权衡？
- **深度（Depth）**：小接口隐藏显著复杂度 => 深模块（good）。大接口但实现很薄 => 浅模块（avoid）。

## 反模式（Anti-Patterns）

- 不要让子 agent 产出相似的设计——要强制根本差异
- 不要跳过对比——对比的价值在于“形成对照”
- 不要去实现——这项工作只关注接口形状
- 不要基于“实现成本/劳动量”去做评价