When Thoughtworks engineer Birgitta Böckeler pointed Amazon’s Kiro at a small bug, the tool turned it into four user stories with 16 acceptance criteria. Her verdict, in a review published on martinfowler.com: “the workflow was like using a sledgehammer to crack a nut.”
That line is the most useful thing anyone has written about spec-driven development, and it is the reason this guide looks different from the version that first ran in March. The original argued that every AI-coded project needs a full specification before the first prompt. A year of tool releases and a few honest studies say something narrower: write a spec sized to the job. A one-file context for everything, a reviewed plan for a feature, and the full Spec Kit or Kiro ceremony only when the build will outlive a single weekend.
What changed in a year
Spec-driven development (SDD) went from a blog-post idea to an ecosystem with version numbers.
- GitHub Spec Kit hit 1.0. The project’s own history page dates the first commit to August 21, 2025 and the 1.0.0 release to August 21, 2026, when the docs listed 38 coding-agent integrations and 157 community extensions. The repository passed 148,000 stars this week, shipped v1.3.2 on November 6, and stays MIT-licensed and free.
- Kiro has real prices now. The Kiro pricing page lists a free tier with 50 credits a month, Pro at $20 for 1,000 credits, Pro+ at $40, Pro Max at $100 and Power at $200, with add-on credits at $0.04 each.
- OpenSpec arrived for existing projects. Fission AI’s OpenSpec is MIT-licensed, works with 30+ AI tools through
/opsx:slash commands, and describes itself as “built for brownfield not just greenfield,” which matters if your project already exists. - The context file became a standard. OpenAI’s AGENTS.md format moved under the Linux Foundation’s new Agentic AI Foundation on December 9, 2025, alongside Anthropic’s MCP, and the foundation counts more than 60,000 open-source projects using it. Claude Code, which uses its own CLAUDE.md, now reads AGENTS.md too when no CLAUDE.md is present.
The old version of this guide treated CLAUDE.md as a Claude-only trick. It is now one dialect of a cross-tool habit, and you can write one file that Cursor, Codex, Gemini CLI and Claude Code all read.
Three sizes of spec
Böckeler’s review splits the field into three levels: spec-first (write it, use it, move on), spec-anchored (keep it and update it as the feature evolves) and spec-as-source (the human edits only the spec, never the code). She found every tool she tested was spec-first in practice. For a solo creator, a more practical split is by the size of the job.
| Job | Spec size | Tool that fits | Time to write |
|---|---|---|---|
| Any session, any project | One context file, under 200 lines | CLAUDE.md or AGENTS.md | 20 minutes once, then edits |
| A feature or a fix that touches several files | A plan you read before edits begin | Claude Code plan mode or your editor’s plan step | 5 to 10 minutes per feature |
| A multi-session build: membership site, course platform, client app | Full spec, plan and task list kept in the repo | Spec Kit, Kiro spec mode, OpenSpec | An hour or two up front |
Most of the pain people report with SDD comes from using row three for a row two job.
The file every project should have anyway
A context file is the cheapest spec there is. It answers the questions the agent would otherwise guess at: what the stack is, how to run the tests, which folder is off-limits, what “done” means.
Anthropic’s memory docs give two rules that are worth more than any template. First, keep each file under 200 lines, because longer files eat context and get followed less reliably. Second, write instructions concrete enough to check: “Run npm test before committing,” not “Test your changes.” The same page is blunt about the limits: Claude treats the file “as context, not enforced configuration.” If something must never happen, such as pushing to main or touching your payments folder, that belongs in a hook or a permission setting, not a polite sentence.
A good context file for a creator project covers:
- What this is: one sentence. “Paid newsletter archive with Stripe checkout, built on Next.js and Supabase.”
- How to run it: the exact dev, test and build commands.
- Conventions the agent keeps breaking: naming, where components live, which UI library you use.
- Hands off: files and folders that need a human, such as environment files, migrations and anything that charges a card.
- Definition of done: tests pass, no new lint errors, a one-line summary of what changed.
Run /init in Claude Code to generate a starter version, then cut it down. If you use more than one agent, write AGENTS.md and import it from CLAUDE.md so both read the same rules.
Plan mode is the size most people skip
Between “just prompt it” and “generate four markdown files” sits the step that catches most of the mistakes: making the agent show its plan before it touches anything.
Claude Code’s plan mode does exactly this. The agent reads files and explores, writes a plan, and cannot edit your source until you approve. Press Shift+Tab to toggle it, or type /plan before a single prompt. Ctrl+G opens the plan in your editor so you can cross out the parts you don’t want.
For a feature like “add a discount code field to checkout,” that plan is the spec. It names the files it will change, the order it will change them in, and the edge cases it noticed. Reading it takes three minutes. Catching a bad assumption here costs one sentence; catching it after 14 files changed costs an afternoon of git diff.
When the full kit earns its overhead
Spec Kit’s core loop is now /speckit-constitution, /speckit-specify, /speckit-plan, /speckit-tasks, /speckit-implement, then /speckit-converge, repeated until it reports the work matches the spec. That is a lot of ceremony, and Böckeler found it “very verbose and tedious to review.” Her line that sticks: “I’d rather review code than all these markdown files.”
The overhead pays back when three things are true:
- The project spans many sessions. A spec kept in the repo means session 12 starts from the same understanding as session 1, instead of from whatever the agent infers from the code.
- Someone else will touch it. A client, a co-founder or a contractor can read a spec. Few will read 4,000 lines of generated TypeScript.
- You are changing an existing app. This is where OpenSpec’s per-change folders (proposal, specs, design notes, tasks) are a better fit than Spec Kit’s branch-per-feature model.
Choosing between the three comes down to where you already work. Spec Kit is free and runs inside the agent you have. Kiro is a full IDE with specs built in, and every agent request draws from a metered credit pool, so price a month of spec work against the 1,000 credits in Pro before you commit. OpenSpec is the lightest of the three and the best fit for brownfield code.
For a link-in-bio page, a landing page or a one-off script, skip all three. Tools like Lovable and Canva Code 2.0 exist for jobs where the prompt is the spec.
What a spec cannot do for you
Three limits the original version of this guide skipped.
Agents still drift from the spec. Böckeler: “Even with all of these files and templates and prompts and workflows and checklists, I frequently saw the agent ultimately not follow all the instructions.” In one run, Spec Kit’s research notes described classes that already existed, and the agent rebuilt them as duplicates. A spec makes drift easier to spot. It does not stop it, so you still review the diff.
A spec does not make the code secure. Veracode’s 2026 GenAI Code Security Report found models pass only 56% of security tests when the prompt does not mention security, essentially unchanged from its 2025 study of 100+ models. Code compiled almost every time. If your app takes payments or stores email addresses, write the security requirement into the spec (“validate all form input server-side; parameterized queries only”) and run a scanner anyway.
Your sense of speed is unreliable. In METR’s 2025 randomized trial, 16 experienced developers took 19% longer on real tasks with AI tools, while believing they had been 20% faster. METR has since marked those results out of date, and its February 2026 follow-up points toward a speedup, though METR itself calls that data “an unreliable signal.” The lasting lesson is the 39-point gap between what people felt and what the clock said. If you adopt a heavy SDD workflow, time a few features with and without it before you decide it is faster.
A one-page spec you can copy
For anything in the middle row of the table, this fits on one screen and gives the agent everything it needs. Save it as specs/feature-name.md and point the agent at it.
# Feature: [name]
### Problem
One or two sentences. Who hits this and what happens now.
### Done when
- [ ] Testable outcome 1 (e.g. "Code SPRING10 takes 10% off at checkout")
- [ ] Testable outcome 2
- [ ] Existing tests still pass
### Out of scope
- Things the agent should not build this round
### Constraints
- Stack / libraries to use or avoid
- Files that must not change
- Security: input validation, auth checks, secrets handling
### Open questions
- Anything you have not decided (the agent should ask, not guess)
The “Out of scope” and “Open questions” sections do most of the work. They are where an agent fills gaps with invention, and naming the gaps is cheaper than reviewing what it invents.
If you want the faster end of the spectrum first, the vibe coding workflow covers the prompt-first approach, and the Cursor vs GitHub Copilot comparison covers which editor to run any of this in.
Recent Posts
Gemini Omni 1.2 Flash's Real Discount Is the 360p Draft, Not the 30% Price Cut
Gemini Omni 1.2 Flash cuts video pricing 30% and stretches clips to 15 seconds, but a full 720p clip still costs about what a 10-second one did. The 360p draft tier and follow-up edits are where...
YouTube doubles its Partner Program entry bar on February 1, 2027, adds a 10M-view floor for Shorts pool payouts, and needs existing partners to accept new terms by January 31.
