SuperAPI AI Directory

design-an-interface

Coding & development

View repository

Updated 10-16 09:45

About this skill

Design an Interface

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:

  1. Interface signature — types、methods、params
  2. Usage examples — how callers use it in practice
  3. 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