Most advice on spec-driven development is backwards. It starts with tools. That's the wrong place to start.

By May 2026, the backlash got loud for a reason. People called SDD "waterfall with markdown," a "productivity trap," and a ritual that burns tokens while your feature still isn't shipped. Simon Willison has been one of the clearest voices pushing back on over-specification. He isn't wrong. A bloated spec process can absolutely turn into fake rigor.

But the opposite mistake is worse for a solo builder. If you hand Cursor, Claude Code, Codex, or Gemini a vague prompt against a real codebase, you usually get confident nonsense, shallow codebase understanding, and rework. That's not agility. That's roulette.

So don't ask which SDD framework is best. Ask which one is the least bad fit for your current constraints. Solo or tiny team. Greenfield or brownfield. Tight token budget or not. CLI habits you don't want to lose. Hosted comfort level. One agent or several.

That's the point of Choosing Your SDD Framework, a Decision Tree. Not ideology. Triage.

If you're still unsure whether specs are helping or just slowing you down, read when specs slow you down and when they 10-x you. Then come back and pick the lightest framework that gives your agent enough context to stop guessing.

Table of Contents

The SDD Backlash Is Here So Why Bother

The backlash is deserved. A lot of SDD advice drifted into ceremony.

You saw the pattern. Someone takes a simple feature, wraps it in a giant markdown packet, adds review rituals, then acts surprised when coding got slower. Birgitta Böckeler's taxonomy is useful precisely because it separates lightweight spec-first work from more rigid spec-anchored and spec-as-source approaches. Thoughtworks put spec-driven development on the Tech Radar because the idea is real, but that doesn't mean every implementation style deserves your time.

The criticism is real

The common complaints are not made up:

  • "Waterfall with markdown" happens when the spec becomes a gate instead of a guide.
  • "Productivity trap" happens when you spend more time perfecting the doc than reducing implementation risk.
  • "Spec drift" happens when the code changes and the spec becomes stale on day two.
  • "Frozen specs" happen when people treat an early guess like a contract.
  • "Token-burning ceremony" happens when the framework asks the model to restate what everyone already knows.

Over-specification doesn't save you. It just moves the waste earlier in the cycle.

Simon Willison's broader critique lands here. AI coding works best with crisp context, not theatrical process. Addy Osmani's canonical six-section spec format is useful because it forces clarity around problem, constraints, scope, and validation. It's bad when people turn that format into a bureaucratic religion.

Why you should still care

If you're building solo, your real problem isn't lack of ideas. It's lack of a second brain that can hold product intent, codebase constraints, edge cases, and implementation plan at once.

A decent SDD framework patches that gap. It gives your coding agent a better starting brief. That matters most on brownfield work, changes with hidden side effects, and features where "mostly right" still means broken.

Use SDD when ambiguity is expensive. Skip heavy process when the task is obvious.

That's the line.

The Three Levels of Spec-Driven Development

Before you pick a framework, you need the right mental model. Birgitta Böckeler's spec-first, spec-anchored, and spec-as-source taxonomy is the cleanest one I've seen. It cuts through the noise.

A diagram illustrating the three levels of spec-driven development maturity for generative AI, starting from level one.

Spec-first is the entry point

This is the lightest version. You write a structured brief before code. Usually markdown. Usually human-readable first.

GitHub Spec Kit, basic BMAD flows, and a lot of solo-founder templates sit here. So do many homemade workflows built around Addy Osmani's six-section format. You define the feature, list boundaries, note assumptions, maybe add acceptance criteria, then hand it to your coding agent.

Good fit: greenfield work, small features, people who hate setup.

Bad fit: messy brownfield systems where file paths, dependencies, and hidden coupling matter more than product prose.

Spec-anchored is where most solo builders should live

This is the sweet spot for many developers building real apps with AI.

The spec isn't just a document anymore. It's tied to the codebase. It references concrete modules, known constraints, existing schemas, and likely blast radius. Kiro, OpenSpec-style workflows, and more structured repo-aware approaches tend to live here. The spec stays human-readable, but it starts acting like a map instead of a wish list.

