Based on the "design two versions" idea from A Philosophy of Software Design: your first idea is unlikely to be the best. Generate multiple sharply different designs, then compare.
Workflow
1. Gather requirements
Before designing, first 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 sub-agents)
Use the Task tool to launch 3 or more sub-agents at the same time. Each must produce asharply differentoption.
每个子 agent 的 prompt 模板：
为以下模块设计接口：[模块描述]
需求：[收集到的需求]
此设计的约束：[为每个 agent 分配不同的约束]
- Agent 1："最小化方法数量——最多 1-3 个方法"
- Agent 2："最大化灵活性——支持多种使用场景"
- Agent 3："针对最常见场景优化"
- Agent 4："从 [特定范式/库] 中汲取灵感"
输出格式：
1. 接口签名（类型/方法）
2. 使用示例（调用者如何使用）
3. 此设计隐藏的内部实现
4. 此方案的权衡取舍
3. Present the designs
For each design present:
- Interface signatures- types, methods, parameters
- Usage examples- how callers use it in practice
- What is hidden- the complexity left internal
Present the designs one at a time so the user can digest each option before comparing.
4. Compare the designs
After presenting all the designs, compare them along the following dimensions:
- Interface simplicity: fewer methods, simpler parameters
- General vs. special-purpose: flexibility vs. focus
- Implementation efficiency: does the interface shape allow an efficient internal implementation?
- Depth: a small interface hiding a lot of complexity (good) vs. a large interface with only a thin layer of implementation (avoid)
- Ease of correct use vs. Ease of misuse
Discuss the trade-offs in prose rather than tables. Highlight where the designs diverge the most.
5. Synthesize
Usually the best design blends insights from multiple options. Ask:
- "Which design best fits your primary use case?"
- "Are there elements from other designs worth incorporating?"
Evaluation criteria
From A Philosophy of Software Design:
Interface simplicity: fewer methods, simpler parameters = easier to learn and use correctly.
Generality: able to handle future use cases without changes. But be careful to avoid over-generalization.
Implementation efficiency: does the interface shape allow an efficient implementation? Or does it force the internal implementation into something awkward?
Depth: a small interface hiding a lot of complexity = deep module (good). A large interface with only a thin layer of implementation = shallow module (avoid).
Anti-patterns
- Don't let the sub-agents produce similar designs-forcibly require them to be sharply different
- 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