Part of Mechanisms of Vibe Coding

Mechanism: Example-Driven Spec

One-sentence definition

An example-driven spec defines behavior through concrete input/output pairs (and edge cases) before implementation — so the agent builds toward named examples instead of guessing what “correct” means.

The problem

You ask for “proper error handling” on the health route. The agent returns generic 500 JSON, HTML errors, or swallows failures — all “valid” interpretations. You wanted { ok: false, error: "not_ready" } when startup is incomplete.

Abstract requirements invite model priors. Examples anchor behavior: request in, response out, status code included.

Symptoms:

• Surprises in response shape, status codes, or error messages
• Long debates about what the API “should” do
• Tests that assert implementation details instead of behavior
• Agent invents field names you did not want

How it works

List examples in a table or bullet block — include happy path, edge, and failure:

GET /health
  → 200 { "ok": true }

GET /health?verbose=1 (ready)
  → 200 { "ok": true, "details": { "uptime": 42 } }

GET /health?verbose=1 (not ready)
  → 200 { "ok": false }   // no details when not ok

GET /health?verbose=invalid
  → 400 { "error": "invalid_verbose" }

Implementation order:

1. Write examples (spec)
2. Write or extend tests from examples
3. Agent implements until tests match examples
4. Verify loop on the example suite

Examples can become acceptance criteria directly — each row is one criterion.

When to use it

• APIs, parsers, validators, formatters, CLI output
• Whenever stakeholders can say “like this request, expect that response”
• Before agent implementation on behavior-heavy code
• Teaching the agent your project’s JSON/error conventions

When not to use it

• Pure refactors with unchanged behavior — point at existing tests instead
• UI layout with subjective taste — examples help for states, not pixels
• Security-sensitive examples with real secrets — use synthetic fixtures

Failure modes

Too few examples — Only happy path; edge cases ship broken. Fix: Add at least one failure and one boundary example.

Examples as implementation — Giant JSON pasted into production code. Fix: Tests assert behavior; code stays clean.

Contradictory examples — Row 2 and row 4 disagree. Fix: Resolve spec before prompting.

Stale examples — Spec from old API version. Fix: Version the spec block or date it.

Missing status/metadata — Body-only examples omit 404 vs 400. Fix: Include status, headers when they matter.

Minimal example

Context: Verbose health query param behavior.

Steps:

1. Paste example block (four rows above) as the spec — no “implement health” yet.

1. Prompt: “Add tests for each example row, then implement health.ts to match.”

1. Verify: each example row has a test; all green.

Done when: A new teammate could predict responses from the example block alone.

Tool instances (optional deep-dive)

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

Cursor

• Example block at top of chat beats prose requirements.
• Test-first agent prompt: “Generate tests from these examples only; then implement.”
• Store canonical examples in docs/api-examples.md or next to route for anchor reuse.

Other tools

JSON Schema from examples, contract tests (Pact), doctest — formalizations of the same idea.

Related mechanisms

• Acceptance criteria — examples often become AC rows
• Interface-first — types can encode example shapes
• Verify loop — example tests are the verify step

Try it yourself

Exercise: Pick one function or endpoint. Write four examples: success, edge, failure, invalid input. No code until examples are written.

You need: One behavior to specify; five minutes

Done when: Someone could write tests from your examples without reading source code.