That matters because most failed AI-generated code isn't caused by weak coding skill. It's caused by missing context.

Practical rule: If you're working in an existing repo, spec-anchored usually beats spec-first.

You don't need full machine-readable orchestration. You need enough grounding that the agent stops inventing architecture.

Spec-as-source is powerful and easy to overdo

This is the ambitious end of the ladder. The spec becomes a primary artifact in the build lifecycle. It can drive checks, workflow states, or even generated behavior. Vibe Kanban and similar systems point in this direction. So do stricter frameworks that want the spec to coordinate work across implementation, validation, and change tracking.

This path can be excellent when you want consistency and repeatability. It can also become rigid fast.

Here are the trade-offs in plain English:

Level What you gain What you risk Best for
Spec-first Speed, simplicity Drift, shallow context Greenfield solo work
Spec-anchored Better repo awareness More setup Brownfield solo builders
Spec-as-source Deep consistency Rigidity, lock-in, ceremony High-discipline builders

The mistake isn't choosing the "wrong" rung forever. The mistake is starting too high because the framework looked impressive on GitHub.

Your SDD Decision Tree Questions

The right framework falls out of your constraints. Not your ideals.

A decision tree diagram titled Your SDD Decision Tree Questions, outlining steps to select a software framework.

The seven questions that actually matter

Answer these in order:

  1. Are you solo or working with a tiny team?
    If you're solo, bias toward low-ceremony tools. Team workflows add value only when coordination is the problem.

  2. Are you okay being IDE-locked?
    Some tools feel smooth inside one editor and awkward everywhere else. If you switch between Cursor, Claude Code, terminal tools, and your own scripts, IDE lock-in gets annoying fast.

  3. Are you sensitive to token spend?
    This one matters more than people admit. A thread in r/OpenAIDev discussing SpecKit token usage captures the frustration. If every refinement round feels expensive, your framework is too chatty for your budget.

  4. Are you on greenfield or brownfield?
    New projects tolerate lighter specs. Existing repos punish shallow context.

  5. Do you use one primary coding agent or several?
    A single-agent workflow can get away with looser formatting. If you bounce across Cursor, Claude Code, Codex, and Gemini, structured specs matter more.

  6. Do you want hosted or self-managed?
    Hosted gets you convenience and persistent context. Self-managed gives you control and less dependency on someone else's product direction.

  7. Do you already have a CLI workflow you like?
    If the answer is yes, don't throw it away unless the replacement is clearly better.

If you're also exploring cross-platform product work, it helps to discover mobile app development options in parallel. Not because mobile frameworks and SDD frameworks are the same thing, but because your platform choice changes how much implementation detail your specs need.

How to answer without lying to yourself

Often, these questions are answered aspirationally. That's a mistake.

Don't answer based on what sounds advanced. Answer based on what you already do on a Tuesday afternoon when you're tired.

  • If you hate leaving the terminal, pick a local workflow.
  • If your repo is old and weird, don't pretend a generic markdown template will carry enough context.
  • If you switch tools often, avoid frameworks that only shine in one environment.
  • If you avoid updating docs, don't pick a system that collapses when the spec goes stale.

Choose for your current habits, not the workflow you wish you had.

That one rule will eliminate half the bad picks.

Branch One Lightweight and Local Frameworks

If you're solo, okay with editor-centric tooling, and attached to your CLI habits, this branch is usually the best starting point.

A person coding in a dark room with an illustration showing a path towards local development.

Pick this branch if friction is your real enemy

Local frameworks win on one thing. They don't ask you to change your life.

GitHub Spec Kit, Traycer, and BMAD all appeal to the same instinct. Keep the artifacts in the repo. Keep the process visible. Keep the handoff to the coding agent manual and obvious. That's attractive because it avoids platform dependency and keeps the spec close to the code.

It's also why these tools drift so easily. Nothing forces you to keep the spec current. Nothing stops you from generating a nice doc, shipping a different implementation, and never reconciling the two.

How GitHub Spec Kit, Traycer, and BMAD differ

Here's the blunt version:

