设计一个接口（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 产出相似的设计——要强制根本差异
• 不要跳过对比——对比的价值在于“形成对照”
• 不要去实现——这项工作只关注接口形状
• 不要基于“实现成本/劳动量”去做评价