Part of Mechanisms of Vibe Coding

Mechanism: Interface-First

One-sentence definition

Interface-first means defining the contract — types, function signatures, route schemas, or module API — before the agent implements internals, so implementation fills a shape you already agreed on.

The problem

The agent implements getHealthDetails() returning a nested object with uptimeMs, startTime, and version. Your tests expected details.uptime in seconds. Rename churn, import thrash, and broken callers follow — all because the surface was discovered during coding, not before.

Implementation-first lets the model optimize locally visible code. Interface-first forces commitment to boundaries early.

Symptoms:

• Response shape changes between agent passes
• Refactors rename public fields after “completion”
• Multiple modules invent incompatible types for the same concept
• Tests written to match code instead of spec

How it works

Sequence for a new surface:

1. Define interface — TypeScript type, OpenAPI fragment, or typed function signature
2. Review — you or checkpoint on the contract only
3. Tests against interface — from examples or ACs
4. Agent implements — internals only; contract frozen unless you reopen step 1

  Interface (types / routes / public API)
       │
       ▼
  Review contract
       │
       ▼
  Tests lock contract
       │
       ▼
  Implementation (agent fills body)

For HTTP: define response type and route signature first. For modules: export types + stub functions returning throw new Error('unimplemented') or use test-driven stubs.

When to use it

• New public APIs, shared packages, SDK surfaces
• Multi-file features where callers depend on shape
• Agent sessions that tend to invent field names
• TypeScript, Go, Rust, or any typed stack — leverage the type checker as verify

When not to use it

• Internal private helpers with one caller — interface ceremony may not pay
• Exploratory spike — sketch implementation, then extract interface before merge
• When the contract is genuinely unknown — interface-first becomes guess-first; use examples + spike

Failure modes

Interface theater — Types that mirror whatever the agent wrote last pass. Fix: Write types before first implementation message.

Leaky implementation in interface — getHealthFromBootstrapSingleton() on public API. Fix: Domain-shaped names; hide internals.

Skipping review — Agent implements before you approve contract. Fix: Plan mode or separate “approve types” checkpoint.

Orphan interface — Types in a file nothing imports. Fix: First consumer test imports the type.

Interface drift mid-slice — Changing contract without versioning. Fix: Reopen interface step explicitly; update all tests.

Minimal example

Context: Verbose health details object.

Steps:

1. Add types first (agent or you):

   export type HealthDetails = { uptime: number };
   export type HealthResponse =
     | { ok: true; details?: HealthDetails }
     | { ok: false };

1. Update route handler signature to return HealthResponse; body throw or minimal stub.

1. Tests assert HealthResponse shapes from examples.

1. Agent session: “Implement handler bodies to satisfy existing types and tests; do not change exported types.”

Done when: Implementation compiles against frozen types; tests green.

Tool instances (optional deep-dive)

Portable idea above; this section is tool-specific. Date: June 2026.

Cursor

• Plan mode: Step 1 = types only; approve before build.
• @types file in first message; negative space on exported types.
• Rules: “Do not rename exported types without explicit request.”
• Generate OpenAPI from types or vice versa for HTTP APIs.

Other tools

Design-by-contract, protobuf-first, JSON Schema — same boundary-first discipline.

Related mechanisms

• Example-driven spec — examples inform the interface
• Vertical slice — interface + thin implementation in one slice
• Acceptance criteria — contract tests express ACs

Try it yourself

Exercise: For one upcoming change, write only the exported type or route schema in a scratch file. Stop. Review. Then allow implementation in a second step.

You need: Typed project or API route; five minutes

Done when: You have a contract file with zero implementation logic — or only not implemented stubs.