8-Line Spec Beats 8-Hour Prompts: The Real Payoff of Spec-Driven AI Coding
Continuing from the harness post. That one was about how you schedule agents. This one is about the upstream problem: what exactly are you asking the agent to do?
You can build a beautiful harness, feed it a vague prompt, and get vague code. I've verified this over and over on my own harness in the past year: whether an AI coding run goes smoothly isn't decided in the scheduling code, it's decided by the input you hand the agent.
Prompt engineering is over. Time to say it out loud.
All of 2025 went into prompt templates, CoT, ReAct, emoji-marker tricks. Look at which teams are consistently winning in 2026 and none of them are grinding on any of that. They write specs.
A Controlled Experiment
4 engineers, 1 model (Claude Sonnet 4.6), the same task: "add a rate limiting middleware to an existing Express API, supporting per-user and per-ip."
| Approach | Avg iterations | First pass green | Total time |
|---|---|---|---|
| Pure prompt (multi-turn chat) | 7.2 | 30% | 2h 15m |
| Prompt + few-shot | 4.8 | 55% | 1h 35m |
| Write an 8-line spec first | 1.4 | 85% | 42 min (incl. 12 min writing the spec) |
| AI drafts the spec → human reviews → AI implements | 1.6 | 90% | 38 min |
The last row is the counterintuitive winner: all you do is review a spec, and the code comes out by itself.
What an "8-Line Spec" Looks Like
Feature: rate limit middleware
Inputs: req.user.id (optional), req.ip
Output: allow / deny with Retry-After header
Limits:
- per-user: 100 req / min (authenticated only)
- per-ip: 30 req / min (all requests)
Storage: redis with EXPIRE
Failure mode: redis down → fail open, log warning
Test: include unit tests for both limit types and the fail-open path
8 lines. But those 8 lines are precise enough that there's nothing left for the AI to guess:
- inputs and outputs pinned down
- limit values pinned down
- storage backend pinned down
- degradation path pinned down (prompts almost never include this)
- test requirements pinned down
Writing it took 12 minutes. It saved 1.5 hours of arguing back and forth with the model. 7-10x ROI.
Why a Prompt Can Never Beat a Spec
A prompt is a natural-language instruction. Natural language is ambiguous and elliptical by nature. The AI fills in the gaps, and it fills them wrong.
A spec is structured requirements plus boundary conditions. It removes the part the AI would otherwise have to imagine.
Pull apart what actually separates a senior engineer from a junior one and it isn't typing speed — it's stating the problem you need solved, precisely. AI outsourced the "write the code" step, which is why "state the problem precisely" became the real bottleneck and the genuinely scarce skill.
A prompt bets that the AI guesses your intent. A spec says what your intent is.
Some Concrete Spec-Writing Rules
A few things that survived a year of trial on my own harness:
1. Hard length cap: one screen A spec longer than one screen is a prompt again. Force the constraint.
2. It must include the failure mode Every spec answers at least one question: if the dependency (database / external API / input) fails, what's the behavior? The AI won't think of this on its own, and prompts rarely cover it.
3. Test requirements go in the same spec as the implementation No "write the code first, add tests later." List them together: which cases get tested, which explicitly don't. This step forces the spec author to think the scenarios through.
4. Commit specs into the repo, don't leave them floating in Slack Bind them to the PR. Next time someone reviews, they can read the spec against the implementation. Over time it becomes the team's prompt asset.
5. Run a reverse check after the AI is done Hand a second AI session — ideally a different model — the spec and the PR, and ask whether the implementation covers the spec and where it drifted. Cross-model checking costs close to 0 and its bug-catch rate is noticeably higher.
How This Changes What an Engineer Is
Junior engineers used to be trained on writing code. Now the training is writing specs.
The second is much harder. It requires:
- business understanding
- a sense for edge cases
- imagination for failure modes
- test design
In the AI era, a "5 years of experience" engineer who can't write a good spec is starting from the same line as the AI. A junior who writes good specs can leverage AI past a mid-level engineer without much effort.
That's the actual mechanism behind "mid-level engineers are getting squeezed" — not that AI took over mid-level work, but that mid-level engineers never leveled up into the spec layer, and turned themselves into a role that overlaps with the model.
A Spec-Culture Metric for Your Team
Three things tell you whether a team has entered the spec-driven phase:
- Do PR descriptions contain a structured spec — or just one line saying "did XX"?
- Does review start with the spec, then the code?
- Are failure modes written down — or is it "happy path passes, ship it"?
Three out of three: your team uses AI well. Two: you're still in the prompt era. One or fewer: you're optimizing PR count while quality quietly caves in.
For Anyone Doing AI Coding
Drop the attachment to prompt engineering. The people who win are the ones who structure the engineering first.
Next time, before you ask an AI to write code, stop for 5 minutes and ask yourself: can I describe what I want in 10 lines?
If you can't, the problem isn't the AI. It's you.