The fastest way to waste tokens is to start coding without a plan. I learned this the hard way.
One afternoon I asked Claude Code to build a caching system for my Spotify API. No spec, no clear requirements, just "do it." The agent started fast — created files, modified routes, added environment variables. Forty minutes later I had a system that didn't handle fallbacks, used inconsistent keys, and had broken the existing route. I scrapped everything and started over.
The problem wasn't the agent. The problem was me. I gave it speed without direction.
The problem with "just build it"
AI agents are fast. Too fast to work without direction. When you say "build X" without defining what X means exactly, the agent makes decisions for you. Some right, many not.
The typical result:
- Rewrite loops — The agent builds something, you say that's not it, it builds another version, you say almost, it builds another. Three iterations later you've consumed more tokens than if you'd planned upfront.
- Context loss — After 30 minutes the window compacts. Without written artifacts, the agent forgets the decisions you made together. You start over.
- Implicit architecture decisions — The agent picks patterns, names files, structures modules. If you didn't define that beforehand, you now have AI-generated tech debt.
This isn't an agent capability problem. It's an input problem. Garbage in, garbage out — applies to prompts just as much as Figma files.
What is SDD in one paragraph
Spec-Driven Development is a practical pipeline: before writing code, you create artifacts that define what you're building and how. It's not a methodology religion or a heavyweight framework. It's concrete phases — Explore, Propose, Spec, Design, Tasks — that you can run through in 10 minutes or an hour depending on complexity. The point is that when the agent starts executing, it knows exactly what to do.
The phases that matter
Each phase produces a concrete artifact. Not documentation for documentation's sake — information the agent needs to do good work.
SDD Pipeline — Click each phase
Codebase map: dependencies, existing patterns, constraints
"The project uses Zustand for global state, Tailwind v4 with OKLCh tokens, and has no tests configured."
The agent researches. You validate it understood correctly.
Exploration — Understand before deciding
The agent investigates your codebase first. It reads your config files, analyzes dependencies, identifies existing patterns. It doesn't assume — it asks the code.
This prevents the classic mistake: building something that already exists, or using a pattern incompatible with the rest of the project. Five minutes of exploration save thirty minutes of rewriting.
Proposal — One paragraph of intent
Before touching code, you articulate in one paragraph what you're going to do, why, and how. Sounds trivial, but it forces you to think. If you can't explain the change in three sentences, you probably don't understand it well enough to delegate it.
The proposal is your contract with the agent. "We're going to do this, this way, for this reason." Everything that follows gets evaluated against that paragraph.
Spec — What "done" means
Concrete requirements, edge scenarios, acceptance criteria. Not prose — verifiable items. "If Redis is down, the API returns data directly." "TTL is configurable via environment variable."
The spec is what survives when context compacts. The agent can lose the entire conversation, but if it has the spec, it can pick up right where it left off.
Tasks — Steps the agent executes
The spec says what to build. Tasks say how, step by step. "1. Create module. 2. Refactor route. 3. Add environment variable. 4. Verify fallback."
Each task is atomic — the agent can execute it without additional context. If one fails, the others aren't contaminated.
When to use it vs when to skip it
SDD isn't for everything. It has a setup cost — minimal, but real.
Use it when:
- The change touches multiple files
- There are architecture decisions to make
- It's new functionality, not a tweak to something existing
- You need another agent to be able to pick up the work
Skip it when:
- It's a one-line fix
- You're correcting a typo or adjusting styles
- The change is so small that the spec would take longer than the code
- You already know 100% what to do and how
The practical rule: if you can describe the change in a tweet, just do it. If you need more than a paragraph, plan first.
The real benefit: artifacts that survive
The value of SDD isn't in the process — it's in the artifacts it generates. When the context window compacts (and it will compact), the conversation disappears. Informal decisions are lost. The "we agreed that..." no longer exists.
But the spec is still there. The task list is still there. The agent can read those artifacts and resume exactly where it left off, without you repeating the entire context.
It's the difference between losing an hour of conversation and losing five seconds while the agent rereads the spec.
Planning isn't overhead when AI does the executing
In traditional development, planning has an opportunity cost: every minute planning is a minute you're not coding. When you're the one executing, that tension is real.
With AI agents, the equation changes. You don't execute — the agent executes. Your most valuable work isn't writing code, it's defining what code to write. Planning goes from being overhead to being the highest-leverage activity.
Ten minutes defining a spec can save an hour of directionless iteration. And the artifacts you produce don't just guide the current session — they survive for the next one.
Next time you're about to tell the agent "just build it," pause for a moment. Write one paragraph about what you want. Define what "done" means. Then let it execute. The difference will surprise you.
This is the eighth article in the series. The first was about the tools I use. The second about why they fail and how to fix it. If you want to see the bridge between design and code, read the Figma-to-Code workflow article.