Specs over Prompts
A prompt controls one agent for one session, then evaporates. A spec file controls every agent, every session, every tool, for the life of the feature. Once you delegate anything larger than a bounded change, the spec — not the prompt — is where your leverage lives. The prompt shrinks to a pointer: Implement specs/spending-alerts.md. Ask before deviating.
Prompts vs Specs covers the conceptual split. This page makes the operational and economic case, and tells you when to skip the spec entirely.
What a prompt structurally cannot do
| Property | Prompt in chat | Committed spec file |
|---|---|---|
| Lifespan | One session; gone from context on /clear | As long as the feature exists |
| Reviewable | No — lives in your scrollback, invisible to the team | Yes — it's a file in a PR; a teammate can veto the intent before code exists |
| Reusable | Retyped from memory each session, drifting each time | implement per specs/x.md — identical input to every session, agent, and tool |
| Versioned | No history; "what did I ask for in March?" is unanswerable | git log specs/x.md answers it |
| Cross-tool | Locked to one tool's session format | Claude Code, Codex, Cursor, and a human contractor all read the same Markdown |
| Verifiable | "Did it do what I meant?" is a vibe check | Diff the output against acceptance criteria — a checkable question |
The last row is the one that changes your daily work. Without a spec, reviewing agent output means reconstructing your own intent from memory while reading 900 lines of diff. With a spec, review splits into two cheap questions: does the code satisfy the spec? (mechanical — and delegable to a second agent) and was the spec right? (the only part that needs your judgment). See Reviewing AI PRs.
The economics: 30 minutes vs 3 hours
The recurring anti-pattern: skipping the spec to "save time," then paying for it in review-and-redo. Concrete version — "add CSV export to the reports page" delegated as a one-line prompt to a React/Node dashboard:
| Prompt-only path | Spec-first path | |
|---|---|---|
| Up-front | 2 min prompt | 30 min spec (agent drafts, you harden) |
| Agent run | 25 min — makes ~8 silent decisions: columns, delimiter, encoding, row cap, streaming vs buffering, permissions, filename, timezone of dates | 25 min — decisions were already made |
| First review | 40 min — you discover it buffered 500k rows in memory and exported soft-deleted records | 20 min — checking against acceptance criteria, not reconstructing intent |
| Redo cycle | Re-prompt from memory, 25 min run, 30 min re-review; the re-prompt introduces a new ambiguity | Rarely needed; deviations are visible as spec violations |
| Next session touches export | Re-explain everything; drift | see specs/csv-export.md |
| Total | ~3 hours, and the constraints still live only in your head | ~1.5 hours, and the spec is a permanent asset |
The redo cycle is the killer. Every re-prompt is a new lossy compression of your intent, and agent runs are cheap enough that you'll be tempted to spin the wheel instead of thinking — three plausible-but-wrong implementations later, you've spent more time reviewing than a spec would have cost. This is the economics behind the stuck loops failure mode.
The multiplier: a prompt's cost is paid per session; a spec's cost is amortized over every future session, teammate, and tool that touches the feature — including the agent that debugs it in production six months from now.
The spec-driven loop
Two edges do most of the work. Plan → spec: run the agent in plan mode against the spec before any code is written; a wrong plan is the cheapest possible detector of a wrong spec (Idea to Spec covers this drafting loop). Verify → criteria: verification means checking acceptance criteria line by line, not skimming the diff — which only works if the criteria were written to be checkable (Verification Strategy). The final edge — spec updated and merged with the code — is what keeps the loop honest across iterations; skip it and you enter the drift cycle described in Keeping Specs Alive.
When a spec is overkill
Specs are a tax on small work. A one-line fix with a full spec is process theater; a billing change with no spec is negligence. Scale the artifact to size × risk:
| Task profile | Examples | Cost of a wrong guess | Artifact needed |
|---|---|---|---|
| Mechanical, one-line, self-evidently verifiable | Fix typo, bump a dependency, rename a variable | Seconds — visible in the diff instantly | Nothing. Just ask. |
| Bounded change, one surface, minor ambiguity | Add a CLI flag, extend an endpoint with a field, add a test for known behavior | Minutes of localized rework | Structured prompt — task, context, constraints, done-when. See Prompt Anatomy |
| Multi-file feature with real decisions embedded | CSV export, notifications, a new settings page | Hours of review-and-redo; invented requirements ship | Lightweight spec — one page: intent, requirements, acceptance criteria, out of scope |
| Cross-cutting, hard to reverse, or architectural | Auth model change, billing logic, data migration, service extraction | Production incident, silent architecture erosion | Full spec plus an ADR capturing the decision. See Decision Records and Writing Effective Specs |
Two overrides that push a task up a row regardless of size: irreversibility (data migrations, published API contracts, anything customers integrate against) and repeat explanation — if you've explained the same constraints in chat twice, the third explanation should be a file, whatever the task size.
And one push down: if a lightweight spec is growing past two pages, you don't have a bigger spec problem — you have a decomposition problem. Split it. See spec granularity and Large Tasks.
Related
- Prompts vs Specs — the conceptual foundation: lifespan, audience, and the escalation rule.
- Writing Effective Specs — the anatomy of an agent-ready spec, section by section.
- Spec Examples — weak requests rewritten as strong specs across seven task types.
- Idea to Spec — the workflow for getting from a vague idea to a hardened spec, using the agent to draft.
- Keeping Specs Alive — preventing spec-code drift once the feature ships.
- Templates: Specs and Planning — copyable spec templates to start from.