There is a workflow doing the rounds right now. Ask an agent to write a spec. Read the spec. Hand it to an agent to turn into a plan. Hand that plan to an agent to turn into code.
Structured. Documented. A clear handoff at every step.
The problem is that word "read". Most people are skimming.
The case for spec-first is real
Before I get to the trap, the case for writing a spec at all is genuinely strong.
A prompt is a wish. It describes what you want in broad strokes and leaves every ambiguous decision for the agent to resolve silently. A spec is different. It makes those decisions explicitly. Which countries does the tax logic cover? Sessions or tokens? What happens when a payment fails mid-flow?
Addy Osmani, engineering lead on Google Chrome, put the boundary precisely: "If you underspecify a task, the AI may do something unexpected; if you overspecify, you may as well code it yourself." The spec is what lives between those two failure modes.
An agent is also genuinely good at surfacing what you haven't thought through yet. Ask it to list every assumption it would need to make before writing any code, and you get an uncomfortable list. That discomfort is information. You're not wasting time. You're front-loading the friction that would otherwise surface as a production bug.
The two-hop problem
Here is where most spec-driven workflows quietly fall apart.
You ask an agent to draft the spec. It produces something thorough: goals, constraints, acceptance criteria, a data model, named edge cases. It is well-formatted and confident. You skim it.
Section 1 looks right. Section 2 looks right. Section 3 mentions a caching strategy that seems reasonable. Approved.
That caching strategy is now your architecture.
You didn't choose it. You didn't evaluate alternatives. You don't know why the agent picked cache-aside over write-through, or whether that distinction even matters for your load pattern. But it's in the spec now, which means the coding agent will execute it with full confidence, because specs are authoritative.
What you've done is delegate understanding, not just execution. You've added a document-shaped layer between you and a decision the agent made. The layer looks like you were in the loop. You weren't.
This is the same problem, one step earlier in the pipeline. We've talked about it at the code level: if you can't explain the code, you shouldn't have shipped it. The same principle applies here: if you can't defend the spec, you shouldn't have approved it.
The coding agent doesn't know the difference. It executes what the spec says, and the spec says what the drafting agent decided.
What the spec is actually for
A spec is not a document you produce. It is proof that you understood the task before you handed it over.
Its value has nothing to do with format or length. It comes from one thing: the person who approved it could walk into a room and defend every decision in it without referring back to the document.
If you can't do that, the spec isn't yours. The agent wrote it. You countersigned it. That is not ownership. That is notarisation.
How to actually do this
Three steps. In order.
1. Use the agent to surface what you haven't decided
Before you ask for a spec, ask for questions. Give the agent your rough brief, then:
Before writing anything, list every assumption you would need to make
and every decision I haven't yet specified.The output is your reading list. Every item is a decision you need to make yourself, in your own head, before the spec can honestly be yours. Work through that list. Answer each one. Then ask the agent to draft the spec from your answers, not from its own interpolations.
2. Read the draft like you will be quizzed on it
Every section where your instinct is "I'll trust the agent on this" is a section you haven't understood. That instinct isn't confidence. It's a gap.
Treat those sections the way you'd treat unfamiliar code in a pull request. You wouldn't approve a function you couldn't trace through. Don't approve a spec section you couldn't justify.
Ask the agent why it chose the approach it chose. Look up the pattern if you don't recognise it. Understand the trade-offs before you move on.
The goal is not to second-guess every word. It is to reach a point where you could re-explain the spec to a colleague from memory, including the parts that weren't obvious.
3. Challenge the sections that feel opaque
Use the Architect/Devil's Advocate pattern on the parts you're least certain about. Ask the agent to make the strongest argument against the approach it has described. If its counterarguments surface things you hadn't considered, you haven't finished reading the spec yet.
Only once you can explain every constraint and justify every trade-off is the spec actually yours. Then hand it to an agent for the coding plan.
If you're using Claude Code, the Superpowers plugin handles the brainstorming phase well. It asks clarifying questions before touching any code, produces a structured design document, and waits for your explicit approval before generating an implementation plan. It is a good tool for step 1.
But the Superpowers post itself is worth re-reading before you rely on it: "plans inherit spec errors. If your design document is wrong, the implementation will be wrong in the same direction." The tool improves the quality of the draft. It does not replace reading it.
What a readable spec contains
Not every spec needs the same sections. But some things have to be explicit, or the agent will invent them.
| What belongs | What it looks like |
|---|---|
| Decisions made explicitly | Not "handle authentication": "JWT tokens, 24-hour expiry, refresh on activity" |
| Named edge cases | Not "handle errors": "payment fails: retry once, notify user, never charge twice" |
| Constraints you could test | Not "should be fast": "API response under 200ms at p95 under normal load" |
| What is out of scope | Saves the agent from solving problems you didn't ask for |
What doesn't belong:
- Anything you'd describe as "figure out the best approach." That's still a gap, now formalised in a document.
- Implementation choices you don't understand and haven't researched.
- Acceptance criteria you couldn't write a test for yourself, without asking the agent.
The test is simple. For every line of the spec, ask yourself: did I decide this, or did I let it go? The lines you let go are the ones that will confuse you when they surface in production.
The step the workflow doesn't automate
The two-agent workflow is not wrong. Using one agent to draft and another to build is better than prompting directly for code. The draft surfaces decisions. The structure creates something to argue with.
But the workflow only works if you do the one step it cannot automate.
The spec is where you take responsibility. Not for writing it: that is what the drafting agent is for. For understanding it. For being the person who can explain, to a colleague, a reviewer, or yourself at three in the morning, why the system was designed the way it was.
You can't spot the bug if you didn't write the code. You also can't steer the build if you didn't understand the plan.
If you approved a spec you couldn't defend, the spec you handed over wasn't yours.