Last November, I was three days into building a Slack digest agent on agent-S (a personal side project) when I realized I’d been coding for two hours without a clear spec. Claude had been helpful. The code looked reasonable. And yet when I sat back and asked “does this do what I actually want?” I couldn’t answer. I’d been optimizing before I’d finished thinking.
That was the moment I committed to spec-first AI development. Not as a philosophy. As a practical constraint.
Over the following months, I worked with two tools built around this constraint: Spec-kit, which I built into the agent-S project in November 2025, and OpenSpec, a CLI tool I adopted at for my projects in 2026. Both tools start from the same premise — AI assistants write better code when forced to work from a specification first — but they model it very differently. The gap between them reveals something important about where AI-assisted software engineering is heading.
What these tools actually are
Spec-kit lives entirely inside Claude Code slash commands. You start a feature with /speckit.specify, walk through clarify → plan → tasks → analyze → implement → checklist, and the tool keeps you honest at each step. The conceptual centerpiece is what Spec-kit calls a constitution: a project governance document you create once, capturing non-negotiable principles (function length limits, naming conventions, complexity thresholds, testing philosophy). Every subsequent spec validates against it. The /speckit.analyze command runs cross-artifact consistency checks with four severity tiers: CRITICAL, HIGH, MEDIUM, LOW.
OpenSpec can be installed in any AI Assisted coding tool. You run `openspec init and select the tool you’re using and it will install it. There’s no precise starting point : you can start with /opsx:new if you know what you want to build or /opsx:explore if you want to brandstorm.
Where each earned its keep
For the Slack digest agent spec in agent-S, Spec-kit produced something I didn’t expect: 100% requirement coverage on the first analysis pass (one spec, one project). The /speckit.analyze output showed every functional requirement mapped to at least one task, zero critical issues, and three medium ambiguities, all resolvable. The three-clarification-maximum rule forced decisions instead of deferrals. The constitution caught a scope creep attempt: I’d started writing implementation details into what should have been a business-level spec.
That last point carries weight. Without the constitution, I would have accepted a spec containing implementation details. With it, the analyze command flagged it CRITICAL: implementation detail in business spec.
OpenSpec’s earned moments were different. In another repo, one completed change produced four distinct spec files, one per capability, before a single line of design was written. Each spec was narrow, focused, independently reviewable. When a junior engineer picked up the task three weeks later, the proposal explained why the change was needed; the per-capability specs described what each piece needed to do; the design file showed how the pieces fit together. They didn’t need to ask me anything.
That’s the signal OpenSpec optimizes for: handoff clarity. Not just “does the AI understand?” But “does the human reading this three weeks later understand, too?”
Where each struggled
Spec-kit’s weakness is constitution setup. It’s a sound concept that adds upfront friction. New projects need a constitution before the quality gates mean anything; without one, /speckit.analyze validates against a blank template. The spec-to-code path also has no feedback loop: once you enter the implement phase, you’re on your own.
There’s a deeper problem. The constitution model works best for solo engineers who remember why they wrote each principle. When I returned to agent-S after two weeks, some principles felt arbitrary. I couldn’t reconstruct the context behind them. The governance document had outlived its author’s short-term memory.
OpenSpec’s weakness is the one-artifact-at-a-time constraint. It’s the right constraint for preventing AI runaway generation (the tendency for AI to elaborate beyond scope when not constrained). But it makes the workflow feel slow when a change is small and obvious. The /opsx:ff fast-forward command exists precisely because this constraint chafes. Whether that means the constraint is right and /opsx:ff is a pragmatic accelerator, or that the constraint is too strict and /opsx:ff is a correction, I’ll leave to you — but the tradeoff is real.
The five signals that tell you which tool to use
Five signals clarify the comparison. Here’s what I’d measure:
Spec-to-code drift. How much does the final implementation match what was specified? Both tools aim to reduce this, but Spec-kit’s constitution catches drift caused by accumulated project-level decisions: naming conventions, function length limits, testing philosophy. Individual specs don’t capture these. The constitution does.
Clarification latency. How many back-and-forth cycles does it take to lock a spec? Spec-kit enforces a maximum of three clarification markers per spec. OpenSpec lets the proposal absorb open questions naturally, which is more flexible but less disciplined. Solo work needs discipline more than flexibility; team work needs the reverse.
Artifact coverage. What percentage of requirements have corresponding implementation tasks? Spec-kit’s analyze command makes this explicit and auditable. OpenSpec achieves coverage implicitly through the per-capability spec discipline: you can’t skip a capability because the tool generates a spec file for it.
Change archival rate. Of all changes started, how many reach archived status? This is a proxy for completion discipline. OpenSpec’s archive creates visibility: openspec/changes/archive/ holds a timestamped record of every completed change. Spec-kit has no equivalent.
Rework rate after implementation starts. How often do specs change once coding begins? Spec-kit’s constitution is theoretically the strongest lever here; it catches misalignment early. In practice, it only works if the constitution is current, and keeping it current requires discipline the tool doesn’t enforce.
Which delivered better
Spec-kit delivered better for solo greenfield work. The constitution concept alone justified the experiment. It’s the first mechanism I’ve used that codifies project philosophy at a level AI assistants can actually check against. The constitution doesn’t just guide humans; it constrains the AI’s quality validation. The linear workflow also prevented over-specifying, which is easy to do when an AI is ready to flesh out any detail you hint at.
OpenSpec delivered better at the team and enterprise level. The proposal → spec → design → tasks chain forces collective clarity before anyone writes code. Archiving creates institutional memory. The schema system standardizes workflow across different project types without each team maintaining their own slash commands. And OpenSpec is a CLI tool, not a set of Claude commands, which means it works identically regardless of which AI tool your team uses.
What I don’t know yet
The spec-to-code drift metric is difficult to measure rigorously. I tracked it subjectively. A real benchmark would require comparing final code against original specs across multiple projects with explicit scoring criteria. I don’t have that data.
The constitution model is hard to evaluate over long time horizons. My longest agent-S session ran about six weeks. OpenSpec’s oldest archived change is four months old. Neither observation window is long enough to see how these tools hold up as projects age and teams turn over.
The spec-to-team-size relationship is unclear to me. Spec-kit’s constitution approach might work well at two engineers. Whether it survives five is an open question I haven’t been able to test.
There are other tools in this space — Autospec, Spec Kitty, cc-sdd, among others — that I haven’t used long enough to compare. This article covers only the two I’ve worked with directly.
The broader point
Neither tool replaces thinking. Both make the thinking visible, and more importantly, checkable.
The real value of spec-driven development with AI isn’t that the AI writes better code. It’s that the process forces you to articulate what you actually want before you ask for it. That turns out to be the hard part, whether you’re building a Slack digest agent on a Saturday afternoon. And I think this is where we’re witnessing maybe the birth of a new discipline : intent/goal engineering. Without intent the context is worthless, no matter how well we’re engineering it.
The difference between good and great spec tooling isn’t the artifact format. It’s whether the tool creates the right stopping points: moments where you’re forced to ask, before we go further, does this still make sense?
Both Spec-kit and OpenSpec do that. They do it differently. For different contexts, one outperforms the other.
The question I keep turning over: what would a spec tool look like that works equally well for both? I’ve started thinking about it. I don’t have an answer yet.