Design the Interface With Claude Before Writing Any Code

A planning move: use Claude to nail down the public interface, data shapes, and boundaries of a component before a single line of implementation is written.

Most bad code comes from a bad interface, and interfaces are cheap to change in a conversation but expensive to change in a codebase. Designing first means the later generation step (see 'Generate a full module from a spec') has a solid target.

New components, new services, or anywhere multiple parts must agree on a contract. Best when the cost of getting the shape wrong is high.

Throwaway scripts or one-off glue code where the interface has no future consumers. Designing there is over-engineering.

I'm about to build <component>. Before we write code, help me design it.

Context: <what it connects to>.
Goals: <what it must do>.
Constraints: <perf, team, deps>.

Propose the public interface only — signatures, data shapes, and the boundary between this and its callers. List the three most important trade-offs and your recommended default for each. Do not write the implementation yet.

Before building a notifications service, Claude proposes a Notifier interface with a single send(channel, payload) method, flags the sync-vs-queue trade-off, and recommends a queue — letting you approve the shape before any code exists.

Have Claude produce two designs — a minimal one and a more extensible one — and argue for each. Choosing between concrete alternatives is faster and sharper than critiquing a single proposal in the abstract.

• Letting Claude jump straight to implementation, so the interface is an accident of the first draft.
• Approving a design without stating constraints, then discovering it can't meet your latency or team needs.
• Designing for imagined future requirements instead of the ones you actually have.