Back to Details

design-an-interface

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Design an Interface

接口设计

Based on "Design It Twice" from "A Philosophy of Software Design": your first idea is unlikely to be the best. Generate multiple radically different designs, then compare.
基于《软件设计的哲学》中的“两次设计法”：你的第一个想法未必是最优解。请生成多种截然不同的设计方案，再进行对比。

Workflow

工作流程

1. Gather Requirements

1. 收集需求

Before designing, understand:
  • What problem does this module solve?
  • Who are the callers? (other modules, external users, tests)
  • What are the key operations?
  • Any constraints? (performance, compatibility, existing patterns)
  • What should be hidden inside vs exposed?
Ask: "What does this module need to do? Who will use it?"
在设计之前，需明确：
  • 该模块要解决什么问题？
  • 调用方是谁？（其他模块、外部用户、测试用例）
  • 核心操作有哪些？
  • 存在哪些约束？（性能、兼容性、现有设计模式）
  • 哪些逻辑应隐藏在内部，哪些需要对外暴露？
可提问：“该模块需要实现什么功能？谁会使用它？”

2. Generate Designs (Parallel Sub-Agents)

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

Spawn 3+ sub-agents simultaneously using Task tool. Each must produce a radically different 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
使用任务工具同时生成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. Present Designs

3. 展示设计方案

Show each design with:
  1. Interface signature - types, methods, params
  2. Usage examples - how callers actually use it in practice
  3. What it hides - complexity kept internal
Present designs sequentially so user can absorb each approach before comparison.
每个设计方案需包含：
  1. 接口签名 - 类型、方法、参数
  2. 使用示例 - 调用方实际使用的场景
  3. 隐藏逻辑 - 内部封装的复杂度
按顺序展示各设计方案，让用户在对比前充分理解每种思路。

4. Compare Designs

4. 对比设计方案

After showing all designs, compare them on:
  • Interface simplicity: fewer methods, simpler params
  • General-purpose vs specialized: flexibility vs focus
  • Implementation efficiency: does shape allow efficient internals?
  • Depth: small interface hiding significant complexity (good) vs large interface with thin implementation (bad)
  • Ease of correct use vs ease of misuse
Discuss trade-offs in prose, not tables. Highlight where designs diverge most.
展示所有方案后，从以下维度进行对比：
  • 接口简洁性：方法数量更少、参数更简单
  • 通用化vs专业化：灵活性与专注度的平衡
  • 实现效率：接口形态是否支持高效的内部实现？
  • 深度：隐藏大量复杂度的小型接口（优质）vs 实现单薄的大型接口（劣质）
  • 易用性：正确使用的便捷性vs误用的可能性
用文字描述对比结果，而非表格。重点突出各方案的核心差异。

5. Synthesize

5. 综合优化

Often the best design combines insights from multiple options. Ask:
  • "Which design best fits your primary use case?"
  • "Any elements from other designs worth incorporating?"
最优设计通常融合了多种方案的优势。可提问：
  • “哪种设计最贴合你的核心使用场景？”
  • “其他方案中有哪些元素值得借鉴？”

Evaluation Criteria

评估标准

From "A Philosophy of Software Design":
Interface simplicity: Fewer methods, simpler params = easier to learn and use correctly.
General-purpose: Can handle future use cases without changes. But beware over-generalization.
Implementation efficiency: Does interface shape allow efficient implementation? Or force awkward internals?
Depth: Small interface hiding significant complexity = deep module (good). Large interface with thin implementation = shallow module (avoid).
来自《软件设计的哲学》：
接口简洁性：方法更少、参数更简单=更易学习和正确使用。
通用化：无需修改即可应对未来的使用场景，但需注意避免过度通用化。
实现效率：接口形态是否支持高效实现？还是会导致内部逻辑尴尬？
深度：隐藏大量复杂度的小型接口=优质深度模块；实现单薄的大型接口=应避免的浅层模块。

Anti-Patterns

反模式

  • Don't let sub-agents produce similar designs - enforce radical difference
  • Don't skip comparison - the value is in contrast
  • Don't implement - this is purely about interface shape
  • Don't evaluate based on implementation effort
  • 不要让子Agent生成相似的设计方案——必须确保方案截然不同
  • 不要跳过对比环节——价值在于差异带来的启发
  • 不要进行开发实现——此流程仅聚焦于接口形态设计
  • 不要以开发成本作为评估标准