design-an-interface

设计接口

基于《A Philosophy of Software Design》中的“Design It Twice”：你的第一个想法很可能不是最好的。生成多个根本不同的设计，然后进行比较。

工作流

1. 收集需求

设计前先理解：

• 这个 module 要解决什么问题？
• 调用方是谁？（其他 module、外部用户、测试）
• 关键操作是什么？
• 有哪些约束？（性能、兼容性、现有模式）
• 哪些内容应该隐藏在内部，哪些应该公开？

询问：“这个 module 需要做什么？谁会使用它？”

2. 生成设计（并行子 Agent）

使用 Task 工具同时生成 3 个以上的子 Agent。每个子 Agent 都必须产出根本不同的方案。

Prompt template for each sub-agent:

Design an interface for: [module description]

Requirements: [gathered requirements]

Constraints for this design: [assign a different constraint to each agent]
- Agent 1: "Minimize method count - aim for 1-3 methods max"
- Agent 2: "Maximize flexibility - support many use cases"
- Agent 3: "Optimize for the most common case"
- Agent 4: "Take inspiration from [specific paradigm/library]"

Output format:
1. Interface signature (types/methods)
2. Usage example (how caller uses it)
3. What this design hides internally
4. Trade-offs of this approach

3. 展示设计

每个设计展示：

1. 接口签名 — 类型、方法、参数
2. 使用示例 — 调用方在实践中如何使用
3. 隐藏内容 — 保持在内部的复杂性

依次展示设计，让用户能在比较前充分了解每个方案。

4. 比较设计

展示所有设计后，按以下维度比较：

• 接口简洁性：更少的方法、更简单的参数
• 通用性与专用性：灵活性与专注度
• 实现效率：接口形态是否允许高效的内部实现？
• 深度：小接口隐藏大量复杂性（好）与大接口搭配薄实现（坏）
• 易于正确使用 与 易于误用

用文字讨论权衡取舍，不用表格。突出设计之间分歧最大的地方。

5. 综合

最好的设计往往会结合多个方案的优点。询问：

• “哪个设计最适合你的主要使用场景？”
• “其他设计中是否有值得合并的元素？”

评估标准

来自《A Philosophy of Software Design》：

接口简洁性：更少的方法、更简单的参数 = 更容易学习和正确使用。

通用性：无需改动即可处理未来的使用场景。但要警惕过度泛化。

实现效率：接口形态是否允许高效实现？还是会迫使内部实现变得别扭？

深度：小接口隐藏大量复杂性 = 深模块（好）。大接口搭配薄实现 = 浅模块（应避免）。

反模式

• 不要让子 Agent 产出相似的设计；要强制要求方案有根本差异
• 不要跳过比较；价值在于对比
• 不要实现；这里只讨论接口形态
• 不要根据实现工作量进行评价