On this page#
What changes when an agent does this#
Spec-driven development with Claude Code moves the bottleneck from writing code to defining intent, protecting invariants, and reviewing evidence. The agent can explore and implement quickly; the engineer must decide what “correct” means before implementation begins and prevent plausible-looking changes from quietly expanding the scope.
A specification is not a long feature brief. It is an executable boundary for the work: required behavior, forbidden behavior, repository constraints, acceptance checks, and rollback conditions.
That distinction matters because Claude Code operates inside a real development environment. It can inspect a repository, reason across files, and perform coding tasks. More capability does not reduce the need for judgment. It concentrates judgment into a few high-leverage decisions.
The workflow should therefore separate four states:
- Discovery: understand the repository without changing it.
- Specification: convert the request into explicit constraints and acceptance criteria.
- Implementation: make only the approved changes.
- Verification: prove the result against the specification.
Do not collapse these states into one prompt. “Investigate, fix, test, and commit” feels efficient, but it removes the point where an engineer can catch a wrong model of the system before that model becomes a large diff.
The central rule is simple: the agent may propose the contract, but a human owns it.
Photo by Christina Morillo on Pexels.
The prompt chain#
Use a staged prompt chain that produces inspectable artifacts before code. Each prompt should narrow the agent’s authority, identify what it may assume, and define the output required for the next gate. The chain is deliberately repetitive because repetition is cheaper than discovering an unstated assumption inside a finished implementation.
Stage 1: Repository discovery#
Start with read-only investigation. The goal is not a solution; it is a map of the relevant system and a list of uncertainties that could invalidate the task.
Investigate this request without modifying files:
[REQUEST]
Identify:
- the entry points and execution path involved;
- existing tests, validation, and error handling;
- repository conventions that constrain the change;
- invariants that must remain true;
- ambiguous requirements or missing decisions;
- the smallest likely change surface.
Do not propose implementation details until you have cited the relevant files
and explained how the current behavior works.This wording prevents premature implementation and demands repository evidence. The official Claude Code documentation explains the product’s working model; your prompt still needs to define the local authority boundary. The tool cannot infer which architectural constraints your team considers non-negotiable.
Stage 2: Draft the specification#
Turn the discovery output into a contract that can be rejected before code exists.
Draft an implementation specification for this request.
Include:
- current behavior;
- required behavior;
- explicit non-goals;
- invariants that must not change;
- files or components expected to change;
- acceptance criteria;
- tests required for each criterion;
- risks and unresolved questions;
- a rollback boundary.
Do not edit the repository. Mark every assumption as ASSUMPTION and every
blocking decision as DECISION REQUIRED.The labels matter. Unmarked assumptions disappear into polished prose; visible assumptions invite correction.
Keep the specification small enough to review. If it cannot state the change surface and non-goals clearly, implementation is not ready. Engineers who need more practice constructing these boundaries can use PairFoundry’s free foundations track before introducing the workflow across a team.
Stage 3: Produce an implementation plan#
After approval, request an ordered plan tied directly to the acceptance criteria.
Using only the approved specification, produce an implementation plan.
For each step, state:
- the file or component affected;
- the behavior being changed;
- the acceptance criterion satisfied;
- the verification to run immediately afterward.
Stop if repository evidence contradicts the specification. Do not broaden scope
or resolve a new product decision without approval.This is where weak workflows usually fail: they treat the approved spec as inspiration rather than authority. “Improve related code while you are there” is not initiative; it is uncontrolled scope expansion.
Stage 4: Implement and report deviations#
Only now should the agent edit code.
Implement the approved plan one step at a time.
After each step:
- run the narrowest relevant verification;
- report changed files and the criterion addressed;
- stop on unexpected failures, contradictory behavior, or required scope changes.
Do not commit, reformat unrelated files, update dependencies, or alter public
interfaces unless the specification explicitly requires it.Claude Code’s official overview describes an agentic coding workflow, but it does not own your repository’s definition of done. That definition must remain explicit in the prompt chain.
The gate#
The mandatory gate sits between the drafted specification and implementation. A human must stop, read the proposed contract against the repository evidence, and approve or revise it. Reviewing only the final diff is too late: a clean implementation of the wrong contract is still the wrong change.
The reviewer should answer five questions:
- Does the stated current behavior match the cited code paths?
- Are the invariants complete and testable?
- Do the non-goals prevent obvious scope creep?
- Does every acceptance criterion describe observable behavior?
- Can the change be rolled back without preserving partial assumptions?
Reject the specification if it contains phrases such as “handle edge cases,” “update as needed,” or “ensure compatibility” without naming the behavior. Those phrases transfer design authority back to the agent.
Approval should be explicit:
Approved specification: [SPEC IDENTIFIER OR PASTED TEXT]
You may implement only this specification. Any contradiction, new dependency,
public-interface change, or additional file outside the stated change surface
requires a stop and a revised specification.For high-risk changes, add a second gate before commit: inspect the diff, test evidence, and any deviation report together. PairFoundry’s Review and Repair is the relevant next step when the main problem is validating and correcting agent-produced work rather than generating more code. The broader pack overview separates that need from other workflow problems.
Photo by Daniil Komov on Pexels.
What it gets wrong#
The agent most often fails by building a coherent solution around an incorrect assumption. Syntax errors are visible; semantic drift is dangerous because the code, tests, and explanation can all agree with one another while violating an unstated repository invariant.
Watch for these failure modes:
| Failure mode | Recognition signal | Required response | |---|---|---| | Invented current behavior | Explanation lacks file-level evidence | Return to discovery | | Scope laundering | “Necessary cleanup” appears outside non-goals | Reject the extra diff | | Test mirroring | Tests repeat the implementation’s assumptions | Re-anchor tests to acceptance criteria | | Silent interface change | Callers, schemas, or errors change unexpectedly | Stop and revise the spec | | Happy-path completion | Existing failure behavior is untested | Add explicit negative criteria | | Spec obedience over reality | Repository evidence contradicts the approved plan | Pause; do not force implementation |
A passing test suite is not sufficient when the new tests were derived from the same mistaken interpretation as the code. Verification must trace back to externally observable acceptance criteria and preserved invariants.
Do not ask the agent to “fix everything you notice.” That prompt destroys the rollback boundary and makes review nonlinear. Capture adjacent issues separately, then decide whether they deserve their own specification.
The Claude Code documentation can explain available capabilities and operation. It cannot identify your undocumented compatibility promises, operational constraints, or team ownership boundaries. Those remain human inputs.
Rollback#
A clean rollback begins before implementation: isolate the change, record the starting state, forbid unrelated edits, and define what must be removed if verification fails. Rolling back after an uncontrolled multi-purpose diff is not recovery; it is manual archaeology.
Before edits, require the agent to report the current branch, working-tree state, and files expected to change. Preserve any pre-existing work and never treat an already dirty file as disposable.
Use a dedicated branch or equivalent isolated workspace. Then keep the rollback unit aligned with the approved specification:
- Inspect the final diff and separate unrelated changes.
- Preserve logs or failure evidence needed for diagnosis.
- Revert only the commits or edits created for the specification.
- Restore generated artifacts or dependency metadata only if this task changed them.
- Run the pre-change verification again.
- Confirm that the original working state—including pre-existing local changes—remains intact.
Do not use destructive cleanup as a default rollback technique. Commands that erase all local modifications can destroy work that existed before the agent started. Prefer targeted reversals whose scope can be reviewed.
If the implementation exposed a flawed specification, do not immediately retry with “fix the fix.” Return to discovery, amend the contract, and pass through the gate again. More workflows built around bounded agent execution are collected in PairFoundry’s workflow hub.
Photo by panumas nikhomkhai on Pexels.
Related reading#
- Codex CLI changelog, with the guardrails that keep it honest
- Codex CLI docs — where the agent helps and where it quietly hurts
FAQ#
When should I not use this workflow?#
Do not use the full chain for trivial, mechanically verifiable edits whose behavior and change surface are already obvious. Also avoid agent-led implementation when the repository cannot be inspected safely, the acceptance criteria are unavailable, or the responsible engineer cannot review the specification. In those cases, the gate would be ceremonial rather than protective.
How is this different from following the official Claude Code workflow?#
Official guidance explains how to use Claude Code; this workflow adds a repository-specific control system around it. The distinction is ownership: Claude Code’s overview describes the agentic tool, while your specification defines permitted scope, invariants, acceptance evidence, stop conditions, and rollback boundaries for one real change.
What usually breaks when a team adopts spec-driven agent work?#
Teams fail when specifications become verbose tickets rather than enforceable contracts. Different reviewers then interpret “approved” differently, agents broaden scope without stopping, and generated tests validate generated assumptions. Standardize the required sections, explicit approval language, deviation rules, and evidence expected at the final review gate.
What should I do when the agent discovers the approved spec is wrong?#
Stop implementation and revise the specification. Do not let the agent silently reconcile the contradiction, even when its proposed fix appears reasonable. Record the repository evidence, update the affected assumption or acceptance criterion, obtain approval again, and restart from the first plan step invalidated by that change.
Can I roll back safely if the repository was already dirty?#
Yes, but only if the initial state was recorded and the agent’s edits remained isolated. Review changes file by file, preserve pre-existing modifications, and reverse only the task-owned diff or commits. If ownership cannot be distinguished confidently, stop; broad cleanup commands are the wrong tool for recovering a mixed working tree.