Most advice on AI coding still assumes one agent should do everything. Write the spec. Plan the work. Edit the code. Review the diff. Catch the regressions. That sounds clean. It also falls apart the moment the session drifts, the model gets clever, or your repo stops being toy-sized.
If you're building alone, spec-driven development with your coding agent stack isn't about ceremony. It's about getting predictable output from messy tools. The popular anti-spec critique has teeth. Some of it is deserved. But the alternative isn't freedom. It's rework, token burn, and code you stop trusting after the third "small" change.
Table of Contents
- The Spec-Driven Backlash Is Here and It's Right
- The One Spec to Rule Them All
- Agent Deep Dive Claude Code
- Agent Deep Dive Cursor
- Agents for the Job Copilot Codex and Gemini
- The Art of the Multi-Agent Handoff
- Building Your Spec-Driven Workflow
The Spec-Driven Backlash Is Here and It's Right
The backlash is real. By May 2026, spec-driven development was already taking hits as "waterfall with markdown," "productivity trap," and "spec drift". Yuval Yeret put a finer point on it. Teams were seeing refinement become disengaging because one person showed up with a detailed breakdown before the conversation even started, which left less room for estimation and less meaningful implementation effort when AI was in the loop, as he wrote in his critique of spec-driven development.
That criticism lands because bad SDD is easy to spot. Someone writes a giant markdown file. Nobody argues with it. The agent blindly executes it. Then the team pretends the spec is truth even after the product changed.
Bad SDD looks exactly like the critics say
The worst version has all the failure modes people complain about:
- Frozen specs: you wrote them once, then kept coding after reality changed.
- Token-burning ceremony: every task starts with a huge context dump because the spec isn't structured enough to be reusable.
- Spec drift: code and spec diverge, and now both are lies.
- Pseudo-waterfall: planning gets front-loaded, but feedback still arrives late.
Simon Willison has pushed hard on engineering discipline for coding agents. Birgitta Böckeler's spec-first, spec-anchored, and spec-as-source framing matters for the same reason. These aren't all the same thing. Most backlash is aimed at the rigid end of the spectrum, not at the practical middle where a spec anchors decisions but still gets revised.
Bad specs don't reduce chaos. They just move chaos earlier.
Thoughtworks Tech Radar, GitHub Spec Kit, Kiro, OpenSpec, Traycer, Vibe Kanban, and BMAD all sit somewhere in this argument. Some treat the spec as a strong contract. Some treat it as guided context. Some wrap the whole thing in enough process to scare off any solo founder with shipping pressure.
Why solo builders still need specs
If you're alone or running a tiny AI-heavy team, you don't have a senior engineer hovering over every generated change. That changes the math. The spec isn't there to please process people. It's there because your coding agent will otherwise fill gaps with guesses.
The hard part isn't writing more words. It's writing the few words that stop expensive mistakes.
There's also a practical security reason. LLMs produce vulnerable code at rates ranging from 9.8% to 42.1% across various benchmarks, and the strongest argument for SDD is that it turns passive documentation into executable contracts that constrain agent output, as summarized in Augment Code's guide to spec-driven development. Unit tests won't reliably catch architectural violations or API drift. A tighter spec can.
For solo builders, the right answer isn't no specs. It's smaller specs, live specs, and fewer lies.
The One Spec to Rule Them All
You need one spec that survives handoff. Not a different prompt for Claude, a different note for Cursor, and a half-remembered checklist for Gemini. One document. Small enough to reread. Structured enough that different agents can parse it without creative interpretation.
What a portable spec needs
Addy Osmani's canonical six-section style is a strong base because it forces you to separate intent from implementation noise. For cross-agent work, I keep the format even stricter.
A portable spec should answer six things fast:
TL;DR
What is changing, for whom, and why now.Scope boundaries
What this spec covers, and what it explicitly does not.Subtasks with acceptance criteria
Break the work into reviewable chunks. Each chunk should be testable.Assumptions tagged by risk
Note what's guessed, unstable, or blocked on outside decisions.Validation scenarios
Name the behaviors you expect to pass or fail.Target files
Point the agent at the likely blast radius.
That structure travels well because each tool reads different signals best. Claude likes complete context. Cursor likes file-aware intent. Gemini benefits from crisp scenarios. Copilot mostly benefits because you, the human, have already reduced ambiguity.
A spec format agents actually follow
Here's the format I use most often.
| Section | What goes in it | What stays out |
|---|---|---|
| TL;DR | user problem, desired behavior, constraint | product manifesto |
| Scope boundaries | in-scope changes, non-goals | hidden "maybe later" ideas |
| Subtasks | concrete implementation units | giant feature blobs |
| Assumptions | risky unknowns and placeholders | fake certainty |
| Validation scenarios | success, edge case, failure case | vague "works correctly" |
| Target files | files to edit, inspect, or avoid | full repo dump |
A lightweight example:
# Feature
Add team invite expiration handling
## TL;DR
Users can accept invites until expiration. Expired invites show a clear error and cannot create memberships.
## Scope boundaries
In scope:
- invite acceptance API
- invite acceptance UI state
- membership creation guard
Out of scope:
- invite resend flow
- admin analytics
## Subtasks with acceptance criteria
1. Reject expired invites in backend
- acceptance: expired token returns domain-specific error
- acceptance: no membership is created
2. Show expired state in UI
- acceptance: expired invite page renders retry guidance
- acceptance: valid invite flow unchanged
## Assumptions tagged by risk
- [medium] existing invite records already store expiration timestamp
- [high] mobile client does not use this endpoint
## Validation scenarios
- valid invite accepted before expiration
- expired invite rejected
- already accepted invite remains rejected
## Target files
- app/api/invites/accept.ts
- domain/invites.ts
- components/invite/accept-page.tsx
- tests/invite-accept.test.ts
Practical rule: if two agents would interpret a sentence differently, rewrite the sentence.
If you want a broader context layer around the spec, a comprehensive context protocol tool can help organize project context outside the spec itself. That's useful when the spec should stay tight but the repo still needs persistent product, architecture, and workflow guidance.
One mention is enough here. Tekk.coach sits in this category too. It reads a GitHub repo, runs a structured interview, and produces a spec in this style for tools like Cursor, Claude Code, Codex, and Gemini. It doesn't send work to those agents for you. You manually hand the spec over.
Agent Deep Dive Claude Code
Claude Code is where I want to start when the problem is still wide. It handles a lot of context, reads long specs without panicking, and usually gives the cleanest first pass on architecture, task decomposition, and implementation order.
Where Claude Code fits
Claude is best at the top of the funnel:
- Spec digestion: long requirements, constraints, and background notes
- Plan creation: turning one feature into task-sized chunks
- Cross-file reasoning: spotting how one change spills into data models, APIs, and UI
- Rewrite passes: tightening a rough spec into cleaner language before implementation
This is why many solo builders default to Claude first. The failure mode isn't usually "can't code." It's "coded something plausible that wasn't the intended job."
A decent starting prompt looks like this:
Read this spec as the source of truth.
Your job:
1. Summarize the feature in 5 bullets
2. List ambiguities or risky assumptions
3. Produce an implementation plan in small reviewable tasks
4. Do not write code yet
5. Do not add requirements not present in the spec
Spec:
[paste spec here]
Then, after you review the plan:
Implement only Task 1 from the approved plan.
Before editing, restate the acceptance criteria in your own words.
After editing, list changed files and explain how each change maps to the spec.
How to prompt Claude from a real spec
Claude responds better when you separate modes. Don't ask for design, implementation, and validation in one breath unless the task is tiny.
A simple sequence works better:
- Pass 1: understand and critique the spec
- Pass 2: produce tasks
- Pass 3: implement one task
- Pass 4: verify against acceptance criteria
If you need examples of a tighter Claude-first workflow, this write-up on a Claude Code workflow is worth reading because it stays grounded in actual implementation steps instead of generic prompting advice.
For builders watching budget and access, this list of resources for AI startup funding can help if Claude usage is becoming part of your regular build loop.
Known limits
Claude's main weakness isn't intelligence. It's session decay. You can feel the moment it starts operating from its own last answer instead of from the source spec. That's where people burn sessions and still end up with drift.
Real developer threads reflect that pain. The Reddit discussion on dealing with Claude sessions is worth reading because it's not abstract. People describe exactly what happens when the thread gets long and the model starts slipping.
Re-paste the spec before trust drops, not after.
When Claude starts proposing changes outside scope, missing previously accepted constraints, or summarizing too confidently, reset. Start a new session. Paste the current spec and the current task only. Treat continuity as optional. Treat grounding as required.
Agent Deep Dive Cursor
Cursor is not where I want to invent the feature. It's where I want to land the feature in the actual codebase. That's a different job.
Cursor is strongest after the spec exists
Once the spec is stable enough, Cursor becomes the practical workhorse because it sees files, references, nearby patterns, and the shape of the repo. You spend less time pasting giant context blocks and more time steering edits.
Cursor works well for:
- Codebase-aware integration: fit the change into existing conventions
- Multi-file edits: route, schema, component, and test changes in one pass
- Local refactors: keep the blast radius under control
- Focused follow-up: "apply Task 2 only to these files"
Cursor 2.0's multi-agent positioning is interesting, and the Cursor blog release notes are the right place to follow that evolution. The upside is speed inside the editor. The downside is opacity. Sometimes you know exactly why it changed a file. Sometimes you don't.
How to work spec-first inside Cursor
Don't dump the whole spec into a generic chat and say "build this." Point Cursor at the current task and the relevant files.
A useful pattern:
Use this spec as the source of truth for Task 2 only.
Acceptance criteria:
- expired invite page renders retry guidance
- valid invite flow unchanged
Inspect:
@components/invite/accept-page.tsx
@app/api/invites/accept.ts
@tests/invite-accept.test.ts
Do not modify unrelated files.
Before editing, tell me the minimal file set you plan to change.
Then tighten it further once Cursor has read the code:
Make the UI changes only.
No backend edits.
Keep copy plain and consistent with existing empty-state patterns.
This is also why writing clean user-facing behavior matters before implementation starts. If your acceptance criteria are mushy, Cursor will happily make the UI "better" in ways you didn't ask for. A solid set of user stories helps because it forces actor, action, and expected outcome into the spec before the IDE agent starts improvising.
Where Cursor gets messy
Cursor inherits strengths and weaknesses from the model underneath it. If the underlying model drifts, Cursor drifts with nicer ergonomics. The IDE context makes it feel more reliable than it always is.
There's another problem. Cursor can tempt you into local optimization. The diff looks good. The code compiles. But the broader feature contract may already be off.
A quick comparison helps:
| Good use of Cursor | Bad use of Cursor |
|---|---|
| integrating an approved task into known files | discovering product requirements mid-edit |
| matching existing code style | deciding architecture from scratch |
| small refactors after a spec exists | replacing the need for a spec |
| checking nearby references | trusting hidden agent behavior blindly |
Use Cursor when the question is where and how in this codebase. Don't use it for what we are building.
Agents for the Job Copilot Codex and Gemini
Most stacks get worse because people treat all coding agents as interchangeable. They aren't. You get better results when each tool has a narrower role.
The broader frame matters here. In 2026, spec-driven development was being defined as a discipline where the spec is the source of truth and code is a generated, verifiable artifact, directly pushing back on "vibe coding" for maintainable systems, as described in this 2026 overview of SDD and tooling.
Copilot as the finisher
Copilot is not my first reader of the spec. It's my in-flow implementer after I already understand the job.
Best use cases:
- fill obvious boilerplate
- complete repetitive tests
- suggest local transformations
- speed up code you already designed
Bad use cases:
- infer missing business rules
- decide data contracts
- own cross-file feature work without supervision
Prompt it with the smallest possible slice:
Implement the validation helper described in the current spec.
Do not create new domain rules.
Match the existing test style in this file.
The practical trade-off is simple. Copilot feels fast because it sits close to your hands. It also inherits your ambiguity. The Reddit thread on frustration with GitHub Copilot behavior captures the annoyance well. When you're underspecified, it happily guesses.
Codex as the programmable executor
Codex matters when you want a more explicit spec-to-task pipeline, especially if you're comfortable shaping repo rules with files like AGENTS.md or a specs/ directory. GitHub's Spec Kit repository is useful here because it shows a cross-agent approach that works with Copilot, Claude Code, Gemini CLI, Cursor, Windsurf, and others.
Codex is good for:
- repository-driven instruction following
- task execution from structured spec files
- generated tests tied back to acceptance criteria
- repeatable flows that don't rely on one giant chat
A minimal repo-oriented prompt:
Read /specs/invite-expiration.md and follow AGENTS.md.
Implement only the backend rejection behavior.
Generate or update tests for acceptance criteria in that spec.
Codex is not magic. It's only disciplined if your repo is disciplined.
Gemini as the second reader
Gemini is useful when I want a different interpretation of the same spec. Not because one model is always smarter, but because different agents fail differently. That matters.
Strong use cases:
- review logic produced by another agent
- challenge assumptions hidden in the spec
- rewrite unclear validation scenarios
- inspect edge cases before merge
A good Gemini prompt is less "build this" and more "interrogate this":
Read this spec and this diff.
List any behaviors that appear implemented but not specified.
List any specified behaviors that appear unimplemented.
Then propose missing tests.
Gemini often proves its worth. It can act as a reviewer without sharing the same conversational momentum that shaped the implementation.
One more thing. There's still a real evidence gap here. The DeepLearning.AI course on spec-driven development with coding agents is useful and practical, but even supporters of SDD have noted the lack of systematic empirical comparison against looser approaches. For a solo founder, that means you won't get a neat benchmark that proves your exact stack is "correct." You still have to judge by output quality, rework, and trust.
If an agent can't explain how its code maps back to the spec, it isn't done.
The Art of the Multi-Agent Handoff
The gains show up when you stop asking one tool to be planner, implementor, and reviewer all at once.
Microsoft's framing is the cleanest mental model I've seen. In its AI-native engineering workflow, a Coordinator breaks down the spec and delegates work, Implementor agents execute, and a separate Verifier checks output against the spec before work is considered complete, as described in Microsoft's spec-driven development workflow.
That matters because self-verification is weak. The same agent that invented the mistake is often bad at spotting it.
A handoff pattern that works
A practical handoff for solo builders looks like this:
| Stage | Agent | Job |
|---|---|---|
| Spec shaping | Claude or Gemini | tighten scope, identify ambiguities |
| Codebase integration | Cursor | land approved tasks in real files |
| Inline completion | Copilot | speed local implementation |
| Review pass | Gemini or Claude | compare code against spec |
| Human decision | you | approve, reject, or rewrite the spec |
Here's the rough flow I keep coming back to:
Start with one portable spec
No per-agent variants yet.Ask one agent to break it into tasks
This is your Coordinator role, even if it's still just one model in one window.Give one task at a time to the implementation tool
Usually Cursor for codebase-aware changes.Use a separate agent to verify
Don't let the implementor grade its own homework.Update the spec if behavior changed
If you only change code, drift starts immediately.
A related write-up on a coding agent orchestrator is useful if you're trying to think in roles instead of brand names.
The live demo below is a good companion because it shows the general flow in action rather than treating multi-agent work like theory.
When to switch agents mid-spec
Switch when the job changes shape, not because you're bored with the current tool.
Good switch points:
- Spec is broad, code task is now narrow: move from Claude to Cursor.
- Implementation is done, trust is low: move from Cursor to Gemini for review.
- You're writing repetitive tests or local cleanup: let Copilot help.
- The session starts forgetting the contract: restart with the source spec in a different window.
Real builders are already doing this. The Reddit thread on a multi-AI dev workflow using Claude and Gemini and the discussion in AI solo businesses about multi-agent workflows are useful because they show people assembling stacks around real friction, not around clean vendor categories.
How to keep one spec portable across agents
Portability breaks when the spec contains tool-specific assumptions. Don't write "Cursor should inspect these files" inside the source spec. Put that in the handoff prompt.
Keep the spec tool-neutral:
- Describe behavior, not preferred model behavior
- Reference files, not editor features
- Use acceptance criteria, not vibes
- Keep assumptions explicit and tagged by risk
A good portability test is simple. Can Claude read it, can Cursor act on it, and can Gemini review against it without you rewriting the document? If not, the spec isn't portable yet.
Building Your Spec-Driven Workflow
This only works if it becomes routine. Not elaborate. Routine.
The main thing to accept is that one-shot spec-to-product thinking is fantasy. Gojko Adzic and Daniel Terhorst-North argued at GOTO 2026 that those approaches are doomed, comparing them to failed CASE tools and model-driven architecture, and saying success requires tight iterative feedback loops, not one giant description handed to AI in hope, in their GOTO 2026 discussion.
The daily loop
A workable solo-founder loop is boring in a good way:
- Morning: pick one spec or one task chunk
- Midday: hand it to the right agent for execution
- Afternoon: run a separate review pass
- End of day: update the spec if behavior changed
If you're on GitHub, keep the workflow visible in the repo itself. A simple rule helps: every meaningful code change should map back to a spec file or spec section. You don't need bureaucracy. You need a trail.
I also like one lightweight CI check. Require a spec link or spec reference in the PR description template. It doesn't prove quality, but it catches the "I just vibed this into existence" branch before it becomes normal.
How to keep specs from rotting
Spec drift starts when changing code is easier than changing the contract. So make spec edits cheap.
A few rules keep it alive:
- Edit the spec when behavior changes: not later, now.
- Keep specs per feature or task cluster: giant master docs die first.
- Tag assumptions by risk: that gives you a natural review queue.
- Rewrite after shipping: remove dead detail and keep only the contract that still matters.
The spec should be shorter after the feature settles, not longer.
For local-first builders who don't want every experiment in the cloud, this ultimate guide to running AI locally is a useful companion when you're deciding which parts of your workflow should stay on your machine.
What to automate and what to keep human
Automate the repeatable parts. Keep judgment where wrong decisions hurt.
Automate:
- task extraction from a reviewed spec
- consistency checks between acceptance criteria and tests
- repo reminders that a spec reference is missing
- basic validation passes
Keep human:
- product trade-offs
- architecture decisions
- deciding when the spec is wrong
- final merge judgment
For Tekk.coach users, the async piece is the CTO loop. One tick per workspace. At most one proposal or question per tick. That's useful because it forces prioritization. It doesn't create PRs, and it doesn't orchestrate external coding agents. You still hand the spec to Cursor, Claude Code, Codex, or Gemini yourself.
The honest truth is that we still don't have strong empirical data comparing disciplined SDD against vibe coding in a way that gives solo builders airtight proof. Even advocates have pointed out that gap earlier in the article's referenced material. But in practice, the signal is obvious enough. If your agent output is inconsistent, your rework is climbing, and sessions keep burning on avoidable confusion, the missing piece usually isn't a smarter prompt. It's a better contract.
Connect your GitHub repo. Describe the problem. Get a structured spec. Ship. Try Tekk.coach.
Part of the Spec-Driven Development pillar — a 52-page honest playbook on shipping with AI coding agents.