zacczakk/metronome/interface-design

Interface Design

Overview

First designs are usually local maxima. Design the interface more than once, compare alternatives by leverage and locality, then choose deliberately.

Vocabulary

When to Use

• User asks for API, CLI, schema, adapter, module, or state-machine design.
• A decision would be expensive to reverse once implemented.
• Tests are hard to write because the interface is unclear.
• Multiple callers or integrations will depend on the shape.

Do not use for small internal helpers where the interface is obvious and cheap to change.

Process

1. Frame the problem space for the user:

• constraints the interface must satisfy
• likely callers
• invariants and error modes
• what should sit behind the seam

1. Generate at least three materially different alternatives. Use parallel subagents only when the boundary is complex enough that independent perspectives justify the coordination cost:

• Minimal interface: 1-3 entry points, maximum leverage.
• Flexible interface: supports extension and varied callers.
• Common-case interface: optimizes the dominant caller path.
• Adapter-oriented interface: useful when external systems vary.

1. Require each subagent to return:

• interface shape
• usage example
• hidden implementation responsibilities
• dependency/adapters strategy
• tradeoffs

1. Compare alternatives by depth, locality, seam placement, test surface, and failure modes.
2. Recommend one design or a small hybrid. Do not dump options without a strong read.

Evaluation Heuristics

• Deletion test: if deleting the module removes complexity, it was probably pass-through. If complexity reappears across callers, it was earning its keep.
• One adapter means a hypothetical seam. Two adapters means a real seam.
• The interface is the test surface. If tests must pierce it, the shape is wrong.
• Avoid interfaces that expose ordering constraints callers should not need to know.
• Prefer narrow interfaces that make invalid states hard to represent.

Output Shape

## Recommendation
 
Choose Design B because ...
 
## Alternatives Compared
 
1. Minimal interface — strengths, weaknesses
2. Flexible interface — strengths, weaknesses
3. Common-case interface — strengths, weaknesses
 
## Interface Sketch
 

// concise sketch only

 
## Tradeoffs
 
- What this hides well
- What remains explicit
- What would force redesign later

Common Mistakes