design-an-interface

Design an Interface

Based on "Design Twice" from "A Philosophy of Software Design": your first idea is unlikely to be the best. Generate multiple distinctly different designs, then compare them.

Workflow

1. Gather Requirements

Before designing, understand:

• What problem does this module solve?
• Who are the callers? (other modules, external users, tests)
• What are the key operations?
• What constraints are there? (performance, compatibility, existing patterns)
• What should be hidden internally vs exposed?

Ask: "What does this module need to do? Who will use it?"

2. Generate Designs (Parallel Subagents)

Use the Task tool to generate 3+ subagents simultaneously. Each must produce adistinctly differentapproach.

每个子代理的提示模板：

为以下模块设计一个接口：[模块描述]

需求：[收集的需求]

此设计的约束：[为每个代理分配不同的约束]
- 代理 1："最小化方法数量 - 最多目标 1-3 个方法"
- 代理 2："最大化灵活性 - 支持多种用例"
- 代理 3："优化最常见的情况"
- 代理 4："从[特定范式/库]中汲取灵感"

输出格式：
1. 接口签名（类型/方法）
2. 使用示例（调用者如何使用它）
3. 此设计在内部隐藏了什么
4. 此方法的权衡

3. Present Designs

When presenting each design, include:

1. Interface signatures - types, methods, parameters
2. Usage examples - how callers actually use it in practice
3. What it hides - the complexity kept internal

Present the designs in order so that the user can absorb each approach before comparing them.

4. Compare Designs

After presenting all designs, compare them in terms of:

• Interface simplicity: fewer methods, simpler parameters
• General vs specialized: flexibility vs focus
• Implementation efficiency: does the shape allow for an efficient internal implementation?
• Depth: a small interface hiding significant complexity (good) vs a large interface with a thin implementation (bad)
• Ease of correct use vs Ease of misuse

Discuss the trade-offs in prose, not tables. Highlight where the designs diverge the most.

5. Synthesize

Often the best design combines insights from multiple options. Ask:

• "Which design best fits your primary use case?"
• "Are there elements from other designs worth merging in?"

Evaluation Criteria

From "A Philosophy of Software Design":

Interface simplicity: fewer methods, simpler parameters = easier to learn and use correctly.

Generality: handles future use cases without changes. But beware of over-generalization.

Implementation efficiency: does the interface shape allow for an efficient implementation? Or does it force an awkward internal implementation?

Depth: a small interface hiding significant complexity = deep module (good). A large interface with a thin implementation = shallow module (avoid).

Anti-patterns

• Don't let subagents produce similar designs - enforce distinctly different differences
• Don't skip the comparison - the value is in the contrast
• Don't implement - this is purely about interface shape
• Don't evaluate based on implementation effort