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