GitHub Spec Kit Tutorial: Spec-Driven Development in an Existing Project

Most GitHub Spec Kit tutorials start from an empty folder. That is the easy case, and it is not the one you have. You have a codebase. It has conventions nobody wrote down, a half-finished refactor, and a feature you shipped last month that the next feature has to respect. The empty-folder demo never shows you what happens when Spec Kit meets all of that.

That gap is the whole reason this tutorial exists. Spec Kit is a genuinely good toolkit, and the idea underneath it is correct: write a structured spec before you let an agent write code. GitHub open-sourced it in September 2025 and it crossed 100,000 stars faster than almost any developer tool in recent memory. But the README's quickstart assumes a greenfield project, and the real builders trying to adopt it are not greenfield. One developer on r/SpecDrivenDevelopment recently laid out, earnestly, the difference between SuperPowers, OpenSpec, and Spec Kit and ended with a line that has become the unofficial motto of this whole space:

"I think we are all still figuring these things out. Sometimes it's best to just dive in and give it a try."

So let's dive in, on a project that already exists. Here is the hypothesis we are going to test: Spec Kit makes spec-driven development concrete and approachable, and the moment you run it on a real codebase, you find the exact line where a per-run toolkit ends and a durable system has to begin.

#What GitHub Spec Kit Actually Is

Spec Kit is a command-line tool, written in Python, that installs a spec-driven workflow into your project. You run it through an agent you already use. It works with Claude Code, Cursor, GitHub Copilot, Codex, Gemini CLI, and roughly 30 other agents, because it does not replace your agent. It gives your agent a sequence of slash commands and a set of templates that turn "build me a thing" into a reviewable plan.

The whole method is six commands, run in order:

1/speckit.constitution   # the project's non-negotiable rules
2/speckit.specify        # what you're building, in plain English
3/speckit.clarify        # the agent asks questions to kill ambiguity
4/speckit.plan           # the stack and architecture
5/speckit.tasks          # a dependency-ordered task list
6/speckit.implement      # the agent finally writes code

That ordering is the entire point. As Den Delimarsky, who maintains the project, frames it, Spec Kit is about making the intent explicit before the implementation exists. Akshay Pachaar put the cultural read on it more bluntly when the repo took off:

"The core idea: write a structured spec before you prompt your AI coding agent."

Notice what is missing from a normal AI coding session: the questions. In a vibe-coding loop you prompt, eyeball the output, and prompt again. Spec Kit inserts /speckit.clarify specifically to make the agent ask you what it does not know before it guesses. That single step is the difference between an agent that builds what you meant and one that builds what it assumed.

#Installing Spec Kit in a Repo That Already Has Code

Here is where the existing-project case diverges from every quickstart. Install the CLI the same way:

1uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

Then, from inside your existing repository, initialize Spec Kit in place rather than scaffolding a new directory:

1specify init --here --integration claude

The --here flag is the one the greenfield tutorials skip. It tells Spec Kit to lay its .specify/ directory, templates, and agent command files alongside your code instead of in a fresh folder. Swap --integration claude for cursor, copilot, gemini, or whichever agent you run. Your code is untouched. What you have added is a workflow, not a rewrite.

This is also the first moment the existing-project case gets interesting, because Spec Kit now knows nothing about the code it is sitting next to. The constitution is where you fix that.

#Writing a Constitution for Code That Already Exists

The constitution is Spec Kit's most underrated command and the one that matters most in a brownfield project. In a new project, the constitution is aspirational: here is how we intend to build. In an existing project, the constitution is archaeological: here is how this codebase already works, and the agent must respect it.

Run /speckit.constitution and describe the rules your code already lives by. A weak constitution reads like a wish list. A strong one reads like a description of reality.

Vague: "Write clean, well-tested code with good architecture."

