design-an-interface

设计接口

基于《软件设计哲学》中的“设计两次”：你的第一个想法很可能不是最佳方案。生成多个截然不同的设计，然后进行比较。

工作流

1. 收集需求

设计前，请了解：

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

询问：“此模块需要做什么？谁会使用它？”

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. 综合

最佳设计往往会融合多个方案中的优点。询问：

• “哪种设计最符合你的主要使用场景？”
• “其他设计中有哪些值得纳入的元素？”

评估标准

来自《软件设计哲学》：

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

通用性：无需更改即可应对未来用例。但要警惕过度泛化。

实现效率：接口形式是否支持高效实现？还是会导致内部实现别扭？

深度：小型接口隐藏大量复杂性 = 深层模块（好）。大型接口仅有简单实现 = 浅层模块（应避免）。

反模式

• 不要让子 Agent 生成相似设计——必须确保差异显著
• 不要跳过比较——价值在于对比
• 不要实现——这纯粹关乎接口形式
• 不要根据实现工作量来评估