Spec Kit vs Kiro vs a Plain plan.md: The Spec-Driven Setup I Kept (2026 Field Log)

I already spent a month running spec-driven development on a real product, and wrote up what the method felt like. The verdict stuck: on anything bigger than my working memory, writing the spec first beats prompting blind.

This time the question is narrower. Which tool do I actually run it in?

Quick refresher, in case you landed here cold. Spec-driven development (SDD) means writing a structured spec before an AI agent touches code, so the spec becomes the contract instead of a fading chat history. If you want the theory, Martin Fowler's team did a clean three-tool teardown (2025). I wanted the practice. So I built the same feature three ways.

The feature I built

A team-invite flow. Email invite, token, accept page, role assignment, expiry. Small enough to finish, big enough to have edge cases that bite. Exactly the size where prompting blind starts dropping constraints.

GitHub Spec Kit

GitHub's Spec Kit (2025) is the toolkit most people mean when they say SDD in 2026. You run a few slash commands. It walks you from a constitution (project rules) to a spec, then a plan, then tasked-out execution.

The structure is genuinely good. Writing the constitution forced me to name rules I usually keep in my head. Never trust an expiry from the client. One token, one use. The agent stopped inventing its own auth story because the story was written down.

The cost is ceremony. Four artifacts before a line of code. For the invite flow it felt right. For a bug fix it would feel absurd.

Kiro

Kiro (2026) is AWS's spec-first IDE. It splits a feature into requirements, design, and tasks, and keeps them visible in a side panel while the agent works.

I liked seeing the spec and the code in one window. The gap between what I asked for and what got built was the smallest here. When the agent drifted, the drift was obvious, because the requirement sat right next to the diff.

It is also the heaviest option. A whole IDE to adopt. If you already live in one editor, that is a real switch cost.

A plain plan.md in Claude Code

Then I dropped the tools and just wrote a plan.md by hand, fed it to Claude Code (2026), and used plan mode to keep it honest. No framework. Just a markdown file with the same sections: goal, constraints, acceptance checks, task list.

I already know Claude Code from my daily agent lineup, so there was nothing new to learn. The spec did most of the work Spec Kit's ceremony does, at a tenth of the setup.

The catch: nothing keeps the plan.md in sync. I have to update it myself. The frameworks at least nag me to.

Where it saved me

The wins were real, and they were all about ambiguity, whichever tool held the spec.

Every place my old loop bled time was a place I had not decided something. Expiry window. What happens on a re-invite. Whether an accepted token can be reused. Writing the spec forced the decision up front, once, in text. The agent then built to the decision instead of guessing and making me review the guess.

Fewer "no, not like that" rounds. That is the whole pitch, and on a feature this size it held across all three.

Where it wasted an afternoon

I also tried the full Spec Kit ceremony on a two-file bug fix. That was a mistake.

Writing four artifacts for a change I already understood added thirty minutes and zero clarity. The spec was longer than the diff. I was doing paperwork to feel organized.

And the specs rot. The invite spec was accurate on day one and stale by day four, because I kept shipping small changes straight to code without updating the doc. A stale spec is worse than no spec. It lies to the next person, including future me. The heavier the tool, the more doc there is to rot.

The one I kept

After two weeks the plain plan.md in Claude Code is what stayed on my machine.

Here is how I would route it now:

Reach for Spec Kit when the project is new and needs shared rules written down. The constitution step is the real value, and it is worth the ceremony once per project, not once per task.

Reach for Kiro when spec-and-code drift is your main pain and you can stomach switching IDEs. The side-by-side view is the tightest feedback loop of the three.

Reach for a plain plan.md when you already trust an agent and just want SDD's upside at a tenth of the setup. That was me. No new tool, most of the benefit.

Whatever you pick, keep the spec small enough that updating it is cheaper than ignoring it. The moment maintenance feels expensive, the spec is already dying.

For which agent runs the plan, that is still a Cursor versus Claude Code call for me, and it has not changed. SDD sits on top of whatever agent you already trust; the tool just decides how much ceremony rides along.

P.S. I still have not updated that invite spec. It is lying to me right now.