# Design An Interface

> Generate multiple radically different interface designs for a module using sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions 'design it twice'.

- Skill: `xanticious/design-an-interface` (Agent Skill)
- Install (CLI): `npx skillmds@latest add xanticious/design-an-interface`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xanticious/design-an-interface/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: xanticious (https://skillmd.com/u/xanticious)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/xanticious/design-an-interface

---


# Design an Interface

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:

- [ ] 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?

Ask: "What does this module need to do? Who will use it?"

### 2. Generate Designs

Produce 3+ **radically different** designs sequentially. Each design must take a different constraint:

- Design 1: "Minimize method count — aim for 1–3 methods max"
- Design 2: "Maximize flexibility — support many use cases"
- Design 3: "Optimize for the most common case"
- Design 4 (optional): "Take inspiration from a specific paradigm or library"

For each design, output:

1. **Interface signature** (types, methods, params, invariants, error modes)
2. **Usage example** — how a caller actually uses it in practice
3. **What it hides** — complexity kept internal
4. **Trade-offs** of this approach

Use the Explore subagent to investigate the codebase for relevant context before generating each design.

### 3. Present Designs

Show each design with:

1. **Interface signature** — types, methods, params
2. **Usage examples** — how callers actually use it in practice
3. **What it hides** — complexity kept internal

Present designs sequentially so user can absorb each approach before comparison.

### 4. Compare Designs

After showing all designs, compare them on:

- **Interface simplicity**: fewer methods, simpler params
- **General-purpose vs specialized**: flexibility vs focus
- **Implementation efficiency**: does shape allow efficient internals?
- **Depth**: small interface hiding significant complexity (good) vs large interface with thin implementation (bad)
- **Ease of correct use** vs **ease of misuse**

Discuss trade-offs in prose, not tables. Highlight where designs diverge most.

### 5. Synthesize

Often the best design combines insights from multiple options. Ask:

- "Which design best fits your primary use case?"
- "Any elements from other designs worth incorporating?"

## 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 over-generalization.

**Implementation efficiency**: Does interface shape allow efficient implementation? Or force awkward internals?

**Depth**: Small interface hiding significant complexity = deep module (good). Large interface with thin implementation = shallow module (avoid).

## Anti-Patterns

- Don't produce similar designs — enforce radical difference between each
- Don't skip comparison — the value is in contrast
- Don't implement — this is purely about interface shape
- Don't evaluate based on implementation effort