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 them.
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
Before designing, understand:
Before designing, understand:
- What problem does this module solve?
What problem does this module solve?
- Who are the callers? (other modules, external users, tests)
Who are the callers? (other modules, external users, tests)
- What are the key operations?
What are the key operations?
- What are the constraints? (performance, compatibility, existing patterns)
Any constraints? (performance, compatibility, existing patterns)
- What should be hidden internally vs exposed externally?
What should be hidden inside vs exposed?
Ask: "What does this module need to do? Who will use it?"
Ask: "What does this module need to do? Who will use it?"
2. Generate Designs (Parallel Subagents)
Launch 3+ subagents simultaneously. Each must produce aradically differentapproach.
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. Present Designs
Present each design, including:
Show each design with:
- Interface signatures - types, methods, parameters
Interface signature - types, methods, params
- Usage examples - how callers use it in practice
Usage examples - how callers actually use it in practice
- What it hides - the complexity kept internal
What it hides - complexity kept internal
Present the designs in order so the user can understand each approach before comparing.
Present designs sequentially so user can absorb each approach before comparison.
4. Compare Designs
After presenting all designs, compare them in terms of:
After showing all designs, compare them on:
- Interface simplicity: fewer methods, simpler parameters
Interface simplicity: fewer methods, simpler params
- General-purpose vs special-purpose: flexibility vs focus
General-purpose vs specialized: flexibility vs focus
- Implementation efficiency: does the shape allow an efficient internal implementation?
Implementation efficiency: does shape allow efficient internals?
- Depth: small interface hiding major complexity (good) vs large interface with shallow implementation (bad)
Depth: small interface hiding significant complexity (good) vs large interface with thin implementation (bad)
- Easy to use correctly vs easy to misuse
Ease of correct use vs ease of misuse
Discuss trade-offs in prose, not tables. Highlight where the designs differ most.
Discuss trade-offs in prose, not tables. Highlight where designs diverge most.
5. Synthesize
Often the best design combines insights from multiple options. Ask:
Often the best design combines insights from multiple options. Ask:
- "Which design best fits your primary use case?"
"Which design best fits your primary use case?"
- "Are there elements from other designs worth incorporating?"
"Any elements from other designs worth incorporating?"
Evaluation Criteria
From A Philosophy of Software Design:
From "A Philosophy of Software Design":
Interface simplicity: fewer methods, simpler parameters = easier to learn and use correctly.
Interface simplicity: Fewer methods, simpler params = easier to learn and use correctly.
Generality: can handle future use cases without changes. But beware of over-generalization.
General-purpose: Can handle future use cases without changes. But beware over-generalization.
Implementation efficiency: does the interface shape allow efficient implementation? Or does it force the internal implementation to be awkward?
Implementation efficiency: Does interface shape allow efficient implementation? Or force awkward internals?
Depth: small interface hiding major complexity = deep module (good). Large interface with shallow implementation = shallow module (avoid).
Depth: Small interface hiding significant complexity = deep module (good). Large interface with thin implementation = shallow module (avoid).
Anti-Patterns
- Don't let subagents produce similar designs - enforce radical difference
Don't let sub-agents produce similar designs - enforce radical difference
- Don't skip the comparison - the value is in the contrast
Don't skip comparison - the value is in contrast
- Don't implement - this is purely about interface shape
Don't implement - this is purely about interface shape
- Do not evaluate based on implementation effort
Don't evaluate based on implementation effort