Design An Interface

Design An Interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Based on "Design It Twice" from "A Philosophy of Software Design": your first idea is unlikely to be the best.

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?
• Any constraints? (performance, compatibility, existing patterns)
• What should be hidden inside vs exposed?

2. Generate Designs (Parallel Sub-Agents)

Spawn 3+ sub-agents simultaneously. Each must produce a radically different approach.

Assign each agent a different constraint:

• 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 a specific paradigm/library"

3. Present Designs

Show each design with its interface signature, usage examples, hidden complexity, and trade-offs.

4. Compare and Select

Compare designs side by side. Ask: which is deepest? Easiest to use? Most maintainable? Pick one or hybridize.

Note: This skill is deprecated in the original source. Consider using codebase-design for deep module vocabulary instead.

Common Pitfalls

• Over-designing before understanding requirements: Jumping to interface designs without first gathering requirements leads to designs that don't solve the actual problem. Always complete the requirements checklist first.
• Sub-agent designs too similar: If spawned sub-agents produce similar designs, you lose the benefit of radical comparison. Enforce different constraints per agent.
• Ignoring what callers actually need: Designing interfaces without understanding who calls them and how leads to mismatched abstractions.

Code Examples

// Minimal interface approach
interface UserStore {
  get(id: string): Promise<User>;
  set(user: User): Promise<void>;
}

// Flexible approach
interface UserStore {
  find(query: UserQuery): Promise<User[]>;
  findOne(query: UserQuery): Promise<User | null>;
  create(data: CreateUserDTO): Promise<User>;
  update(id: string, data: Partial<User>): Promise<User>;
  delete(id: string): Promise<void>;
}

Verification Checklist

• Requirements gathered before design started
• At least 3 radically different designs generated
• Each design has interface signature, usage example, hidden complexity, and trade-offs
• User has compared designs and selected one