Concrete: "API routes live in src/app/api and return typed responses via the ApiResponse helper. Database access goes through the repository classes in src/db/repositories, never raw queries in route handlers. All new tables use snake_case columns and include created_at and updated_at. Tests use Vitest and live next to the file they cover. Auth is checked with requireSession() at the top of every protected route."

The second one is what stops your agent from inventing a parallel pattern next to the one you already have. The number one failure mode of AI on an existing codebase is not bad code. It is plausible code that ignores your conventions: a second auth helper, a fourth way to fetch data, a state pattern that fights the three already there. The constitution is the document that prevents it, and spec kit constitution example is one of the most-searched queries about the tool for exactly this reason. People feel the gap.

#The Specify-to-Implement Loop on a Real Feature

Now the working part. Say your existing app has user accounts and you want to add team invitations. You do not describe the whole app. You describe the one feature, and you let Spec Kit's structure carry it from sentence to code.

1/speckit.specify Add team invitations. An account owner can invite a teammate by email.
2The invite expires after 7 days. The teammate accepts via a link and joins with a "member"
3role. Owners can see pending invites and revoke them.

Then /speckit.clarify, where the agent surfaces the questions a vague prompt would have buried: what happens if the email already has an account, can a member invite other members, what is the role hierarchy. You answer those once, in writing, and they become part of the spec instead of a surprise in the diff.

/speckit.plan is where you tell it the stack, and on an existing project this is where the constitution earns its keep: the plan should reuse your repository classes, your auth helper, your table conventions, not invent new ones. /speckit.tasks breaks it into a dependency-ordered list. /speckit.implement builds it, task by task.

Here is the before-and-after that makes the case. Without Spec Kit, "add team invitations" to an existing app is a single prompt and a roll of the dice, and the agent's first guess about your role model is probably wrong. With Spec Kit, the same feature arrives as a spec you reviewed, a plan that respects your conventions, and a task list you can check off. The work is the same size. The number of times you regenerate it from scratch is not.

Loading diagram...

#Where Spec Kit Stops

Now the honest part, because a tutorial that only sells the tool is not a tutorial. Run Spec Kit on a real project for a week and you find its edges.

The first edge is that it is per-run. Spec Kit is brilliant inside a single feature. It is quiet about the relationship between features. Your team-invitations spec does not know your billing spec exists, and next month when you build seat-based billing, nothing connects the two. The specs are files in a folder. They do not accumulate into a model of your product unless you build that yourself. Builders feel this immediately: one r/GithubCopilot thread is titled, plainly, "Spec-driven development with Spec-Kit is eating my tokens alive," because re-establishing context every run is expensive when the context does not persist.

The second edge is verification. Spec Kit gets you a spec, a plan, and tasks. What it does not give you is proof that the implementation actually did what the spec said. /speckit.implement ends when the code is written, not when the acceptance criteria are demonstrated. That last step, the one where someone confirms the invite really does expire after 7 days and a revoked invite really is dead, is left to you. On a one-person demo that is fine. On anything you ship, that gap is where the trouble lives.

The third edge is reach. Spec Kit lives in the terminal, behind a CLI, run through a coding agent. That is perfect for the engineer on your team. It is a closed door for the non-technical co-founder who actually knows what "done" means for the invitations feature, and who will never run uv tool install to weigh in.

None of these are bugs. They are the natural boundary of a per-run toolkit. Spec Kit is a method made concrete, and a method has to stop somewhere.

#What Has to Begin Where Spec Kit Ends

The boundary Spec Kit hits is the same one every spec-driven workflow hits eventually: a spec is only as valuable as the system that keeps it, connects it, and checks it. This is exactly the seam BrainGrid is built for, and it picks up where the per-run toolkit leaves off.

