Spec Kit: Reducing the Gap Between What We Ask and What AI Builds

Over the last three years I’ve been using AI for everything I can in my day-to-day: brainstorming, writing, learning, code review, architecture decisions, documentation, product thinking, and of course—shipping software.

And after thousands of prompts (and plenty of frustration), I keep coming back to a simple conclusion:

When AI doesn’t give us the result we expect, it’s usually not because “AI is bad”. It’s because we didn’t give it the right context.

Yes, model choice matters. But in practice, the #1 failure mode is that we ask for a result while under-specifying the inputs, constraints, expectations, and definition of “done”.

In software engineering this mismatch becomes painfully visible. The assistant writes code, but not the code you meant. It solves a problem, but not your problem. It implements “a queue”, but not the queue library your organization standardized on. And then we blame the model.

The truth is: we’re still learning how to communicate requirements to machines.

In the early days, the “best practice” was to craft custom prompts and keep them versioned somewhere. You’d have prompts for asking questions (consulting mode) and prompts for agents that touch your code (agent mode). Then came the planning paradigm: models started doing a much better job when they could first propose a plan, you validate it, and only then implement.

Alongside that, many AI providers and tools have introduced their own conventions—files like AGENTS.md, CLAUDE.md, and similar “house rules” to steer behavior. Those can be useful, but they also come with a trade-off: they tend to couple your workflow to a specific provider or tool, reducing the versatility of switching between assistants (or using multiple ones across teams).

Planning helped—massively.

But it didn’t eliminate the core problem: the gap between what we ask and what we expect to get.

That’s where Spec Kit enters.

Why Spec Kit (and why now)

Spec Kit is a spec-driven development workflow maintained by GitHub’s community. The key idea is straightforward:

• Don’t start with code. Start with a spec.
• Make that spec actionable.
• Turn it into a plan.
• Break it into tasks.
• Implement with guardrails.

If you’ve been “asking the AI to build things”, you already know why this is needed.

The big differentiator for me is that Spec Kit solves two problems at once:

1. Tool independence: You’re not locked into a single runtime (Claude Code, Gemini CLI, Codex, Copilot Chat, Cursor, etc.). The workflow can be adopted across tools and teams.
2. Operational maintainability: You’re not maintaining a fragile pile of prompts on your own. The ecosystem evolves: commands improve, scripts improve, prompt templates improve, and you can update your workflow instead of reinventing it.

In my team we’ve been using it in production projects for a couple months and it’s been a net win: more predictable outcomes, less “prompt folklore”, and a clearer path to scaling AI-assisted development beyond a single power user.

Momentum signals: it’s not just hype

Beyond GitHub stars, you can see Spec Kit gaining—and sustaining—attention over time. One quick proxy is Google Trends for the term “speckit”, which shows a sharp rise and then a fairly steady level of interest rather than a one-week spike.

Google Trends: https://trends.google.com/trends/explore?q=speckit&hl=en-US

Another (imperfect but useful) indicator is repository activity and adoption signals. At the time of writing, github/spec-kit shows roughly:

• ⭐ ~69k stars
• 🍴 ~6k forks
• 🐛 ~500+ open issues
• 🔀 ~90 open pull requests
• 🏷️ frequent releases (latest tagged template release 0.0.94 on Feb 11, 2026)

None of these metrics alone prove quality—but together they do suggest a living project with a large user base, ongoing iteration, and an active contributor community.

The real reason AI output disappoints

Before going deeper into Spec Kit, it’s worth stating the uncomfortable part:

AI rarely fails because it can’t code.

It fails because we didn’t specify:

• Context it doesn’t have (internal architecture, domain rules, constraints, policies, existing patterns)
• Non-functional requirements (performance, reliability, observability, security)
• “How” constraints (libraries, frameworks, patterns, team conventions)
• Acceptance criteria (what should be tested, what “done” means)

So we get results that are technically plausible but operationally misaligned.

Spec Kit’s entire value is that it forces us to capture the missing information in a structured and reusable way.

Where Spec Kit fits in a real organization

A common reaction is:

“Couldn’t we do this with good prompts?”

You can—but you’ll pay for it in maintenance.

Custom prompts tend to become:

• fragmented
• outdated
• inconsistent across teams
• hard to update and roll out

