Behavior Contract Phased Plan — Claude Code Guide

Behavior contract before changing the source state

A migration must preserve more than happy-path output. A behavior contract covers inputs, outputs, errors, side effects, order and timing where they are observable, idempotency, retries, persistence, and recovery behavior.

The contract does not mean that implementation or internal structure remains unchanged. It defines what must be compared between source and target and which deviation requires an owner decision.

Phased migration plan

Phase	Evidence gate	Decision	Rollback/hold
Discovery	source state and scope are reproducible	proceed to analysis	hold on critical unknowns
Analysis	changelog, graph, and matrix have anchors	choose a pilot	narrow scope or hold
Pilot	bounded slice and behavior checks	test the target hypothesis	return to the source checkpoint
Verification	focused and contract checks	expand or rework	rollback on discrepancy
Expand / hold	risk gate and owner decision	increase coverage or stop	disable/rollback by procedure
Retirement	exit criteria and migration evidence	remove the old path only after evidence	keep coexistence

Phase fields that cannot be skipped

one bounded scope and a responsible owner;
a concrete evidence gate, not a general “check it”;
exit criteria that can be observed or reproduced;
a practical rollback or hold action with a known return point;
a GO, HOLD, narrow, or rollback decision with an explanation and open unknowns.

A plan is not evidence that migration was completed

A documented migration plan describes a future sequence and decision criteria. It does not prove that dependencies were updated, the pilot passed, production is compatible, or rollout finished. An actual result appears only after real commands, tests, review, and an evidence record.

If the behavior contract cannot be checked or the compatibility matrix contains a blocking Unknown, the correct decision is HOLD rather than an optimistic GO.