Spec-Driven Development
Write a Spec Before You Prompt an AI Coding Agent
GitHub's Spec Kit is GitHub's own open-source project. This guide is independent and not affiliated with or endorsed by GitHub.
Most frustration with AI coding agents traces back to the same root cause: a vague request produces a vague result, and you only find out what you actually wanted after reading code that doesn't match it. A spec fixes the order of operations. Before you send a single prompt, you write three short things in plain language: what the thing should do, who it's for, and the specific checks that tell you it's finished. None of that requires knowing how to code. GitHub's Spec Kit, an open-source toolkit maintained in GitHub's own repository, builds a structured, repeatable process for coding agents around exactly this habit, with its own command-line tool and a named sequence of steps running from a project's guiding principles through to a working build. This guide covers the three-part spec you can write by hand in five minutes, how Spec Kit's workflow turns the same idea into separate commands, and when installing the full toolkit is worth it versus just writing the spec yourself.
A spec is a short, plain-language brief you write before asking any coding agent to build something: what it does, who it's for, and the done-when checks that prove it's finished. GitHub's Spec Kit, an open-source toolkit built in GitHub's own repository, turns that habit into a repeatable workflow with its own commands for setting principles, writing the spec, planning, breaking the plan into tasks, implementing, and converging, and its documentation names agents it connects to, including Anthropic's Claude Code and GitHub Copilot. You don't need the toolkit to get the benefit: typing the same three-part brief as your first message works with any coding agent you already use.
Published
Free lesson · no account neededMeet ClaudeWhy Claude?6 minStart the free lessonKey Takeaways
- A spec is three things written before the first prompt: what the agent should build, who it's for, and the done-when checks that prove it's finished.
- GitHub's Spec Kit is a free, open-source toolkit, MIT licensed per its own repository, that turns this habit into six named commands: a constitution, a spec, a plan, a task list, implementation, then convergence.
- You don't need Spec Kit to benefit from a spec. Typing the same three-part brief as your first message works in Claude Code, OpenAI's Codex, Copilot, Anysphere's Cursor, or any other coding agent.
- Spec Kit's own setup documentation names the coding agents it connects to by an integration key, including Claude Code and GitHub Copilot, with a path for adding others.
- Skipping the done-when checks is the most common way a spec fails quietly: without them, neither you nor the agent can tell whether the task is actually finished.
Copy and Paste
Prompts You Can Use Today
A three-part spec to open your first chat with
Here is the spec for what I want you to build. WHAT IT DOES: a script that sorts the files in my Downloads folder into dated subfolders by file type. WHO IT'S FOR: just me, running it by hand from the terminal, no other users. DONE WHEN: running it on a test folder of 20 sample files sorts every one into the correct subfolder, nothing outside that folder is touched, and I can undo the whole run with one command. Ask me anything you need before you start building.
Paste this as your very first message, before any back-and-forth about how it should work.
Asking an agent to turn a vague idea into a spec
I want to build something, but my idea is still vague. Here's roughly what I'm picturing: describe your rough idea in a sentence or two here. Before writing any code, ask me questions until you can state back to me, in three short parts, what this does, who it's for, and how we'll both know it's done. Don't start building until I confirm all three parts out loud.
Useful when you know the shape of the problem but haven't pinned down the details yet.
Checking the done-when checks before approving a build
Before you start implementing, list the specific checks you'll run to prove this is done: what you'll test, what the expected result is for each one, and what counts as a failure. If any check needs something you can't verify yourself from inside this session, tell me now instead of assuming it will work later.
A good agent should be able to answer this in detail before writing a line of code.
The Core Habit
Why a Spec Comes Before the Prompt
Typing a request straight into a coding agent feels faster than writing anything down first, and for a genuinely trivial task it often is. The trouble starts on anything with more than one reasonable interpretation: the agent picks one, builds toward it, and you don't find out it picked the wrong one until you're reading finished code. Every round trip from there costs more than the few minutes a spec would have taken.
A spec reframes the order of operations. Before any code gets written, you write down three things in plain language: what the thing should do, who it's for, and the done-when checks that prove it works. None of this is a technical document. It's closer to the note you'd leave a capable assistant who's never met you: enough detail that they don't have to guess at the parts that matter.
It works for a simple reason. The agent stops filling gaps in your request with its own assumptions, because there aren't as many gaps left to fill. And you stop discovering what you actually wanted by reading the agent's output after the fact, because you already wrote it down before asking for anything.
None of this is specific to one tool. Claude Code, Codex, Copilot, Cursor, and every other coding agent all work the same basic way: plain-language instructions in, code and commands out. A spec changes what goes in, which changes what comes back, whichever one you're talking to.
The Three-Part Spec
What Goes Into a Spec You Can Write in Five Minutes
Four short parts, in plain language. Nothing here requires knowing how to code.
What It Does
One or two sentences describing the behavior, not the implementation. "Sorts files by type into dated folders," not a description of which functions or libraries to use.
Who It's For
Just you, running it by hand? A coworker who's never seen the project? That answer changes what you actually need built, often more than the feature description does.
Done-When Checks
The specific, testable conditions that prove the build is finished. This is the part most people skip, and the part that matters most when something goes wrong.
Guardrails
Optional, but worth adding when the stakes are real: what the agent must never do, such as touching files outside one folder or sending anything automatically.
An Open-Source Structure for This
How GitHub's Spec Kit Turns a Spec Into a Workflow
GitHub's Spec Kit is an open-source toolkit, maintained in GitHub's own repository under the MIT license, built to give AI coding agents structured processes, reusable templates, and documented outcomes rather than one-off conversations. It installs through its own command-line tool, and its own README describes it as a toolkit for getting started with spec-driven development, or any other structured process you want an agent to follow.
The core spec-driven workflow, per the project's own documentation, runs through a named sequence of six commands: one sets a project's guiding principles, one writes the spec itself, one turns that spec into a technical plan, one breaks the plan into an ordered task list, one carries out the tasks and writes the actual code, and a final one checks how closely the result converged on the spec. The project's own guidance is to run these one at a time, reviewing each result before continuing, and to repeat the implement and converge steps until convergence reports the work as converged, rather than handing the whole job to the agent in one shot.
The toolkit also ships separate extensions you add on top of the core workflow, again per its own documentation: one set of commands built around assessing and fixing a specific bug, and another built around taking a rough idea through research and definition before deciding whether to build it at all.
On which agents it connects to, Spec Kit's own setup documentation names several by an integration key you pass at install time, including Claude Code and GitHub Copilot, and points to its own separate documentation for connecting further agents beyond the ones it names directly. Treat any specific agent list, including this one, as a snapshot: check Spec Kit's current documentation before assuming a given tool is or isn't supported today.
The Workflow, Command by Command
Spec Kit's Six Core Commands
Per the project's own README, the spec-driven workflow runs through these six steps in order, repeating the last two until the result converges.
Set the Constitution
A command that records project-wide principles the agent should respect for everything that follows, written once and reused across later work.
Write the Spec
A command that produces the actual spec document, the same plain-language brief covered above, now captured as a reusable file instead of a one-off message.
Plan the Approach
A command that turns the spec into a technical plan, choosing an approach before any code gets written, so a design decision isn't buried inside the implementation.
Break It Into Tasks
A command that splits the plan into a concrete, ordered list of tasks, each one small enough to check on its own.
Implement
A command that carries out the task list and writes the code, using everything from the earlier steps as its guide rather than starting from scratch.
Converge
A command that checks how closely the result matches the spec. Per the project's own guidance, you repeat implement and converge together until convergence reports the work as converged.
Without Installing Anything
Writing a Spec by Hand, No Toolkit Required
For a non-developer building one small thing, running the full Spec Kit workflow can be more ceremony than the task needs. The three-part spec by itself, typed as your very first message to whichever agent you already use, does most of the actual work on its own, with nothing to install.
Paste the spec, then let the agent ask you clarifying questions before it writes anything. A capable agent will ask when something's unclear, and a spec gives it something concrete to ask about instead of silently guessing and building the wrong thing confidently.
This plain version of the habit travels. The same three-part brief works whether you're talking to Claude Code, Codex, Copilot, Cursor, or any other coding agent, because none of it depends on a feature specific to one tool. It's a habit you're building, not a plugin you're installing.
Where This Goes Wrong
The Mistakes That Undo a Spec
Writing a spec helps less than it should when one of these creeps in.
No Done-When Checks
A spec without a way to verify completion just moves the guessing from the prompt to the review, where it's harder to catch.
Mixing in Implementation Detail
Specifying a programming language or a specific algorithm before deciding whether the feature is even wanted turns a spec into premature design.
Writing It After the Fact
A spec drafted to match code that already exists only documents what got built. It can't catch a problem it was written to agree with.
One Spec, Many Tasks
A spec that covers more than one real task buries the one that actually matters. Keep each spec to a single, checkable piece of work.
When to Reach for the Toolkit
Plain Spec or Full Spec Kit: Picking One
For a single small build, a plain three-part spec typed straight into the chat is enough, and it's faster than installing anything. Most of the examples in this guide are written for exactly that case.
Spec Kit starts earning its setup cost once you're repeating this on the same project, want its principles enforced automatically across every new feature, or want the bug-fixing or idea-assessment extensions' own structure instead of inventing your own version of them each time.
Either way, the actual skill is the same: state what it does, who it's for, and how you'll know it's done, before a single line of code gets written. The toolkit just automates writing that down consistently, once the habit is one you're reaching for often enough to be worth automating.
Practice Writing a Spec Before You Build
Writing a clear spec, and giving an AI coding agent standing project instructions, is a skill that transfers across every tool in this guide. Nightschool AI's free lesson on a project's instruction file walks through exactly that, using Claude Code as the example.
Frequently Asked Questions
What exactly is a spec, in this context?
A short, plain-language brief you write before asking a coding agent to build something. At minimum it covers what the thing should do, who it's for, and the done-when checks that prove it's finished. It's not a technical document and doesn't require knowing how to code.
Do I need to know how to code to write one?
No. A spec describes behavior and outcomes in plain language, not implementation. Describing what a tool should do and how you'll know it works doesn't require programming knowledge, even though the agent that builds it will write actual code.
What is GitHub's Spec Kit?
An open-source toolkit, MIT licensed, maintained in GitHub's own repository. It gives AI coding agents a structured, repeatable process built around spec-driven development, with its own command-line tool and a named sequence of six commands from a project's guiding principles through implementation and convergence.
Which coding agents does Spec Kit work with?
Per its own setup documentation, you connect an agent at install time with an integration key; the documentation names several agents this way, including Claude Code and GitHub Copilot, and links to its own docs for connecting others. Check Spec Kit's current documentation for the full, up-to-date list before assuming any specific tool is covered.
Is this guide affiliated with GitHub?
No. This is an independent educational guide, not published or endorsed by GitHub. Spec Kit and GitHub are GitHub's own project and trademark, named here only to describe them accurately.
What's the difference between a spec and just a longer prompt?
A longer prompt is still one message describing a task. A spec is a structured brief with three specific parts, what it does, who it's for, and done-when checks, meant to be read, confirmed, and reused, not just typed once and forgotten.
What are "done-when" checks, specifically?
Testable conditions that prove a build is finished: what you'll check, the expected result for each check, and what counts as a failure. Without them, there's no agreed way to tell whether the agent actually finished the task or just stopped.
Do I need to install Spec Kit to get the benefit of this habit?
No. Typing the same three-part spec as your first message to any coding agent, Claude Code, Codex, Copilot, Cursor, or another, gets you most of the benefit with nothing to install. Spec Kit is a repeatable structure for doing this often, not a requirement for doing it at all.
Is Spec Kit free to use?
Yes. It's an open-source project released under the MIT license, per its own repository, and installs through its own free command-line tool.
What does Spec Kit's spec-writing command actually produce?
Per the project's own documentation, it produces the spec document itself, the same plain-language brief described throughout this guide, saved as a reusable file in your project rather than typed fresh into a chat each time.
Turn a Spec Into Your First AI Agent
State what it does, who it's for, and how you'll know it's done, then build.