Spec Kit gives you:

• an evolving community-maintained workflow
• reusable structure across repos
• a shared language for AI-driven development
• a stronger baseline for quality and predictability

And perhaps most importantly:

• it turns “prompt engineering” into organizational process, not individual heroics.

Model choice: don’t guess—use SWE-bench

Even with perfect context, model quality matters.

When you’re choosing a model for software engineering tasks, don’t rely on vibes. Track benchmarks that focus on real-world issue resolution.

A good starting point is SWE-bench (and its verified leaderboard):

• https://www.swebench.com/

The important part is not “pick the best model forever”. The ranking changes.

With a tool-agnostic workflow like Spec Kit, you can:

• use one runtime today
• switch to another tomorrow
• keep the same spec-driven discipline

That’s a major advantage over workflows that are tightly coupled to a single agent or prompt stack.

Getting started: installing Spec Kit

I’m not going to re-explain the full installation walkthrough here—Spec Kit’s README already does a great job.

For a general guide, first follow the official Get started steps in the repository (the section linked below). Once you’ve completed that baseline setup, come back here—I’ll focus on adding value at each step with practical tips and patterns that help in real projects.

There are different ways to integrate Spec Kit depending on your environment and your AI runtime, but the high-level setup usually looks like this:

1. Initialize Spec Kit in your repository
   • This creates the folder structure and baseline files.
   • You’ll often choose a shell/runtime depending on your OS (e.g., PowerShell on Windows, Bash on Linux/macOS).
2. Verify the commands are available in your assistant
   • You should see slash commands like /speckit.* in the chat/agent interface you’re using.

From there, the workflow becomes repeatable.

Official reference: https://github.com/github/spec-kit?tab=readme-ov-file#-get-started

The Constitution file: where alignment begins

After initialization, the first high-leverage step is creating the Constitution (via /speckit.constitution).

Think of it as the project’s “governing principles” for AI-driven development:

• coding standards
• test expectations
• architectural constraints
• preferred libraries and frameworks
• repository-specific conventions
• performance requirements
• security requirements
• UX consistency guidelines

The Constitution is not universal.

It should be project-specific, because the only Constitution that matters is the one that matches your codebase, your team, and your production reality.

The compounding effect

One of my favorite parts of this workflow is what happens over time:

• Every time the AI misses something important (wrong library, wrong pattern, missing tests, ignoring a constraint)
• You don’t just “fix it once”
• You encode the expectation into the Constitution

Over weeks, that reduces drift.

You progressively reduce the mismatch between:

• what you asked
• what the AI built
• what you actually needed

The Spec Kit flow: four main steps

Similar to what I mentioned in Getting started: installing Spec Kit, I won’t rehash the official walkthroughs here. Spec Kit’s README already documents the step-by-step outputs and the exact artifacts/files to review in great detail.

If you want the canonical, detailed reference, review the Detailed process section in the repository and then come back here—I’ll keep this part focused on a high-level mental model plus a few practical tips for each step.

Official reference: https://github.com/github/spec-kit?tab=readme-ov-file#-detailed-process

Spec Kit is easy to remember because it’s basically four phases:

1. Specify the feature
2. Plan the feature
3. Generate tasks
4. Implement

But the real power comes from the supporting commands and the operational habits around the flow.

Below is the version of the workflow I recommend in real teams.

Step 0: start from an existing task description (optional, but practical)

(Optional nuance for teams that don’t rely on Git branches: Spec Kit also supports selecting the current feature/spec context via environment variables—see the official docs for SPECIFY_FEATURE.)

In many organizations the feature already exists as a description—Jira ticket, product spec, Notion page, email, whatever.

If you already have a good description, put it in a task.md file (markdown) and let Spec Kit start from there.

Example framing you can use:

• /speckit.specify Specify the task defined in task.md.

That small step makes the process much more “real-world compatible”: you’re not forced to rewrite the ticket in the chat.

Step 1: Specify

The Specify step produces the feature spec (often spec.md).

At this stage you want:

• user-facing goal
• scope and non-goals
• constraints and assumptions
• acceptance criteria
• edge cases
• impacted components

After specify: use Clarify

A common issue is that a spec looks “complete” but still has missing details.

That’s why one of the best follow-up commands is:

• /speckit.clarify

