Spec-Driven Development With Claude Code: Verify the Spec

Use spec-driven development with Claude Code to review requirements, run eight acceptance cases, and catch changed tests before approving the implementation.

Three stages connect a reviewed spec and its decisions to an implementation plan and eight acceptance checks, with the final verification stage highlighted.

Spec-driven development with Claude Code means agreeing on observable behavior before asking Claude to implement it, then checking the implementation against that agreement. Write the requirement, review the ambiguous cases, derive acceptance checks, and keep the reviewed version available through the pull request. A plan describes how to build the change; the spec defines what would make the change correct.

The difficult part is preserving that distinction once the agent can edit the implementation, the tests, and the document together. A green test run can reflect a repaired feature. It can also reflect a weakened definition of success.

We built an eight-case Python exercise to make that difference inspectable. The correct implementation passes every case. Two plausible mistakes fail specific acceptance checks. Removing two checks makes one incorrect implementation appear to pass, while changing the reviewed contract's file hash. This is a synthetic, deterministic example, executed on Python 3.14.4; it is not a Claude model benchmark or a test of SyncStaff's authorization implementation.

What belongs in a spec for Claude Code?

A useful spec states the behavior that changes, the cases that must remain unchanged, the interfaces involved, and the evidence a reviewer will require. Keep product decisions separate from implementation suggestions. If two reasonable developers could disagree about an outcome, resolve that disagreement before treating the document as ready for implementation.

For a small feature, a single versioned Markdown file is enough. Include:

  • The reader or user who needs the change and the problem it solves.
  • Observable inputs, outputs, and failure behavior.
  • Boundary cases, including empty input and exact limits.
  • Explicit non-goals that prevent unrelated work expanding the patch.
  • Acceptance criteria with stable identifiers.
  • Open questions, a named decision owner, and the reviewed revision.

Avoid padding the spec with the entire repository architecture. Point to existing conventions instead. A short requirement that makes an expiry boundary unambiguous is more useful than several pages of general instructions to write secure, maintainable code.

Use CLAUDE.md for durable project instructions, such as where specifications live and which test command to run. Keep feature-specific requirements in the feature's own document. That separation makes it easier to retire an old feature spec without losing rules that still apply to the project.

Separate the spec, plan, tasks, and acceptance evidence

These artifacts answer different questions. Combining them into one unstructured conversation makes it hard to tell whether a proposed implementation change also changes the product requirement.

Artifact Question it answers Example for this exercise
Spec What behavior did we agree to? An owner may act only before the reservation expires.
Plan How will we implement it? Add a pure predicate, then connect it to the caller.
Tasks What reviewable units will be changed? Add checks, implement the predicate, inspect the integration.
Acceptance evidence What did we actually observe? AC3 rejects the exact expiry boundary.
Review record Which revision and exceptions did a person accept? Contract version 1, its file hash, and any unresolved limitation.

Claude Code plan mode helps separate exploration and planning from implementation. It does not make the requirements correct. Ask Claude to identify unanswered questions before asking for a plan, and review the answers yourself.

GitHub Spec Kit provides a more structured specification workflow if you want templates and linked artifacts. It is optional for this example. We did not run a Spec Kit installation or compare its performance with a plain Markdown workflow, so no setup or speed claim follows from our test.

Review the spec before reviewing generated code

Start with a narrow prompt that requests questions rather than implementation. This illustrative prompt is a workflow suggestion, not a measured model result:

Read specs/reservation.md. Do not implement it yet.
List ambiguous inputs, boundary cases, and conflicting requirements.
For each acceptance criterion, propose an observable check.
Keep unresolved decisions visible; do not choose a product policy silently.

For our exercise, the first important question is what “expires at 10” means. Does an action at time 10 still count? The reviewed answer is no: expiry is an exclusive upper boundary. The second question is whether two empty owner fields count as a match. They do not: a valid owner must be nonempty.

Those decisions are small enough to overlook in prose, yet they produce different code. A review should also ask which clock supplies the timestamp, whether negative values are valid, and what happens when ownership changes. Our deliberately small fixture accepts supplied integer timestamps and checks a single snapshot. It does not model clock skew, distributed ownership changes, or a real reservation service.

That scope statement matters. A demonstration can verify its own contract without proving the surrounding production system safe.