BrainGrid runs the same shape of loop, Plan to Build to Verify to Repeat, but the spec is not a file you regenerate each run. You describe the feature, and the Planning Agent turns it into a requirement with acceptance criteria, in the web app, where your non-technical co-founder can read and edit it too. That requirement persists. When you build the next feature, the previous ones are still there as context, so your billing work knows your invitations work happened. Then the Builder Agent builds it, either in a BrainGrid-managed sandbox with a live preview, or self-managed in your own GitHub repo through MCP, driving Claude Code, Cursor, or Codex against the plan. And the part Spec Kit hands back to you, verification, is the part BrainGrid treats as the definition of done: a feature is not finished until every acceptance criterion is checked with evidence.

So the honest framing is not Spec Kit versus BrainGrid. It is Spec Kit teaching you the discipline, and BrainGrid being the place that discipline lives once one feature becomes fifty. If you want the full structural comparison, we wrote it up at BrainGrid vs Spec Kit.

#What This Means If You're Adopting Spec Kit Right Now

If you are a solo builder or a small team adding Spec Kit to an existing codebase this week, here is the concrete read. Start with the constitution, and spend real time on it, because on a brownfield project the constitution is the single thing standing between you and an agent that quietly forks your conventions. Use /speckit.clarify every time and answer the questions in writing, because that is where the spec actually gets its value. And go in knowing the two things Spec Kit will hand back to you: the connective tissue between features, and the proof that each feature met its criteria. Those are the two jobs you own.

The deeper point survives even if you never touch Spec Kit. Spec-driven development is not really about a CLI. It is about deciding, in writing, what "done" means before an agent guesses. As Boris Cherny, who reports writing nearly all of his Claude Code contributions with Claude Code, put it, his job now is to write loops that can verify themselves. Spec Kit is one good way to start writing those loops. The question that decides everything after that is whether your specs are a pile of files or a system that remembers.

#FAQ

#How do I use GitHub Spec Kit in an existing project?

Install the CLI with uv tool install specify-cli --from git+https://github.com/github/spec-kit.git, then run specify init --here --integration claude from inside your repository. The --here flag installs Spec Kit alongside your existing code instead of scaffolding a new folder. Then run /speckit.constitution first and describe the conventions your codebase already follows, so the agent respects your existing patterns instead of inventing new ones.

#What are the GitHub Spec Kit commands?

There are six, run in order: /speckit.constitution sets the project's non-negotiable rules, /speckit.specify describes what you're building in plain English, /speckit.clarify makes the agent ask questions to remove ambiguity, /speckit.plan defines the stack and architecture, /speckit.tasks generates a dependency-ordered task list, and /speckit.implement writes the code last.

#What is a Spec Kit constitution?

The constitution is the file that holds your project's durable rules, the standards every spec and plan must respect. In a new project it describes how you intend to build. In an existing project it should describe how the codebase already works: where files live, which helpers to reuse, naming conventions, how auth and data access are handled. A concrete constitution is what stops an agent from forking your existing patterns.

#Does GitHub Spec Kit work with Claude Code and Cursor?

Yes. Spec Kit is agent-agnostic and works with Claude Code, Cursor, GitHub Copilot, Codex, Gemini CLI, and roughly 30 other agents. You choose the agent at init time with the --integration flag, and Spec Kit installs the matching slash commands. It augments your agent rather than replacing it.

#Is GitHub Spec Kit free?

Yes. Spec Kit is an open-source toolkit released by GitHub, free to install and use. Your only costs are the usual ones: the model usage your coding agent consumes when it runs the spec, plan, and implement steps.

#What is the difference between Spec Kit and BrainGrid?

Spec Kit is a per-run, CLI-based toolkit that produces a spec, plan, and tasks for one feature at a time inside your terminal. BrainGrid is a system where specs persist and connect across features, accessible in a web app so non-technical teammates can write and review them, with verification against acceptance criteria built into the definition of done. Spec Kit teaches the discipline; BrainGrid is where that discipline lives as a project grows.

BrainGrid is the system that takes an idea to a live product you can trust, with specs that persist and verification built into done. Try it at braingrid.ai.