Framework Best at Weak spot My take
GitHub Spec Kit Clean repo-native structure, familiar GitHub gravity Can feel verbose and token-hungry if you overuse refinement loops Good if you want convention and don't mind editing
Traycer Lightweight tracing from intent to implementation Less guardrail-heavy than hosted systems Good for builders who want clarity without a platform move
BMAD More complete planning flows, can support deeper thinking Easy to overdo, especially if you treat every feature like a formal project Good when the feature is messy enough to justify it

A few practical notes:

  • GitHub Spec Kit works best if you already trust GitHub as the center of gravity for your dev process. The upside is obvious discoverability through the GitHub topic for spec-driven development. The downside is that teams often inherit the structure without deciding whether they want the ceremony.
  • Traycer fits people who want a path from requirement to code impact without drowning in templates.
  • BMAD is strongest when you need stronger elicitation, diagrams, or a more deliberate thinking process. It's weakest when you use it on tiny tasks.

Addy Osmani's six-section format is a good benchmark for this branch. If a framework can't help you clearly state intent, boundaries, implementation notes, assumptions, validation, and open questions, it's too loose. If it forces a dissertation for a tiny feature, it's too heavy.

For a deeper side-by-side on the low-ceremony end, read lightweight SDD frameworks compared.

A local framework is great when you already know how to think. It won't save you from sloppy reasoning.

My recommendation is simple. Start here if you're greenfield, mostly solo, and allergic to setup. But keep your specs short enough that you'll still edit them after the code changes.

Branch Two Structured and Hosted Platforms

This branch is for people who are tired of manually collecting context before every serious feature.

Screenshot from https://tekk.coach

Pick this branch if context gathering keeps killing momentum

Hosted and structured platforms earn their keep on brownfield work. That's where repo awareness, stored context, and guided spec creation matter.

The common pattern is straightforward. You connect your codebase, answer questions, and get back a more grounded spec than you'd usually write by hand. That can be a big improvement when the actual work isn't typing code. It's figuring out where the change belongs, what it might break, and which assumptions need validation.

The trade-off is obvious too. You depend on a product. You accept some opinionated workflow. You usually give up some of the raw flexibility you'd get from a plain markdown folder.

How Kiro, OpenSpec, and hosted structured workflows compare

I wouldn't lump every structured tool together because they solve different pain points.

  • Kiro makes more sense when your process already leans collaborative and you want stronger shared structure. For a solo founder, that can feel like too much framework unless the project is getting hairy.
  • OpenSpec is interesting because it pushes toward a standard shape for specs without requiring the heaviest possible process. That's attractive if you want portability and cleaner handoffs across tools.
  • Hosted structured workflows in general are strongest when you have an older repo, recurring context problems, or multiple agents that need a consistent brief.

Other names in this orbit matter too. OpenSpec, Kiro, and GitHub Spec Kit are often the first noticed, but SDD, GSD, and AI-DLC-style repo-aware approaches all point at the same core need. Better grounding than a freeform prompt.

For solo builders, here's my opinionated filter:

If this sounds like you Pick
"My repo is old and the agent keeps missing hidden constraints" Structured hosted workflow or OpenSpec-style approach
"I want specs to stay portable across tools" OpenSpec
"I need more team-facing process than personal notes" Kiro
"I want the lightest possible thing that still knows my codebase" A simpler structured workflow over a heavier team system

The danger with this branch isn't usually drift. It's dependency. If the platform disappears, changes direction, or nudges you into more ceremony than you need, your process can calcify around it.

That said, if your bottleneck is not writing code but repeatedly rebuilding context, this branch is often the right answer.

Branch Three The High-Integration Path

This path is for builders who want the spec to be more than a document. They want it embedded in the workflow itself.

When deeper integration is worth it

High-integration systems such as Vibe Kanban, and adjacent approaches that treat the spec as an operational artifact, can be excellent when consistency matters more than spontaneity.

You get a tighter loop between intent, implementation, review, and validation. The system can make work more legible. It can reduce ambiguous handoffs. It can stop random prompt improvisation from becoming your engineering process.

