Spec-driven development is the practice of writing detailed specifications — requirements, architecture, API contracts, database schemas — before you write any code, then letting an AI agent build against them. The methodology is tool-agnostic, but it has a particularly good fit with Anthropic's Claude Code, the AI coding CLI.
That fit isn't an accident. Claude Code reads a CLAUDE.md file automatically at the start of every session, and it follows explicit instructions closely rather than improvising. Give it vague prompts and it guesses; give it precise specs and it executes them. Spec-driven development is simply the discipline of always giving it the latter.
Keeborg was built around this way of working — specs first, enforced rules, an agent held to a standard — before the industry settled on the name "spec-driven development." This guide walks through doing it with Claude Code specifically: the setup, the step-by-step workflow, and the point three features in where most teams watch the agent quietly wander off the spec.
In this guide
1. Why Claude Code and Spec-Driven Development Fit Together
Claude Code has two properties that make it a natural host for a spec-driven workflow:
Claude Code looks for a CLAUDE.md in your repo root — and a global one at ~/.claude/CLAUDE.md — and loads it before it does anything else. That gives you a guaranteed place to put standing rules the agent sees every single session, with no prompting.
Claude Code excels at doing exactly what it is told and struggles with implicit requirements. Explicit specs play directly to that strength: the more precisely you state the contract, the more reliably it builds to it. Ambiguity is where it has to guess — and guessing is where bugs come from.
Because it works against your actual working tree, Claude Code can open the PRD, the API spec, or the database schema on demand. Your specs do not live in a chat window it will forget — they live in the repo, right next to the code they govern.
The same documents that steer the agent also onboard the next human (or the next agent) on the project. There is no separate "docs" artefact to keep in sync — the spec is the source of truth for both.
The core insight: Claude Code is only as good as the context you hand it. A sharp spec turns a capable-but-literal agent into a reliable one. The whole workflow below is just a disciplined way of keeping that context accurate and in front of the agent at all times.
2. The Setup: CLAUDE.md Plus a Specs Directory
A spec-driven Claude Code project has two layers: a standing rules anchor the agent reads on every session, and a set of detailed specs it reads on demand. Keep them separate so the always-on file stays short and the heavy detail lives where it belongs.
CLAUDE.md — the standing rules anchor
Lives in your repo root. This is the file Claude Code reads automatically. Keep it tight: project conventions, architecture decisions, the commands to build and test, and a pointer to where the detailed specs live. A global ~/.claude/CLAUDE.md can hold rules that apply to every project you work on.
A specs/ or docs/ directory — the detail
Holds the documents Claude Code reads when it needs them: the PRD (requirements and user stories), the architecture document, the API specification, and the database schema. Version-controlled alongside your code, so when the spec changes, the change is in the same history as the implementation.
A typical layout looks like this:
One subtlety: Claude Code auto-reads CLAUDE.md, but it does not automatically ingest everything in specs/. Reference the spec files from CLAUDE.md ("read specs/architecture.md before changing service boundaries") or point the agent at them explicitly when you start a task. The rules anchor tells it where the detail is; the detail stays out of the always-loaded budget.
3. The Step-by-Step Workflow in Claude Code
With the setup in place, the day-to-day loop is simple. The key move is in the last step: you iterate on the specs, not on one-off prompts.
Describe your product
Start in plain English. Who is it for, what problem does it solve, what are the core features? You are not writing specs yet — you are capturing intent clearly enough to generate them.
Generate the spec stack
Turn that description into structured documents — PRD, architecture, API spec, database schema. You can write them by hand, but a generator like Keeborg produces the full stack in about 90 seconds so you spend your time refining rather than drafting.
Store the specs in the repo
Drop the documents into specs/ (or docs/) and commit them. Add a CLAUDE.md at the root with your conventions and a pointer to the spec files. Now the context is version-controlled next to the code.
Point Claude Code at the specs
Open Claude Code in the repo. It reads CLAUDE.md automatically; reference the relevant spec for the task at hand ("implement the auth endpoints from specs/api-spec.md"). It builds to the contract instead of guessing at it.
Iterate on the specs, not the prompts
When something needs to change, edit the spec and point the agent at the delta — not a throwaway chat message. The spec stays the single source of truth, the change is captured in git, and the next session starts from the corrected contract.
If you are also juggling Cursor or another agent alongside Claude Code, the same specs can feed every tool — see CLAUDE.md vs AGENTS.md vs .cursorrules for how to keep one source of truth across them.
4. Where It Breaks Down — and How to Hold the Line
The setup above gets you started. On a real project of any size, you hit a harder problem: getting Claude Code to keep following the spec once the session gets long. This is the part most teams discover the hard way.
Long sessions and context compaction
Claude Code works within a context window. When a session runs long, it compacts earlier turns into summaries to make room — and the fine detail of your spec is exactly what gets summarised away. The agent that read your API spec carefully at the start is, an hour later, working from a lossy memory of it.
Drift, three features in
By the third or fourth feature, the pressure is to just ship. The agent starts making the same assumptions the spec existed to prevent — a slightly different error shape here, an auth check skipped there. A spec the agent read once and then drifted from is worse than no spec, because it gives you false confidence that the contract is being honoured.
Free, unopinionated frameworks — GitHub's Spec Kit, AWS Kiro, and others — give you a structure for writing specs, and they're genuinely useful if you want to assemble your own workflow. But they're deliberately a blank scaffold: they hand you the format and leave the enforcement to you. That enforcement layer is exactly what keeps Claude Code on the spec, and it's the gap the Keeborg dev system fills:
Three files record decisions, changes, and where the work left off. When context compaction hits — or you start a fresh session — Claude Code re-reads them and resumes exactly where it was, still inside the spec, instead of from a faded summary.
Every piece of work is scored against a rubric. Below 95/100 means it is not done — the agent re-runs rather than handing you half-built code that merely compiles. The spec defines "correct"; the gate refuses to call anything less than that finished.
Specs describe the happy path. The audit checks what specs usually forget — exposed keys, missing auth, unsafe defaults — before anything ships. It is a gate the agent cannot wave through on its way to "done".
Documentation before code. No phase skipped without a written reason. Secrets never in the client bundle. These are not suggestions buried in a README — they are rules Claude Code operates under, baked into the CLAUDE.md and skills it reads every session.
The free generators get you spec-driven with Claude Code. The dev system is what keeps you there across a long build. If you've tried spec-first before and watched the agent wander off halfway through, the enforcement layer is the piece you were missing.
5. Getting Started: A Checklist
You don't need the full system on day one. Here's a practical path from a blank repo to a spec-driven Claude Code workflow:
1. Add a CLAUDE.md to your repo root
Start with your conventions, the build and test commands, and a one-line pointer to where specs live. Keep it short — this file is loaded every session, so it should be the map, not the territory.
2. Write (or generate) the spec for your next feature
Don't spec the whole product at once. Pick the next feature, write a PRD and the API or schema changes it needs, and drop them in specs/. Generating the first draft is faster than starting from a blank page.
3. Point Claude Code at the spec and build
Open Claude Code in the repo and reference the spec explicitly for the task. Compare the output to your usual prompt-driven approach — the jump in first-attempt accuracy is the whole argument for the method.
4. When something changes, change the spec
Resist the urge to fix things with a one-off prompt. Edit the spec, commit it, and point the agent at the delta. The spec stays the source of truth and every future session starts from the correct contract.
5. Add enforcement before the project gets big
Once you're past a feature or two, add continuity files, a quality gate, and a pre-deploy security audit — the layer that stops the agent drifting on long sessions. This is where the Keeborg dev system drops in.
Start free: generate the specs
Turn a plain-English description into a complete specification stack — PRD, architecture, API spec, database schema, and more — ready to drop into your repo for Claude Code to build against.
Try the free generatorGo further: keep Claude Code on-spec
The Keeborg dev system adds the enforcement layer — continuity that survives context compaction, a 95/100 quality gate, and a security audit that blocks deploy — personalised to your stack. One-time, yours forever.
Get the dev system