Back to Details

design-an-interface

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Design an Interface

设计接口

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

Workflow

工作流程

1. Gather Requirements

1. 收集需求

设计前先理解：
  • 这个 module 解决什么问题？
  • callers 是谁？（other modules、external users、tests）
  • key operations 是什么？
  • 有哪些 constraints？（performance、compatibility、existing patterns）
  • 什么应该隐藏在内部，什么应该暴露？
询问：“这个 module 需要做什么？谁会使用它？”
设计前先理解：
  • 这个module要解决什么问题？
  • 调用者是谁？（其他模块、外部用户、测试用例）
  • 核心操作有哪些？
  • 存在哪些约束条件？（性能、兼容性、现有模式）
  • 哪些内容应该隐藏在内部，哪些需要暴露？
询问用户：“这个module需要实现什么功能？谁会使用它？”

2. Generate Designs (Parallel Sub-Agents)

2. 生成设计方案（Parallel Sub-Agents）

使用 Task tool 同时生成 3+ 个 sub-agents。每个都必须产出根本不同的 approach。
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
使用Task工具同时生成3个及以上sub-agents。每个sub-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. Present Designs

3. 展示设计方案

每个 design 展示：
  1. Interface signature — types、methods、params
  2. Usage examples — callers 在实践中如何使用
  3. What it hides — 保持在内部的 complexity
顺序展示 designs，让用户能在比较前吸收每个 approach。
每个设计方案需展示：
  1. 接口签名——类型、方法、参数
  2. 使用示例——调用者在实际场景中如何使用
  3. 内部隐藏内容——被封装在内部的复杂度
按顺序展示设计方案，让用户在比较前能充分理解每个设计思路。

4. Compare Designs

4. 对比设计方案

展示所有 designs 后，按以下维度比较：
  • Interface simplicity：更少 methods、更简单 params
  • General-purpose vs specialized：flexibility vs focus
  • Implementation efficiency：shape 是否允许高效 internals？
  • Depth：小 interface 隐藏大量 complexity（好）vs 大 interface 配薄 implementation（坏）
  • Ease of correct use vs ease of misuse
用 prose 讨论 trade-offs，不用 tables。突出 designs 分歧最大的地方。
展示所有设计方案后，从以下维度进行对比：
  • 接口简洁性：方法数量更少、参数更简单
  • 通用型 vs 专用型：灵活性 vs 专注度
  • 实现效率：接口形态是否允许高效的内部实现？
  • 深度：小接口隐藏大量复杂度（优质模块）vs 大接口搭配轻量实现（劣质模块）
  • 易用性 vs 误用风险
用文字讨论各方案的权衡，不要使用表格。重点突出设计方案分歧最大的部分。

5. Synthesize

5. 整合优化

最好的 design 往往结合多个 options 的 insights。询问：
  • “哪个 design 最适合你的 primary use case？”
  • “其他 designs 中是否有值得合并的 elements？”
最优的设计方案往往融合了多个选项的优势。询问用户：
  • “哪个设计方案最符合你的核心使用场景？”
  • “其他设计方案中是否有值得整合的元素？”

Evaluation Criteria

评估标准

来自 “A Philosophy of Software Design”：
Interface simplicity：更少 methods、更简单 params = 更容易学习和正确使用。
General-purpose：能不改动就处理未来 use cases。但要警惕 over-generalization。
Implementation efficiency：interface shape 是否允许高效 implementation？还是迫使 internals 变别扭？
Depth：小 interface 隐藏大量 complexity = deep module（好）。大 interface 配薄 implementation = shallow module（避免）。
来自《A Philosophy of Software Design》：
接口简洁性：方法更少、参数更简单 = 更易于学习和正确使用。
通用型：无需修改即可应对未来的使用场景。但要警惕过度泛化。
实现效率：接口形态是否允许高效的实现？还是会迫使内部实现变得繁琐？
深度：小接口隐藏大量复杂度 = 深度模块（优质）。大接口搭配轻量实现 = 浅层模块（需避免）。

Anti-Patterns

反模式

  • 不要让 sub-agents 产出相似 designs；强制 radical difference
  • 不要跳过 comparison；价值在 contrast
  • 不要 implement；这里只讨论 interface shape
  • 不要基于 implementation effort 评价
  • 不要让sub-agents产出相似的设计方案；必须强制要求截然不同的思路
  • 不要跳过对比环节；价值在于对比差异
  • 不要进行实现；此处仅讨论接口形态
  • 不要基于实现成本进行评价