An eight-case acceptance contract you can run

Create an empty exercise directory. Save the following as acceptance.json. These are the exact eight cases used in our run; whitespace may differ from our stored file, which changes its byte-level hash without changing its meaning.

{
  "version": 1,
  "requirements": [
    "Nonempty owner must match actor.",
    "Expiry is exclusive: allow only when now < expires.",
    "No network or product server is called."
  ],
  "cases": [
    {"id":"AC1","owner":"alice","actor":"alice","now":9,"expires":10,"allow":true},
    {"id":"AC2","owner":"alice","actor":"bob","now":9,"expires":10,"allow":false},
    {"id":"AC3","owner":"alice","actor":"alice","now":10,"expires":10,"allow":false},
    {"id":"AC4","owner":"alice","actor":"alice","now":11,"expires":10,"allow":false},
    {"id":"AC5","owner":null,"actor":"alice","now":9,"expires":10,"allow":false},
    {"id":"AC6","owner":"","actor":"","now":9,"expires":10,"allow":false},
    {"id":"AC7","owner":"alice","actor":"alice","now":0,"expires":0,"allow":false},
    {"id":"AC8","owner":"alice","actor":"alice","now":0,"expires":1,"allow":true}
  ]
}

Save this as check_contract.py. It includes the correct predicate and two intentionally incorrect alternatives, so you can see which cases distinguish them.

import hashlib,json,sys
from pathlib import Path

def digest(path):
    return hashlib.sha256(Path(path).read_bytes()).hexdigest()

def check(fn, contract):
    return [c["id"] for c in contract["cases"]
            if fn(c["owner"], c["actor"], c["now"], c["expires"]) != c["allow"]]

def correct(owner, actor, now, expires):
    return bool(owner) and owner == actor and now < expires

def inclusive_expiry(owner, actor, now, expires):
    return bool(owner) and owner == actor and now <= expires

def empty_owner(owner, actor, now, expires):
    return owner == actor and now < expires

if __name__ == "__main__":
    contract = json.loads(Path("acceptance.json").read_text())
    for fn in (correct, inclusive_expiry, empty_owner):
        print(fn.__name__, check(fn, contract))

Run it from the directory containing both files:

python3 check_contract.py

Our executed result was:

correct []
inclusive_expiry ['AC3', 'AC7']
empty_owner ['AC6']

An empty list means no failed acceptance cases. The inclusive comparison accepts actions at the exact expiry time, failing AC3 and AC7. The missing nonempty-owner check accepts two empty strings, failing AC6. These are ordinary implementation mistakes made visible by an explicit contract; we are not claiming Claude produced them.

The checker prints results for comparison. It is not a complete CI gate and deliberately does not exit unsuccessfully for the included incorrect examples. In a real test suite, select the implementation under review and assert that its failure list is empty. Keep the deliberately wrong functions as negative controls in the exercise, rather than shipping them as production alternatives.

Show how a green test run can conceal spec drift

Now consider a patch that changes the predicate to use an inclusive expiry comparison and also removes AC3 and AC7. The remaining six cases pass for that incorrect predicate. We executed this negative control separately, keeping the original eight-case file unchanged.

The problem is not that six passing checks are worthless. They still verify six inputs. The problem is that the acceptance set no longer tests the reviewed expiry decision. Without the earlier artifact, a reviewer might read the new code and the new tests as a consistent implementation of the original request.

Record the reviewed contract's hash before implementation:

python3 -c "from check_contract import digest; print(digest('acceptance.json'))"

Store that value with the review record, outside the implementation branch's unilateral control. Recompute it when reviewing the patch. A different value is a reason to inspect the contract diff, not automatic proof of wrongdoing: formatting changes and legitimate amendments also change the hash.

In our run, removing the two expiry checks changed the file hash. The original artifact remained byte-for-byte unchanged. A hash alone neither authorizes the original requirement nor prevents someone from changing both the file and an unprotected recorded hash. Its value is connecting the review to a specific artifact when the comparison record is independently controlled.

Handle a legitimate requirement change explicitly

Sometimes the inclusive boundary is the desired policy. The right response is an amendment, not hiding the policy change inside a test update.

