Based on "Design It Twice" from "A Philosophy of Software Design": your first idea is probably not the best. Generate multiple fundamentally different designs, then compare.
Workflow
1. Gather Requirements
Understand before designing:
- 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, and what should be exposed?
Ask: "What does this module need to do? Who will use it?"
2. Generate Designs (Parallel Sub-Agents)
Use the Task tool to generate 3+ sub-agents simultaneously. Each must produce afundamentally differentapproach.
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
Each design shows:
- Interface signature — types、methods、params
- Usage examples — how callers use it in practice
- What it hides — the complexity kept internal
Present the designs in order so the user can absorb each approach before comparing.
4. Compare Designs
After presenting all designs, compare along the following dimensions:
- Interface simplicity: fewer methods, simpler params
- General-purpose vs specialized:flexibility vs focus
- Implementation efficiency: does the shape allow efficient internals?
- Depth: a small interface hiding a lot of complexity (good) vs a large interface with a thin implementation (bad)
- Ease of correct use vs ease of misuse
Discuss trade-offs in prose, not tables. Highlight where the designs diverge the most.
5. Synthesize
The best design often 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 params = easier to learn and use correctly.
General-purpose: can handle future use cases without changes. But beware of over-generalization.
Implementation efficiency: does the interface shape allow an efficient implementation? Or does it force the internals to become awkward?
Depth: a small interface hiding a lot of complexity = deep module (good). A large interface with a thin implementation = shallow module (avoid).
Anti-Patterns
- Don't let sub-agents produce similar designs; force radical difference
- Don't skip the comparison; the value is in the contrast
- Don't implement; here only discuss interface shape
- Don't evaluate based on implementation effort