This is the branch for people who want rigor.

Not fake rigor. Real rigor.

Where Vibe Kanban and similar systems bite back

The cost is rigidity. That's where the backlash language starts making sense.

When the framework sits too close to the lifecycle, every change can feel like paperwork. That isn't automatically bad. It is bad when the task is small and the process still insists on heavyweight updates.

A discussion on the r/vibecoding subreddit highlighted scalability concerns, with one user noting, "SDD is amazing until you hit 30 repos and 100 devs," underscoring the friction that can arise as complexity grows even in smaller-scale operations, as seen in that Reddit thread on scaling SDD workflows.

That quote matters because it points to the core truth of this branch. The more integrated the system becomes, the more your process quality matters. If your spec habits are poor, high integration doesn't save you. It amplifies the mess.

Here are the tools and patterns I put in this bucket:

  • Vibe Kanban, for workflow-integrated spec tracking
  • Spec-as-source experiments, where the spec coordinates implementation states
  • More rigid SDD pipelines, often used by builders trying to standardize AI-assisted delivery end to end

And here are the caveats I would give any solo founder:

  • Don't start here unless drift is already hurting you
  • Don't start here if you hate maintaining process artifacts
  • Don't start here if your project changes shape every day
  • Do start here if repeated implementation inconsistency is your main pain

If you want a broader map of where these frameworks sit, read the framework landscape for SDD tooling in 2026.

This path has the highest upside and the highest self-inflicted downside. That's why most solo builders shouldn't begin here. They should earn their way into it.

How to Implement SDD and Avoid the Traps

Picking the framework is the easy part. Using it without turning into a process goblin is the true work.

A three-step infographic on how to implement SDD, featuring icons for starting small, defining specs, and integrating workflows.

Start with a spec small enough to survive contact with reality

Your first spec should be almost annoyingly small.

Not a product requirement novel. Not a grand system redesign. One feature. One endpoint. One workflow fix. Use a short structure:

  • Problem you are fixing
  • Scope of the change
  • Constraints from the current codebase
  • Acceptance checks you can verify
  • Open questions the agent shouldn't guess on

That shape works whether you're using GitHub Spec Kit, BMAD, OpenSpec, or a hand-rolled markdown template.

A practical example. You're adding an API endpoint to an existing app. You write the spec in plain markdown, note the route, auth expectations, affected service layer, edge cases, and tests you expect. Then you hand that spec to Claude Code manually. The first pass comes back. You update the spec to reflect what you learned. Then you do the next pass.

That's how this works in real life. Short cycles. Living doc. Manual judgment.

Use the spec as a tool not a shrine

Frozen specs kill momentum. So does endless refinement.

Use these rules instead:

  1. Write less than you think you need
    If the coding agent can infer it safely from repo context, don't repeat it.

  2. Update the spec when reality changes
    If implementation revealed a hidden constraint, the spec should catch up.

  3. Throw away stale sections fast
    Old guesses are not sacred.

  4. Judge the framework by shipped output
    If your process produces nice docs and worse shipping speed, it's failing.

The best spec is the one that improves the next coding pass, not the one that wins a documentation contest.

Most "productivity trap" stories begin not with the wrong tool, but with the wrong behavior. People start treating the artifact as the deliverable. It isn't. The shipped feature is the deliverable.

The Right Framework Is the One You Actually Use

There isn't one best SDD framework. There is only the one that fits your current constraints without dragging you into ceremony you won't maintain.

If you're solo and moving fast, start lightweight. If you're wrestling with a brownfield repo, move toward spec-anchored structure. If consistency and workflow integration already matter more than raw speed, the high-integration path can make sense.

Try one path for a week. Be honest. If it helps your agent get the first attempt closer to right, keep it. If it adds process and nothing else, cut it.

Shipped features beat beautiful specs every time.

Tekk.coach fits the builder who wants structured specs without pretending to hire an imaginary engineering team. Connect your GitHub repo. Describe the problem. Get a structured spec. Ship.

Part of the Spec-Driven Development pillar — a 52-page honest playbook on shipping with AI coding agents.