The Claude Code Spec Workflow: Spec-Driven Development for AI Agents

The 80% stall is real, and it isn't the model's fault

If you have used Claude Code, Cursor's agent mode, or any other agentic coding tool on a real project, you already know the shape of the problem. The first hour is remarkable. You describe an app, the agent scaffolds routes, wires a database, writes components, and something genuinely usable appears on screen. Then progress flattens.

The build sits at "mostly working." Auth is there but roles are fuzzy. The list view renders but silently truncates at 1,000 rows. Deleting a record leaves orphaned rows behind. Every new session, the agent re-derives decisions you thought were settled, and half of them come out differently than last time.

That is the 80% stall. It is not a reasoning failure. The model can absolutely implement row-level permissions or a pagination loop — it does so correctly when asked. The failure is that nothing in the repository tells it those rules exist. The agent is reconstructing your product from whatever fragments fit in its context window today.

Why agents lose the plot

Three properties of agentic coding create the stall:

• Context is per-session and lossy. Whatever you explained in chat last Tuesday is gone. The agent sees code, not the intent behind it.
• Code under-specifies intent. A table with a status column does not say which transitions are legal, who may make them, or what happens to dependent records.
• Ambiguity is resolved silently. When a requirement is missing, the agent does not stop and ask. It picks something plausible and keeps going — and plausible-but-wrong is the most expensive kind of output, because it looks finished.

Every one of those is fixed by the same thing: a durable, structured specification that lives in the repo and is read before each change.

What "spec-driven development" actually means

Spec-driven development is not a return to hundred-page requirements documents. The spec is a working artifact, versioned alongside the code, that captures the decisions an agent cannot infer. In practice it answers five questions:

The last row matters more than people expect. An agent without acceptance criteria has no definition of done, so it either stops early or keeps refactoring. Written criteria convert an open-ended task into a closed one.

The workflow, step by step

1. Write the spec before the first prompt

Start with entities and rules, not screens. Ten minutes describing that a workspace has many projects, that only an owner may invite members, and that seats are capped will save hours of rework. Keep it in the repository — PROJECT_SPEC.md at the root works fine — so it travels with the code.

2. Make reading the spec a standing instruction

Agents follow persistent instructions far better than one-off chat messages. In a CLAUDE.md, an agent rules file, or your tool's project instructions, state the invariants directly:

1. Read PROJECT_SPEC.md before every change. It is the source of truth
   for business rules and module behavior.
2. No silent data truncation: paginate any query that can exceed 1,000 rows.
3. No demo or mock data in production screens.
4. If a change would violate a rule, stop and ask before proceeding.

Rules phrased as prohibitions ("no mock data in production screens") outperform aspirations ("write good code") because they are checkable.

3. Scope each session to one slice

Hand the agent one vertical slice at a time — one entity, its rules, its screens, its tests. Long multi-feature sessions are where context is lost and earlier decisions get quietly overwritten. Slices also give you a clean review boundary.

4. Close the loop after every change

Require the agent to update the spec with what changed and why, then bump a version number. This is the step most teams skip, and it is the step that compounds. A spec that is updated after each change stays true; a spec that is written once becomes fiction within a week, and a fictional spec is worse than none because the agent trusts it.

5. Review the spec, not just the diff

A human can read a spec change in two minutes and catch a wrong rule. Catching the same wrong rule in a 900-line diff takes an hour and usually does not happen. Reviewing at the spec layer is the cheapest quality control available on an AI-assisted project.

A worked example: teammate invitations

Here is the difference in practice. The vague version:

An agent will build an invite form, a table, and an email. It will probably not scope invitations to a workspace, cap seats, expire tokens, or handle an invited address that already has an account.

The specified version:

The second version is not longer for its own sake — every sentence removes a decision the agent would otherwise invent. That is the whole discipline.

Signals that your spec is doing its job

• New sessions pick up where the last one left off instead of relitigating decisions.
• The agent asks a question instead of guessing when a rule is missing.
• Edge cases show up in the first implementation, not in a bug report.
• Reviews get faster, because the diff matches something you already approved.

If none of those are true, the spec is probably describing screens rather than rules. Rewrite it around entities, permissions, and states.

Where SpecLoop fits

Everything above can be done by hand in a markdown file, and for a small project you should. The reason we built the SpecLoop Spec Engine is that the discipline breaks down at scale: specs go stale, rules live in three places, and nobody knows which version the agent read.

SpecLoop produces the deep specification — entities, permissions, states, edge cases, and acceptance criteria — in a structured form, keeps it versioned as the build progresses, and exposes it to agents over MCP so the tool reads the current spec rather than a copy someone pasted last month. The workflow is identical to the one described here. The engine just stops it from decaying.

The short version

Agentic coding tools are not stalling at 80% because they cannot write the last 20%. They stall because nobody has told them what the last 20% is. Write the rules down, keep them in the repo, make reading and updating them mandatory, and review at the spec layer. That single change is the difference between an impressive prototype and a build you can put in front of customers.