Turn Requirements into Specs, Acceptance Tests, Plans, and Evidence-Based Handoffs

Quick answer

Before coding, translate a request into observable scenarios, invariants, non-goals, risks, and a verification matrix. Use plan mode to inspect the repository and resolve contradictions. Approve an implementation plan only when every step names its purpose, affected contract, and check. End with a handoff that contains evidence and residual risk—not “done.” The explore-plan-implement-commit sequence is documented in Anthropic's Claude Code best practices.

Convert prose into behavior

“Add team invitations” is not yet an engineering contract. Ask Claude to interview the requirement:

We need team invitations. Before proposing architecture, identify unanswered product,
security, lifecycle, and compatibility questions. Inspect existing membership and email
patterns. Separate facts found in the repo from assumptions requiring a decision.

Resolve at least:

who may invite and to which roles;
whether an existing user and a new user follow different paths;
expiration, revocation, reuse, and duplicate rules;
tenant isolation and audit requirements;
email failure behavior;
backwards compatibility and rollout.

Build a verification matrix

Turn each rule into a testable row:

Scenario	Expected result	Verification
Admin invites new address	One pending invitation	API + database assertion
Member attempts invite	Forbidden, no side effect	authorization test
Token expired	Neutral error, invitation unchanged	clock-controlled test
Two accepts race	One membership, token consumed once	concurrency integration test
Email provider fails	Transaction policy is explicit	service test + log assertion

Include negative cases and observability. A feature that works only on the happy path is unfinished.

Write a plan that can be reviewed

A useful plan states:

Existing flow and extension point.
Data and API contract changes.
Authorization and failure semantics.
Implementation sequence that keeps the tree testable.
Test additions and exact commands.
Migration, rollout, monitoring, and rollback.

Reject plans that simply list filenames. A list of edits does not explain why the system remains correct. Use plan mode to research without source edits, and open the plan for direct review where supported.

Keep an assumption ledger

During implementation, maintain three lists:

Verified facts: supported by code, tests, docs, or runtime output.
Decisions: explicitly accepted tradeoffs.
Open risks: unresolved or untestable conditions.

When a fact changes, update the plan. Do not force implementation to match an invalid plan merely because it was approved earlier.

Demand an evidence-based handoff

Use this completion contract:

At completion report:
- observable behavior implemented;
- files changed and why;
- tests/checks run with their results;
- acceptance criteria mapped to evidence;
- assumptions and residual risks;
- checks not run and the exact reason;
- rollout or reviewer actions still required.
Do not call the task complete if any required check failed.

A reviewer should be able to reconstruct the confidence argument without replaying the entire session.

Mastery lab

Choose a deliberately vague request such as “add export.” Have Claude conduct requirements discovery, produce a verification matrix, create a plan, and implement only one vertical slice. Review whether the test proves user behavior or merely mirrors implementation. Then hand the artifact to a fresh session and see whether it can accurately continue without the original conversation.

FAQ

Should Claude write the spec or should the human?

Claude can elicit and structure it; accountable humans decide product behavior, risk tolerance, and irreversible tradeoffs.

What makes acceptance criteria executable?

They name inputs, observable outputs, failure behavior, and an environment or command that can prove the result.

When should planning stop?

When remaining uncertainty is cheaper and safer to resolve through a bounded experiment than through more prose.