Most advice about SDD for solo developers is backward. It tells you to act like a team of ten when you're one tired founder with a repo, a backlog, and an AI that will happily sprint in the wrong direction if you feed it mush.
That's why so much spec-first advice gets mocked in 2026. People call it "waterfall with markdown," "spec drift," "frozen specs," and "token-burning ceremony." They're not wrong. A big PRD, a constitution, a plan, tasks, and a bunch of ceremony can become a productivity trap fast. Simon Willison has been part of that broader pushback, and Birgitta Böckeler's spec-first, spec-anchored, and spec-as-source framing matters because it separates useful discipline from dogma. The mistake is treating all SDD as the same thing.
For a solo builder, the useful version is lean. One short spec. One focused build session. One self-review pass against acceptance criteria. This is all that's required. If you want the long version on where specs help and where they waste your time, read this breakdown of when specs slow you down and when they help.
Table of Contents
- Why Most SDD Advice Is a Trap for Solo Devs
- The Solo-Friendly Spec Using Addy Osmani's Format
- Your Workflow From Problem to AI-Ready Spec
- The Hand-Off Feeding Specs to AI Coding Agents
- The Loop Self-Review and Nightly Audits
- Common Pitfalls and How to Avoid Them
Why Most SDD Advice Is a Trap for Solo Devs
The backlash is earned
If you've looked at GitHub Spec Kit, Kiro, OpenSpec, Traycer, Vibe Kanban, or BMAD, you've probably noticed the split. Some builders swear by them. Others think the whole category is busywork wearing an AI badge.
That backlash is real because a lot of SDD content still smells like process cosplay. It gives you a constitution, a planning phase, task decomposition, maybe a taxonomy, maybe a matrix, then acts surprised when a solo founder spends the day grooming docs instead of shipping. Thoughtworks Tech Radar and Addy Osmani get referenced for good reasons, but people often copy the artifact count and miss the point.
Practical rule: If your spec workflow creates more documents than decisions, it's already too heavy for solo work.
There's another reason the critique landed. In 2026, Spec-Driven Development is defined as making a precise, executable specification the source of truth and treating code as a generated, verifiable artifact, specifically as a response to "vibe coding," a term Andrej Karpathy popularized in early 2025 for loosely prompting AI to ship unverified results. That same definition explicitly rejects "waterfall with markdown" because the spec is supposed to stay living and version-controlled, not frozen at the start of a long phase, as noted in this 2026 SDD overview.
The solo version is different
Here's the part most advice misses. You do not need team-shaped SDD when you don't have a team.
You need a minimal spec that behaves like the senior engineer you can't hire. It should catch missing constraints, define out-of-scope work, and give your AI enough structure to stop freelancing architecture. That's the entire job.
Real solo builders keep running into the same wall in public threads. In the Reddit discussions on vibe coding failures, guardrails, and solo-friendly "get stuff done" spec patterns, the pattern is obvious. Raw prompting feels fast right until the second or third change request, then the repo turns into a pile of accidental decisions. You can recover, but recovery costs more than writing a short spec would have.
The right move isn't "no process." It's low-ceremony discipline.
A good solo spec should do four things:
- Name the problem clearly. Not the feature. The problem.
- Draw boundaries. Your AI needs a fence.
- State acceptance criteria. That gives you a review rubric later.
- Stay short enough to rewrite. If you won't revise it, it's already dead.
That's why I push back on PRD-heavy frameworks for solo builders. The enterprise shape of SDD is often a trap. The solo shape can be sharp.
The Solo-Friendly Spec Using Addy Osmani's Format
Addy Osmani's format is the best default I've seen for solo work because it doesn't pretend your document needs to satisfy five stakeholders. It needs to satisfy one builder and one coding agent.
Why this format works when you're alone
The canonical 6-section spec format, attributed to Addy Osmani and cited by Thoughtworks Tech Radar, says specs should include a constitution of project-wide rules and define the negative space, meaning what's out of scope, to prevent drift. It also says specs should stay short, around 1 to 3 pages, and be split if they grow larger, as summarized in this review of the format.
That size limit matters more than people admit. Once your solo spec gets bloated, you stop using it. Then the AI stops following it. Then you drift.
If you want a simple way to keep these notes in a system you already use, SystemSculpt's Obsidian project spec template is a decent starting point because it treats the spec like a working document instead of a formal relic.
The six parts that matter
I use a stripped-down interpretation of the format. Same backbone. Less theater.
| Section | What it does for a solo dev |
|---|---|
| Project overview | Names the feature in plain English |
| Problem statement | Forces you to say why this exists |
| User stories | Keeps the work tied to real behavior |
| Components | Limits which parts of the system can change |
| API or interactions | Clarifies touchpoints and data flow |
| Edge cases | Stops the AI from only building the happy path |
A few notes matter more than the labels.
Negative space is your rabbit-hole blocker
Out-of-scope belongs in every solo spec. Not because a PM asked for it. Because you will absolutely get tempted to add "just one more thing" once the AI starts moving fast.
Write down what you're not building. Be blunt.
- Don't add auth changes if this task is about onboarding copy.
- Don't redesign data models if you're fixing one reporting flow.
- Don't touch mobile layouts if this spec is desktop-only.
That one section saves hours.
Acceptance criteria turns the spec into a reviewer
Your future self needs a testable finish line. Without it, you review by mood. That's how bugs slip through and scope expands unchecked.
A short spec beats a smart prompt. The prompt disappears. The spec stays and gives you something to check.
Good acceptance criteria are boring on purpose. They describe visible outcomes and constraints. They do not contain implementation fan fiction.
A copy-paste template
Use this. Fill it in fast. If it takes more than one focused session, you're probably overthinking the feature.
# [Feature name]
## Project overview
One paragraph on what this feature is.
## Problem statement
What problem are you solving?
Who has it?
What breaks today?
## User stories
- As a [user], I want [capability], so that [outcome].
- As a [user], I want [capability], so that [outcome].
## Components
Files, modules, routes, services, or UI areas allowed to change:
-
-
-
Project rules:
- Follow existing patterns in the repo
- Prefer modifying existing code over adding new abstractions
- Keep naming consistent with current modules
## API or interactions
Inputs:
Outputs:
Events:
External dependencies:
Data contracts affected:
## Edge cases
- Empty state
- Error state
- Retry behavior
- Permission or auth constraints
- Loading and timeout behavior
## Out of scope
-
-
-
## Acceptance criteria
- [ ]
- [ ]
- [ ]
## Assumptions
-
-
## Validation
- Manual checks:
- Tests to update or add:
- Rollback plan:
If you're using SDD for solo developers, this is enough. You don't need a ceremonial PRD. You need a sharp document that prevents stupid mistakes.
Your Workflow From Problem to AI-Ready Spec
Most solo builders start too late. They start at "build the feature" instead of "name the problem." That's why the first draft the AI gives back feels productive but wrong.
Start from pain, not features
A weak starting point sounds like this:
- "Add onboarding improvements"
- "Make search better"
- "Clean up dashboard UX"
That isn't a spec seed. That's vague dissatisfaction.
A better starting point sounds like this:
- New users don't understand the first action to take after signup
- Search returns too many irrelevant records for exact-name queries
- The dashboard hides failed syncs until support tickets show up
That's enough to begin.
From there, write three short notes before you open your editor:
- What's broken now
- Who feels it
- What done looks like
That short exercise cuts out a lot of fake complexity. If the problem is still fuzzy after that, you're not ready to ask an AI to code it.
Make the spec codebase-aware
Solo builders usually cut corners. They write a decent feature description, then hand it to Cursor or Claude Code without telling it how the current repo behaves.
Bad idea.
Your spec needs to point at the codebase reality:
- Relevant files and folders
- Existing patterns to copy
- Constraints you refuse to break
- Tests that already cover adjacent behavior
If you're stuck on how to phrase the behavior side, product and UX prompt libraries can help sharpen the language. I like browsing resources such as these advanced AI design prompts for examples of clearer problem framing, not to paste blindly, but to tighten rough thinking.
There are a few ways to build a first-try spec:
| Approach | When it works | Where it breaks |
|---|---|---|
| Manual markdown in your repo | Best if you know the codebase cold | Easy to miss hidden dependencies |
| Notes app plus repo grep | Fine for small features | Context gets scattered |
| Repo-aware spec tools | Good for brownfield codebases | You still need judgment |
One option is Tekk.coach, which reads a GitHub repo, runs a structured interview, and produces a first-try spec for tools like Cursor, Claude Code, Codex, and Gemini. It doesn't create PRs, and it doesn't orchestrate external coding agents. You still manually hand the spec to the agent you want. If you want a broader look at agent flow design, this AI agent workflow guide is useful.
Run an AI pre-flight before you hand it off
Before you paste anything into an agent, do a pre-flight check. I use five questions.
- Can this be done in one build session? If not, split it.
- Does the spec say what not to touch? If not, add out-of-scope.
- Are acceptance criteria testable? If not, rewrite them.
- Did you name the files or modules involved? If not, do that now.
- Would a stranger understand the feature without Slack context? If not, your AI won't either.
Reality check: An AI-ready spec is not a polished artifact. It's a clear enough artifact.
That standard is important. Solo founders lose days polishing a planning doc that should've taken an hour.
The Hand-Off Feeding Specs to AI Coding Agents
A spec isn't magic. You still have to hand it to the model correctly.
Your spec is also your prompt
This part needs to be explicit because people keep muddying it. You manually hand the spec to Cursor, Claude Code, Codex, or Gemini. That's the hand-off. No mystery layer.
Different agents behave differently, but the principle stays the same. Give them the spec, the allowed scope, the relevant files, and the review expectations. If you're comparing tools for broader startup use, lists like this roundup of AI agents for startups can help you get your bearings.
A lot of newer workflows fail here because they treat the spec as a background doc instead of the main instruction artifact. That's backward. The spec should be the core prompt. The chat around it should be minimal.
If you want examples of how this fits into a wider stack, this page on spec-driven development with your coding agent stack maps the hand-off patterns well.
Copy-paste hand-off prompts
Use these as a starting point.
Cursor
Best when you can point at files directly.
Use the attached spec as the source of truth for this task.
Rules:
- Stay inside the listed components and files
- Do not expand scope beyond the spec
- If acceptance criteria conflict with current code, flag it before changing architecture
- Prefer existing patterns over new abstractions
Task:
Implement the feature exactly as written. Then list:
1. files changed
2. open questions
3. which acceptance criteria are satisfied
4. what still needs manual verification
In Cursor, I like selecting the related files, then using the command flow with the spec pasted in. That keeps the context narrow.
Claude Code
Best when you want stronger reasoning and a cleaner review summary.
Treat this spec as binding unless you find a clear conflict in the existing codebase.
First:
- inspect the relevant files
- summarize the implementation plan in 5 bullets
- ask questions only if a blocked decision exists
Then:
- implement in small, reviewable changes
- do not touch unrelated code
- map your final output to the acceptance criteria
Claude Code tends to do better when you ask for a short plan first. That catches misunderstandings early.
A quick visual example helps here.
Codex or Gemini
Keep these tighter. Too much prose can create detours.
Implement this spec within existing repo patterns.
Constraints:
- no new frameworks
- no unrelated refactors
- preserve existing APIs unless the spec says otherwise
Return:
- implementation summary
- changed files
- acceptance criteria checklist
- risks or follow-up items
What good execution looks like
You want the agent to behave like a careful mid-level engineer with a good tech lead document in front of it.
That's why the best hand-offs usually include:
- A spec file with scope, out-of-scope, and acceptance criteria
- A file list for likely change areas
- A clear instruction to avoid refactors
- A required mapping back to acceptance criteria
If the model starts redesigning your app, your spec wasn't sharp enough or your hand-off prompt gave it too much freedom.
The Loop Self-Review and Nightly Audits
Most solo builders stop at "the AI wrote code." That's too early to feel done.
Review against the spec, not your mood
Your spec should become the review rubric. That's the whole point of writing it in the first place.
Open the spec and check the acceptance criteria one by one. Not "does this look good?" Not "did the model sound confident?" Just the checklist.
I use a blunt review pass:
- Behavior check. Does the feature do what the spec says?
- Boundary check. Did the AI touch anything outside scope?
- Failure check. Are the edge cases handled?
- Code fit check. Does it match existing repo patterns?
That review style is less glamorous than vibe-based coding, but it saves you from the fake speed loop where each "quick win" creates future repair work.
The missing team member in solo development isn't another coder. It's a reviewer with standards. Your spec can do most of that job if you actually use it at the end.
Use a tiny audit loop
You also need some form of async review rhythm, especially when you're tired. Tired founders bless bad code all the time.
A useful pattern is a nightly audit loop. One pass that asks: what's drifting, what's risky, and what's the one issue worth attention tomorrow?
That can be manual. It can also be tool-assisted. Tekk's async feature is the CTO loop. One tick per workspace. At most one proposal or question per tick. That's a narrow constraint, and it's a good one. It prevents a flood of noisy advice.
The key idea matters more than the tool. You want a recurring check that compares the repo's direction against your intended direction.
Why this fits the micro-launch model
This review loop works especially well if you build small and ship often.
For solo developers using a micro-launch approach in SDD, the strongest pattern is to create 1 to 4 small projects that can launch within 1 to 3 months, validate market fit hard, and kill ideas that don't stick. A successful project can reach $500/month, according to the discussion captured in this HN thread on micro-launches.
That model fits solo SDD because it forces restraint. You don't need a grand framework. You need specs short enough to support rapid validation, fast enough to rewrite, and clear enough to review after each release.
If an idea doesn't catch, kill it. Don't architect it harder.
Common Pitfalls and How to Avoid Them
The usual failures in SDD for solo developers aren't proof the method is broken. They usually mean you've drifted back into team-sized habits.
Drift means your spec is too vague
If the implementation keeps wandering, don't blame the model first. Check the spec.
Spec drift usually comes from one of three mistakes:
- Scope is mushy. You didn't state what stays untouched.
- Acceptance criteria are abstract. "Feels smoother" is not reviewable.
- Components aren't named. The AI guessed where to work.
Course correction is simple. Rewrite the spec smaller. Add negative space. Tighten the criteria.
Perfectionism is the real process bug
The bigger risk for solo builders isn't under-planning. It's over-polishing.
According to Smashing Magazine's piece on solo development and perfectionism, 70% of solo developers fail within 12 months due to feature creep and perfectionism, and the better fit for solo work is a flexible, iterative note-taking system rather than a formal GDD.
That lines up with what ships. Your spec should feel alive, cheap to edit, and disposable when needed. If it starts feeling sacred, you've already lost speed.
A simple rule helps:
| Pitfall | Course correction |
|---|---|
| Spec keeps growing | Split the feature into a smaller spec |
| AI hallucinates architecture | Add tighter file boundaries and out-of-scope |
| You keep rewriting docs | Build the smallest executable slice |
| Review feels fuzzy | Rewrite acceptance criteria as visible outcomes |
Don't confuse framework complexity with rigor
GitHub Spec Kit can be useful. Kiro can be useful. OpenSpec, BMAD, and the rest all have strengths. But solo builders often copy the heaviest parts first and the useful parts last.
Rigor isn't the number of artifacts. Rigor is whether your spec prevents drift and supports review.
If your process feels like a token-burning ceremony, strip it down. Keep the six-section spec. Keep the hand-off discipline. Keep the self-review loop. Throw out the rest.
Connect your GitHub repo. Describe the problem. Get a structured spec. Ship. Tekk.coach.
Part of the Spec-Driven Development pillar — a 52-page honest playbook on shipping with AI coding agents.