Lesson 5.1 — Why specs beat prompts (git for intent)

A prompt is the spoken trip; the spec is the map you keep.

TL;DR: A prompt is used once and evaporates; a spec is durable, re-runnable, and committed. At system scale the code is a regenerable output of the spec, so the spec is the artifact worth versioning.

ELI5 — prompt vs. spec

A prompt is directions you say out loud once; a spec is the map anyone can re-run.

	Prompt	Spec
Lifespan	one session, then gone	committed · durable
Re-run	re-typed differently each time	same input → same destination
Reviewed?	no	yes, like code
Analogy	spoken turn-by-turn directions	the map

   PROMPT                              SPEC
   ┌──────────────────────┐           ┌──────────────────────┐
   │ "add retries to the  │           │ # SPEC: payment       │
   │  payments client,    │   →→→      │   retries             │
   │  exponential I think"│           │ Goal / scope /        │
   └──────────────────────┘           │ contracts / verify    │
   used once, then gone               └──────────────────────┘
   re-typed differently each time      committed · re-runnable · reviewed

The core claim: code is regenerable, the spec is durable

Lose the code, keep the spec → an agent rebuilds it. Lose the spec → you have decisions with no record of why.

Spec Kit's own framing: "Specifications don't serve code — code serves specifications" — the implementation is the spec's expression in one language and framework ¹.

flowchart LR
    K{"What do you<br/>still have?"}
    K -->|"keep SPEC, lose code"| A["agent regenerates<br/>the implementation"] --> OK["✅ recoverable"]
    K -->|"keep code, lose SPEC"| B["decisions with no 'why'<br/>→ archaeology"] --> BAD["❌ guesswork"]

So the spec — not the chat log, not the diff — is the load-bearing artifact. You version it, review it, and argue over it, because it's the part that's expensive to reconstruct ¹.

"Git for intent." Git versions your code (the HOW-it-ended-up). A spec versions your intent (the WHAT-and-why). When intent has a diffable home, "why is this here?" stops being archaeology and becomes a git log on the spec.

🧠 Test Yourself: You delete the implementation but keep a HOW-free spec. Why is that recoverable, but the reverse (keep code, lose spec) is not?

Answer

The spec is the durable source of intent — an agent regenerates code from it ¹. Code alone records what was built but not why, so the next change becomes guesswork.

Worked example: this repo's own scaffolder

The scaffolder pinned a guarantee in a committed spec that no one-off prompt could survive.

Before a line of the scaffolder existed, someone wrote specs/002-scaffolder/spec.md:

Pinned in the spec	Why a prompt couldn't hold it
FR-009 — MUST offer the Spec Kit handoff and leave a complete scaffold whether accepted or declined	The "even when declined" nuance is exactly what gets dropped between sessions.
SC-008 — "Declining the hand-off still yields a complete, valid scaffold 100% of the time"	A testable promise that survives team turnover and model upgrades.

Six months out, an agent can regenerate the implementation from the spec and that guarantee still holds — because it lives in the artifact, not in someone's memory of a chat.

Why this scales when prompts don't

A prompt's reach is one session; a spec's reach is the lifetime of the system.

   one small change:        prompt is fine (Phase 1: small tasks skip the plan)
   a feature:               prompt rots across a long session (Phase 2: context rot)
   a system, over months:   only the spec survives team turnover, model upgrades,
                            and "wait, why did we build it this way?"

The bigger and longer-lived the work, the more the durable artifact wins — a quick prompt is the right tool only for the small, fast changes that don't even need a plan ².

Your turn (exercise)

Find a feature whose intent lives nowhere — not a doc, not a spec, just code and someone's head. Write the 5-line spec that should have existed: Goal, Scope, one Contract, one Constraint, one Verification. Then ask: hand only that to a fresh agent — could it regenerate the feature? If yes, you just turned tribal knowledge into git-for-intent.

---

← Phase 5 home · next → Lesson 5.2 — The Spec Kit loop

---

1. Spec-Driven Development methodology (spec-driven.md) — GitHub ↩↩↩

2. Best practices for Claude Code — Anthropic ↩