spec-kit is GitHub’s toolkit for spec-driven development: you define what to build before building it, and any of 30-odd AI coding agents does the implementing. The core loop is constitution → specify → plan → tasks → implement, and there’s a handful of extras listed as optional — clarify, analyze, checklist.

I’ve been running it across several projects now. My single strongest finding is that the optional step is the one that pays for everything else.

If you keep one command out of the whole toolkit, keep /speckit.clarify — the pass that interrogates your spec for ambiguity before planning starts.

Why clarify matters more when an agent writes the code

Here’s the pattern that repeats. A feature request sounds complete. You read it, it makes sense, nothing’s obviously missing. Then the clarifying pass asks two or three questions and every one of them changes the data model:

• Is this number captured or derived?
• Is this total the sum of its parts, or an independently reported figure that happens to land close to the sum?
• Is visibility all-or-nothing per role, or per row?

Those aren’t edge cases. Each one silently determines a schema. Get one wrong and the rework reaches all the way back to your migrations.

None of that is new. Ambiguous requirements have always been expensive, and teams have been interrogating specs for ambiguity since long before any of this was automated. What changed is what happens to an ambiguity that slips through.

A human engineer, hitting a genuinely ambiguous requirement, stalls. They wander over to your desk, or drop a message in the channel, and ask. The ambiguity surfaces itself because a person got stuck on it.

An agent doesn’t get stuck. It resolves ambiguity by picking something plausible and moving on — quickly, confidently, and the result looks finished. You get a complete-looking implementation built on a guess nobody reviewed. The ambiguity never surfaces as a question; it surfaces three weeks later as a schema you have to unwind.

That’s the whole argument for clarify. The step exists to force the questions into the open before there’s code, because the mechanism that used to surface them for free — a confused human — isn’t in the loop anymore.

The second payoff nobody mentions: specs are a decision record

An underrated side effect showed up when a governance question came up late on one project: does this architectural decision need to be formally recorded?

The answer was defensible, and it was defensible because the design decisions were already written down — at the time they were made, with their reasoning attached.

That’s the thing teams almost never have and always want six months later. And with spec-kit it’s essentially free: spec.md and plan.md already exist, written to direct the work. They just need to live somewhere durable. Planning documents you wrote to steer an agent turn out to double as the record of why the system is the way it is.

Worth optimizing for deliberately. If your specs are getting deleted with the branch, you’re throwing away the most valuable artifact of the process.

The failure mode: verification tasks are the ones that get skipped

Now the part that bit me hardest, because it’s structural rather than occasional.

The most reliable failure in any checklist-driven workflow: the feature works, so the tail of the list quietly stops getting done.

A concrete case. One slice was considered complete for weeks — functionality working, everyone moved on. An audit later found its final tasks had never been run. Among them was a design-consistency check, which then turned up three shipped screens with no approved design at all.

Nobody lied. Nothing was hidden. The work simply felt finished once the functionality worked, and everything remaining in the list was verification.

That’s the trap: a checked-off task list creates false confidence precisely where verification lives. The last phase is the one that proves the rest — and it’s also the one most likely to be abandoned, because by the time you reach it the interesting part is already done.

Two mitigations that actually work:

1. Run /speckit.analyze before declaring anything done. Cross-artifact consistency analysis is another of those “optional” commands, and it’s how you catch the gap between what the spec said and what got built.
2. Treat an unchecked box in the final phase as blocking, not cosmetic. If the phase that proves the work is optional, you don’t have verification — you have a nice list.

Structural things worth designing around

A few sharper edges I hit, all of which generalize past spec-kit to any spec-driven setup:

Don’t bind artifacts to branch names. Any convention that resolves “the spec for the current work” from the branch name breaks the moment a branch gets renamed, or an umbrella/integration branch exists. The failure mode is the bad part: a gate that can’t find its config tends to silently pass rather than loudly fail. Resolve from an explicit marker in the repo, and make “no spec found” an error rather than a default-allow.

Approval gates should check specificity, not existence. A gate that greps for “is anything approved?” green-lights everything the moment one thing is approved. Approvals need to bind to the specific artifact and version they approved, or they decay into ceremony that costs time and buys nothing.

Shared, auto-generated files are merge magnets. If a workflow appends to one shared file on every planning run, that file conflicts on every merge between parallel workstreams — always additively, always tediously. The structural fix is one file per feature, aggregated on read, rather than every branch rewriting a common file. (I tried solving it with a union merge driver first. That just produces duplicated headers — treating the symptom.)

Namespace your task IDs. If every feature’s tasks start at T001, then “T013” is ambiguous the second you have two features in flight.

When it’s worth it, and when it isn’t

Be honest about the overhead: this loop is worth it when the work is genuinely uncertain — new domain, real design decisions to make, several slices to coordinate. For well-understood work, it’s ceremony. Adding constitution → specify → clarify → plan → tasks to a task you could describe in one sentence is how spec-driven development gets a bad reputation.

And the valuable output isn’t the plan. Plans go stale, usually fast. The value is:

1. The ambiguities forced into the open before any code got written.
2. The written record of why each decision went the way it did.

Both of those got more valuable with agents in the loop, not less — because the implementation step got dramatically cheaper, and deciding what to build didn’t get any cheaper at all. When writing the code is the expensive part, spending a day on specs feels like overhead. When an agent writes the code in twenty minutes, the spec is the work.

Which is the real reason to run the optional step. clarify is where you do the only part of the job that hasn’t been automated yet.