Spec-Driven Development with GitHub Spec Kit: From Intent to Implementation

Every team working with agentic coding tools eventually runs the same experiment. You hand the agent a feature request phrased the way a human colleague would phrase it - "add CSV export to the reports page" - and you get back something that compiles, demos well, and is wrong in four ways nobody enumerated: it exports the filtered view instead of the full dataset, invents its own date format, skips the permission check, and quietly adds a dependency your platform team banned last quarter. None of that is the model being careless. It is the model filling in every blank you left, and a one-sentence prompt is mostly blanks.

GitHub Spec Kit is the most complete answer we have seen to that problem. It is an open source toolkit for spec-driven development: turning vague intent into precise, machine-readable specifications that AI coding agents can actually act on, then using those specs to drive implementation with minimal drift. We have been running it in client engagements since it launched, and it has earned a permanent place in how we teach agentic development.

Why specs beat prompt-driven iteration

Prompt-driven development treats every gap between intent and output as a conversation problem: the code is wrong, so you prompt again, and again, steering by correction. For small changes that loop is fine. For complex features it fails for a structural reason - the requirements never exist anywhere except scattered across a chat transcript. Each correction lives in context that will be compacted, summarized, or simply forgotten by the next session. Two weeks later, neither the humans nor the agents can say what the feature was actually supposed to do.

Spec-driven development inverts the flow. You spend your effort where ambiguity is cheapest to remove - before implementation - and produce an artifact that survives the conversation. The spec becomes the durable statement of intent: reviewable by humans, consumable by agents, and versionable in Git right next to the code it describes. When the implementation drifts, you have something to check it against. When you switch tools, or models, or teammates, the spec carries the knowledge forward.

Anatomy of a Spec Kit workflow

Spec Kit installs as a CLI (specify init, via uv or pipx) that scaffolds templates and slash commands into whichever agent you use. The workflow is a chain of Markdown artifacts, each one structured context for the next step:

• constitution.md captures your project's non-negotiables: code quality standards, testing expectations, architectural principles, the things every feature must respect. You write it once with /speckit.constitution and every later phase checks against it.
• spec.md, produced by /speckit.specify, is the heart of the system: the goals and user stories (the what and the why, deliberately free of tech stack), functional requirements precise enough to test, explicit open questions, and acceptance criteria that define done.
• plan.md, from /speckit.plan, holds the implementation notes: architecture, data model, API choices, and the technical constraints you impose ("use the existing report service; no new dependencies").
• tasks.md, from /speckit.tasks, breaks the plan into small, ordered, independently verifiable units of work, with parallelizable tasks marked.

The separation matters more than it first appears. Keeping what and why (the spec) apart from how (the plan) means product-level review can happen without wading through technology debates, and the same spec can outlive its first implementation.

Writing specs agents can follow

A spec an AI agent can execute against reliably has three properties, and they are the same properties a good spec for a human junior engineer has, enforced more strictly.

Specificity. "Export should be fast" is a wish; "export of 100,000 rows completes in under 10 seconds" is a requirement. Agents amplify vagueness: whatever you leave undefined, the model will define for you, confidently.

Constraints. State what must not change: public API shapes, dependency policy, files that are off limits. Constraints are how you keep an eager agent from "helpfully" refactoring your authentication layer on the way to adding a button.

Acceptance criteria. Concrete, checkable statements the agent can verify against - ideally ones that map directly to tests. When the acceptance criteria are executable, "done" stops being a feeling.

Spec Kit's templates push you toward all three, and the toolkit is refreshingly honest about ambiguity: rather than letting the model paper over gaps, the workflow marks underspecified areas explicitly, and /speckit.clarify interrogates you about them one question at a time before planning begins. In our experience this clarification pass is where most of the value lives. It is uncomfortable in exactly the way good requirements work has always been uncomfortable.

Walkthrough: from raw intent to reviewable spec

Here is the shape of a real session, condensed from one we run in training. The raw intent: "Team leads need a weekly digest of stale pull requests."

Running /speckit.specify on that sentence produces a first-draft spec with user stories ("as a team lead, I receive a digest every Monday listing PRs with no activity for 7 days...") and functional requirements - and, more importantly, a list of open questions the model was honest enough not to answer for itself. What counts as activity: comments, commits, or both? Per-team or per-repository? What happens on empty weeks? Email, Slack, or in-app?

/speckit.clarify walks through those questions sequentially. Five minutes of answering ("comments or commits; per-team; skip empty digests; Slack now, email later") and the answers are folded back into the spec, not lost in chat. A pass with /speckit.checklist then grades the spec itself - are the requirements testable, consistent, complete? Think of it as unit tests for English. What comes out the other end is a one-page document a product owner can review line by line, and that review happens before a single line of code exists, where changing course costs nothing.

Driving Copilot and Claude Code from the spec

Spec Kit is agent-agnostic: the same workflow drives GitHub Copilot, Claude Code, Gemini CLI, Cursor, and a long list of others, which also makes specs a portability layer as the tool landscape keeps shifting. With the spec and plan settled, /speckit.tasks and /speckit.implement execute the work task by task, each one small enough to review as an ordinary diff.

This is where drift control pays off. The agent is not improvising from a prompt; it is executing numbered tasks against a spec and a constitution, and /speckit.analyze cross-checks the artifacts for inconsistencies before implementation starts. When the model wanders - and models still wander - the correction is not "that's not what I meant" but "task 7 violates requirement FR-3," which is a conversation both parties can resolve precisely. Scope creep becomes visible because scope is written down.

Specs as living documents

The failure mode of every specification methodology since the waterfall era is the spec that was true on day one and fiction by day thirty. Spec Kit's answer is to make the spec cheap to keep current: it lives in the repo, changes through pull requests like everything else, and the newer /speckit.converge command assesses an existing codebase against its spec and reports where reality has diverged, which turns "is the spec still true?" from an archaeology project into a command. Requirements change mid-build; that is not a process failure. The discipline is folding the change into the spec first, then letting the agent re-plan, so the artifact stays authoritative instead of becoming a historical curiosity.

The deeper shift here is one we keep seeing across agentic engineering: as implementation gets cheaper, the scarce skill moves upstream - to specifying what should exist and reviewing what was built. Teams that write precise specs are compounding an advantage right now.

We teach this workflow hands-on, from first constitution to converge-driven maintenance, in Spec-Driven Development with Spec Kit, and the surrounding skills of steering agents in AI for Software Developers and Prompting and Context Engineering for Software Engineers. If your team is ready to move from vibe coding to something you can review, we would love to help.