It helps you identify underspecified areas by asking up to five targeted clarification questions, and then encoding your answers back into the spec.

This step alone can remove a surprising amount of ambiguity early—before it becomes implementation debt.

Step 2: Plan

Now you turn your spec into an actionable plan (plan.md).

The goal is not just to list steps, but to surface:

• dependencies
• migration strategies (if any)
• testing strategy
• rollout/feature flags
• backward compatibility
• risks and mitigations

Planning is where the AI starts behaving like a senior engineer: it’s forced to reason about order, impact, and trade-offs.

Optional: Checklist (a quick quality gate)

Depending on the project, it can be helpful to run /speckit.checklist here to sanity-check expectations before you break the work into tasks.

Step 3: Tasks

This generates a tasks list (tasks.md) that breaks the plan into implementable units.

Ideally tasks are:

• small enough to review
• scoped enough to avoid “vibe coding”
• sequenced logically
• tied back to acceptance criteria

After tasks: use Analyze

Before you implement, it’s smart to validate the consistency across artifacts:

• /speckit.analyze

This performs a non-destructive cross-artifact analysis across spec.md, plan.md, and tasks.md.

It’s a quality gate that catches:

• inconsistencies (plan doesn’t match spec)
• missing requirements
• unclear tasks
• low-confidence areas

Step 4: Implement

Finally, implementation.

At this point, the assistant is no longer guessing what “done” means—it has:

• your Constitution
• your spec
• your plan
• your task breakdown

That’s the difference between “AI wrote code” and “AI shipped the feature we wanted”.

It may feel slower (and it costs more tokens)—but it usually wins

One honest downside of Spec Kit is that it adds more verification stages. Compared to jumping straight into coding, the workflow can feel slower because you’re spending time on artifacts (spec → plan → tasks) before writing implementation.

In practice, that time is often paid back—quickly.

Those extra checkpoints reduce the amount of rework later, because you spend less time:

• debugging misunderstandings
• rewriting entire chunks of code
• arguing with the assistant about requirements you never wrote down

There’s another trade-off: yes, it tends to consume more tokens.

But if your goal is reducing the gap between what you asked for and what you needed, the improvement in alignment usually outweighs the extra token cost.

If you’re a bit token‑poor

If you’re a bit token‑poor (or simply cost-conscious), a practical strategy is:

• Run Specify / Plan / Tasks using a stronger, more capable model
• Then Implement using a model with a better cost/performance balance

This works well because the high-value reasoning happens early, and the implementation step can follow the already-agreed structure.

Of course, the rule still holds: better models usually produce better outputs—this strategy doesn’t change that. It just helps you allocate your budget where it matters most.

Editing after the fact: how to iterate without losing the thread

Real development is iterative.

You will run a step, review the output, and realize:

• a requirement is missing
• a constraint needs tightening
• acceptance criteria should change
• the plan needs a new task

The practical trick is: don’t rerun everything from scratch.

Instead, tell the assistant what to change and give it the full context by referencing the spec folder.

For example, you can say:

• “Update the acceptance criteria to include X and ensure we use Y library. Use @specs/00X-spec-title/ as context.”
• “Also consider @task.md (original task description) so we don’t lose any requirements.”

This keeps the workflow grounded and prevents the assistant from drifting away from the original intent.

Context rot: why “new chats” can improve quality