Write down the changed behavior, its reason, and its affected criteria. Ask the decision owner to approve it. Update the contract version and the acceptance cases together, then retain the previous version in Git history. Reviewers should be able to distinguish “the implementation failed version 1” from “version 2 intentionally changed the boundary.”

For larger interfaces, add concrete compatibility evidence. A change to a response shape may require consumer tests; a migration may require a rollback example. A spec cannot settle those questions merely by declaring them complete. Connect each claim to the command, fixture, or observation that supports it.

Keep unresolved decisions visible in the task rather than inventing defaults. Our human-in-the-loop guide explains where a person's decision belongs in agent work. The human should decide the behavior; the agent can gather the evidence needed to make that decision.

Give a fresh reviewer a bounded job

Our Claude Code subagent guide covers the mechanics of review roles. A fresh review context can help expose assumptions carried through a long implementation session. Give the reviewer the reviewed spec revision, the implementation diff, the acceptance results, and the open decisions. Ask it to map each criterion to evidence and identify missing checks. For hosted and local review paths, trigger choices, and the boundary between findings, CI, and human approval, use our Claude Code Review guide.

Anthropic's subagent documentation describes separate contexts and configurable tool access. Those are useful workflow primitives, not an assurance that a second model will detect every error. Our exercise does not measure reviewer accuracy or compare model families.

For this example, a useful review request is narrower than “is the code good?” Ask whether AC3 and AC7 still exist, whether the predicate matches the exclusive boundary, and whether any requirement changed after approval. Have the reviewer quote the relevant criterion identifiers and actual results.

Do not give a review role permission to rewrite its own acceptance evidence merely to make the run pass. Where the repository allows changes, distinguish a proposed amendment from an accepted one. Access restrictions, protected review artifacts, and human approval are separate controls; a prompt does not implement all three.

When the requirement changes after the first implementation, use the AI agent testing lab to compare baseline and changed requirements with their corresponding graders. Its scripted controls show how an outdated grader can accept an outdated result.

Coordinate parallel implementation around the reviewed contract

When several agents work on one feature, the spec is shared input but the planned edits may overlap. One agent can implement the predicate while another prepares an integration check, provided their scopes and dependencies are visible. Two agents silently rewriting the same contract can erase the distinction between implementation work and a product decision.

SyncStaff supplies a shared board, declared intents, file leases, conflict arbitration, and human decisions for connected coding agents. Use those records to state which reviewed contract a task follows, what files an agent intends to change, and which disagreement needs a person. Keep the actual test artifacts and source revision in the repository or the team's chosen evidence store.

File leases do not prove the spec correct, replace code review, or universally prevent shell edits. The benefit here is a shared view of responsibility and overlapping work while your tests and repository controls do their own jobs.

Before starting the next feature, take one ambiguous boundary from its spec and make it an executable acceptance case. Record the reviewed revision, run the check against the implementation, and inspect any change to the acceptance artifact as carefully as the code change. That gives the team a concrete agreement to coordinate around.

Frequently asked questions

What is spec-driven development with Claude Code?

It is a workflow where reviewed requirements define observable behavior before Claude implements a change. The specification guides planning, tasks, and acceptance checks. Keep the reviewed revision available during implementation, and inspect changes to the requirements separately from changes intended to satisfy them.

Is Claude Code plan mode the same as a specification?

No. A specification defines the behavior and acceptance criteria; a plan describes the implementation approach. Plan mode helps separate exploration and planning from implementation, but it does not settle ambiguous product decisions or prove that the resulting code satisfies the reviewed requirements.

Do I need Spec Kit to use this workflow?

No. A versioned Markdown specification and explicit acceptance checks can support a small feature. Spec Kit offers a more structured workflow and linked artifacts. This article uses a standalone Python exercise and does not claim to benchmark Spec Kit or verify its installation process.

Why keep the reviewed acceptance contract separate?

An implementation can appear correct if its author also removes the checks that expose its mistakes. Retaining the reviewed contract lets a reviewer compare the patch against the earlier agreement. A protected review record matters; a hash stored beside an editable file is not sufficient authorization.

What should happen when the specification legitimately changes?

Record the changed behavior, its reason, and the affected acceptance criteria. Have the decision owner approve the amendment, then version the specification and checks together. Preserve the previous revision so reviewers can distinguish an implementation error from an intentional change in what the feature should do.