TL;DR: Spec-driven development with Claude Code works when the spec produces tests before it produces code. Write observable acceptance criteria, turn them into reviewed tests in ContextQA, have Claude Code build the feature against them, then run those tests on the deployed build and send any failure back to the agent. The spec stays the source of truth, not whatever the agent happened to build. Only 3% of developers say they highly trust AI output (Stack Overflow Developer Survey, 2025), so the proof has to come from somewhere else.
Coding agents are good at building features from a description. They are less good at telling you whether the feature does what the business asked for. Claude Code will often say "done" while an edge case, an error message or a second screen is wrong. This guide shows a repeatable loop that goes from spec to verified feature: acceptance criteria first, tests second, code third, evidence last.
Quick answers
What is spec-driven development with Claude Code? You write a specification with clear acceptance criteria before any code, and Claude Code implements against it. The spec, not the agent's summary, decides when the work is done. Tools like GitHub's Spec Kit structure the spec, plan and tasks. ContextQA adds the missing piece: tests generated from the spec that run against the real build.
How do I verify acceptance criteria automatically? Upload the spec or connect the Jira ticket to ContextQA, answer its clarifying questions, and approve the generated test cases. Each case maps back to a requirement. After Claude Code builds the feature, run those cases on the deployed build and read the step-by-step result (requirements tutorial).
Why not let Claude Code write the tests too? It should write unit and integration tests in your repository. But if the same agent writes the code and the only acceptance tests, a misunderstanding of the spec ends up in both. Tests generated from the spec, reviewed by a person and run independently, catch that.
Why do features built by agents fail acceptance?
Usually because the spec was vague and the agent filled the gaps. "Passwords must be strong" becomes whatever rule the agent picked. "Show an error if the email is taken" becomes an error somewhere on the page with any wording. Each guess looks reasonable, and the code is internally consistent, so code review doesn't flag it.
Claude Code's own guidance points at the fix: give the agent a check it can run and review its work against your spec, not against its summary (Claude Code best practices). The check needs to exist before the code does. If you write the expected results after seeing the implementation, they describe the implementation. If you're seeing this already, our guide on what to do when Claude Code says done but the feature doesn't work covers the debugging side.
What does a testable spec look like?
Every acceptance criterion should describe something a user or a system can observe. Here's the registration example from the ContextQA docs, which works well as a starting point:
- The form collects first name, last name, email address and password.
- Email addresses must be unique across all accounts.
- Passwords need at least 8 characters, one uppercase letter, one lowercase letter and one number.
- On successful registration, the user lands on the dashboard.
- If the email is already in use, an inline error appears next to the email field.
- If the password breaks the rules, an inline error appears next to the password field.
Notice what each line has: a condition and an observable result. Notice also what's missing and has to be decided by a person: the exact error wording, the starting URL and what happens to a half-filled form. Write those down before the agent starts.
| Spec style | Example | Testable? |
|---|---|---|
| Vague goal | "Registration should be secure" | No. Nothing to observe |
| Rule without a result | "Emails must be unique" | Partly. What does the user see? |
| Condition plus observable result | "If the email is in use, an inline error appears next to the email field" | Yes |
| Condition, result and wording | Same, with the exact error text agreed | Yes, and stable across agent attempts |
How do you go from spec to verified feature, step by step?
This loop uses Claude Code for the build and ContextQA for the tests and the evidence.
- Write the release question. One sentence with the user outcome and at least one failure case. For example: a new user can register and reach the dashboard, and a duplicate email shows an inline error without creating an account.
- Generate tests from the spec. In ContextQA, open Test Cases, choose Import File and then Import Requirements. Set the target platform, choose Require Approval and upload the spec. You can also generate from a Jira user story.
- Answer the clarifying questions. ContextQA asks about gaps, such as the exact error wording or the starting URL. Specific answers produce precise tests. If nobody knows the answer, take it to the product owner instead of letting a test invent policy.
- Review and approve the cases. Each generated case is typed (positive, negative, edge, field validation, boundary or end to end) and linked to its requirement. Approve what's right, reject what isn't, and check the Gaps tab for requirements with no test yet (coverage gaps guide).
- Hand Claude Code the spec and the test list. Ask it to plan first, then implement on a new branch and add unit and integration tests in your repository's own runner. Tell it the acceptance cases exist and must pass on the deployed build.
- Deploy a preview build. ContextQA's runners need a URL they can reach. A preview deployment per pull request is the cleanest option.
- Run the approved cases. Through the ContextQA MCP server, Claude Code can execute the cases, poll their status and read the step results. Or run them from ContextQA and share the report.
- Loop on failures. Send the failed step, its screenshot and the expected result back to Claude Code. Each fix is a new commit, so run the cases again on the new build.
- Merge with evidence. Attach the run links and the tested commit to the pull request. A person approves the merge.

Building features with Claude Code every day? Ship by ContextQA tests each pull request against the journeys it affects: start free, no credit card needed.
How do you prompt Claude Code for this loop?
Keep the prompt short and put the contract in it. Something like:
- Read the spec in the linked ticket and the approved ContextQA test cases for it.
- Write a plan and wait for approval before editing files.
- Implement on a new branch. Add unit tests for the validation rules and an integration test for account creation.
- Don't change the acceptance cases. If one looks wrong, say why and stop.
- After the preview deploys, run the approved cases with ContextQA and report each result with its run link.
- Return the pull request, the tested commit and anything unresolved.
The line about not changing the acceptance cases is the important one. Agents under pressure to finish will sometimes "fix" a test instead of the code. If a case really is wrong, a person should change it, because the spec changed.
To connect Claude Code, run claude mcp add --transport http contextqa https://mcp.contextqa.com/mcp, then open /mcp and sign in (Claude Code testing guide). Our Claude Code automated testing guide walks through the setup in detail.
Which tests should come from the spec, and which from the agent?
Split the work by layer. The spec drives the tests that prove business behavior. The agent writes the tests that prove its code is correct.
- From the spec, run in ContextQA: user journeys, error messages users see, role and permission behavior, and end-to-end flows across screens.
- From the agent, run in your repository: unit tests for rules like password strength, integration tests for persistence and API contracts.
- Both: boundary values. The spec defines them, and the agent should cover them at the unit level too.
ContextQA doesn't replace your Jest, Vitest or pytest runner. Claude Code runs those. ContextQA runs the browser, API and mobile tests against the deployed application.
What are the common mistakes?
- Generating tests from the code instead of the spec. They'll pass, because they describe what was built.
- Skipping clarifications. A vague answer produces a vague test that passes for the wrong reasons.
- Letting the agent edit acceptance cases. Lock them, or require a person to approve changes.
- Running against the wrong build. Always record the commit and build for each run.
- Treating "generated" as "covered". Approved, executed cases with real assertions are coverage. Drafts are not.
Bottom line
Spec-driven development with Claude Code is only as good as the check at the end. Write criteria a user could observe, turn them into reviewed tests before the code exists, and run those tests on the real build. Then "done" means the spec passed, not that the agent stopped. For the wider pipeline this loop fits into, see how to build a verification-led AI software factory.
Want to see a spec become a tested feature on your own app? Book a ContextQA demo and bring one user story.