A subtle failure mode in long agentic sessions is what Chroma research calls context rot (reference: https://research.trychroma.com/context-rot).

In simple terms:

• as the number of tokens in the context window increases,
• the model’s ability to accurately recall information from that context decreases.

It’s not just about “having a huge context window”. Reliability across long contexts is uneven.

The habit that helps

For many teams, a surprisingly effective practice is:

• After completing each Spec Kit step (specify → plan → tasks → implement)
• Start a new conversation for the next step

The idea is to “clean the context”, reduce noise, and avoid compression artifacts that cause the model to forget or distort earlier details.

Versioning strategy: what to commit (and why it matters)

Depending on your team’s workflow, you may choose to version-control all, some, or none of the artifacts Spec Kit generates (specs, plans, tasks, etc.). There isn’t a single “correct” answer—what you commit should reflect how your team collaborates and how you want knowledge to persist over time.

My recommendation, whenever possible, is to treat specs as first-class project assets:

• Let each developer decide how they run Spec Kit locally with their preferred AI/tooling.
• But aim to keep the resulting feature artifacts versioned in the repo (at minimum the Constitution file, plus the final spec.md, and often plan.md / tasks.md).

Parallelism in Spec Kit: planning vs. real execution

Spec Kit’s “parallelism” is planning-level parallelism. In tasks.md, it marks tasks as parallelizable with [P] (parallel execution markers). That means: from a dependency/sequence perspective, these tasks can be done in parallel.

What Spec Kit does not do is orchestrate real parallel execution. It’s not a scheduler or multi-agent runtime: it doesn’t spin up multiple concurrent agents, coordinate shared state, or automatically merge branches/PRs. Whether tasks actually run in parallel depends on the runtime/tool you’re using (Codex CLI, Gemini CLI, Claude/Cloud Code, Cursor, etc.)—or on you coordinating it manually.

So when we talk about Spec Kit parallelism in this post, we mean planning parallelism (the [P] signal). Execution parallelism is out of scope because it’s a capability of the runtime/tooling.

Why this is still useful: if your runtime supports parallel agents (e.g., Claude Code and similar tools), Spec Kit can feed it a clean, structured plan where [P] tasks can be handed to different agents/sub-agents to execute concurrently without stepping on each other.

Example — parallel hardening work

• [P] Add tests for digest generation
• [P] Add logging/metrics + review-queue persistence

Same logic: parallelizable by dependencies. Real concurrency happens only if your runtime (or your workflow) runs them concurrently.

Why versioning the feature artifacts pays off

Some developers complain that this creates “too much documentation” and becomes hard to maintain. That’s a fair concern—but it’s also a good problem to have.

Having the documentation is almost always better than not having it. The management challenge is real, but it’s solvable—and the benefits compound:

• You preserve the why behind code changes, not just the diff.
• Future contributors can re-run or extend a feature with far less context loss.
• You build an organizational memory that reduces repeated debates and repeated mistakes.

I won’t cover “how to manage hundreds of specs over years” in this post, but it’s an important consideration when scaling.

A powerful secondary use case: planning and estimation

Once you have a history of versioned feature specs, you can reuse them for workflows that happen before code is written:

• drafting new work items (e.g., a Jira ticket)
• doing early scoping and estimation
• identifying blockers and cross-feature impacts

This is valuable for technical leads and project managers, because an AI that has access to:

• the repository code
• and the repository’s prior feature specs/plans/tasks

can surface things that humans often miss during early estimation—hidden dependencies, architectural constraints, or unintended impacts across existing features.

That can improve the quality of planning and even the accuracy of estimates, even if the actual implementation happens later.

Advanced / Team setup

The following sections cover operational and team-level topics. They’re not needed to get started with Spec Kit, but they become relevant once you’re adopting the workflow across a team or integrating it with existing infrastructure.

Guardrails for tool execution: don’t give the AI “root” by default

This isn’t Spec Kit–specific, but it’s one of the best habits you can adopt when working with agentic tools (Codex, Claude Code, Gemini CLI, Cursor, etc.): avoid the default tendency of letting the AI execute any command it wants.

Instead, configure per AI/runtime a small allowlist of commands you’re comfortable letting it run without asking. Everything else should require an explicit prompt/approval from you.

Why it matters:

• It reduces the blast radius of common mistakes (wrong command, wrong directory, destructive flags).
• It protects you from “helpful” actions that become risky the moment the environment has internet access, credentials, or sensitive files.
• It forces the AI to slow down only at the boundaries that matter (network, filesystem, package managers, infra changes), while still keeping you fast for safe, routine operations.

Practical guidance:

• Start with a conservative allowlist (read-only or low-risk commands), then expand it as your team gains confidence.
• Be extra strict around anything that:
  • reaches the network
  • touches secrets/credentials
  • installs dependencies
  • mutates infra or production-like resources

Yes, at first this can feel like it hurts velocity—but in practice it’s a huge safety net and prevents exactly the kind of “it ran something I didn’t mean” incidents that kill trust in AI-assisted development.

Optional add-on: Git hooks to enforce Spec Kit hygiene

If you want Spec Kit to be used consistently across a team, one practical add-on is Git hooks (e.g., pre-commit, commit-msg, or even pre-push). Hooks let you run lightweight checks before a commit lands—so you can enforce the basic “Spec Kit discipline” without relying on manual reminders.

Examples of checks you can implement:

• Require spec artifacts when code changes are present
  • If a commit touches src/ (or your main app folders), ensure there’s a corresponding change in specify/.
• Block commits that add code without a spec reference
  • A common rule: “If you’re implementing a feature, the related spec (or update) must be included in the same commit.”
• Validate presence/structure of required files
  • E.g., ensure key spec files exist (or follow your naming convention) before allowing the commit.
• Automated, AI-assisted checks (optional)
  • You can write hook scripts that call an AI model to do basic validation, like:
  • verify the commit includes the right spec files
  • detect “spec drift” (code changed, spec didn’t)
  • enforce a short checklist (acceptance criteria present, risks section filled, etc.)

Implementation notes:

• Hooks are just scripts, so you can keep them in-repo and provide a bootstrap command to install them.
• Keep them fast and predictable; if AI is involved, make it optional or run it in pre-push rather than pre-commit.

The core idea: turn Spec Kit from “a recommendation” into “a workflow guardrail,” so the team naturally keeps specs and implementation in sync.

Switching AI runtimes (Codex → Claude, Gemini, etc.) without losing track

If you already have Spec Kit set up with one AI runtime (say Codex) and you want to switch to another (say Claude), there’s no dedicated “add/switch AI provider” command today. The pragmatic way is to re-run the init for the AI integration, but do it in a way that makes every change auditable.

Here’s the workflow I recommend:

1. Stage your current specify/ artifacts

bash git add specify/

1. Re-run Spec Kit init targeting the new AI runtime

bash specify init . --ai claude

Replace claude with whatever runtime you’re switching to.

1. Review the diff carefully

bash git diff --cached git diff

1. Protect your Constitution

The main “gotcha” is the Constitution file: you don’t want the init step to overwrite or drift it.

• Verify the Constitution wasn’t modified unexpectedly
• If it was, revert and re-apply only the changes you actually want

This gives you a clean, reviewable migration path: you switch runtimes, keep your artifacts intact, and you can prove exactly what changed.

A quick note on branches (how we handle it in practice)

In many setups, running the early Spec Kit commands (especially around Specify) will end up creating a Git branch named after the spec/feature.

At the time of writing, Spec Kit doesn’t make it particularly clear how to customize that behavior—and we intentionally avoid patching Spec Kit itself, because carrying local modifications means extra maintenance and potential conflicts when updating to newer versions.

Our pragmatic workflow is:

1. Create the branch we actually want to work on (based on our branching strategy).
2. Once that branch exists, run the Spec Kit commands on top of it.
3. When we’re done, we either:
   • keep committing directly to that branch, or
   • merge the Spec Kit commits into the branch we originally intended (depending on the repo’s workflow).

This keeps us compatible with upstream Spec Kit while still fitting into our team’s Git conventions.

The feedback loop: encode missing expectations into the Constitution

If you only take one operational lesson from this post, make it this one:

When the assistant misses something that matters, you have two options:

1. Keep fixing it manually forever
2. Add it to the Constitution so the next features don’t repeat the mistake

Example:

• You want queue + background job processing implemented using a specific library.
• The AI picks a different approach.

Don’t just rewrite the code. Update the Constitution:

• “For queueing and background jobs, use Library X and follow Pattern Y.”

Over time, this becomes a compounding asset.

Closing thoughts

Spec Kit is not magic.

It won’t replace engineering judgment. It won’t remove the need to review code. And it won’t save you from unclear product requirements.

But it does something very valuable:

• it makes your intent explicit
• it makes AI output more predictable
• it gives teams a shared workflow
• it reduces drift between request and result

If you’ve felt the frustration of “AI almost did it, but not quite”, Spec Kit is a practical step forward.

And if you’ve been blaming models for outcomes that are really caused by missing context, this workflow will force a healthy shift:

Don’t ask the model to guess. Teach the model what matters.

Credits

Written with love by Agustin Martinez with the help of GPT‑5.2 and Gemini 3 Pro.

Special thanks to the AI Lab for contributing important insights while working through—and organizing—shared knowledge.

Agustin Martinez Head of AI Engineering