Change Shape
Change-shape rules cover one-purpose changes, small follow-ups, generated artifacts, dependency churn, ownership, and structure-versus-behavior review boundaries.
Change scope, review shape, generated artifacts, and follow-up boundaries.
13 rules
Avoid Speculative Public APICHANGE-AVOID-SPECULATIVE-PUBLIC-APIAdd public surfaces only when current or accepted callers need them. Waiting for concrete pressure keeps compatibility commitments smaller and easier to validate.Avoid Unnecessary Dependency ChurnCHANGE-AVOID-UNNECESSARY-DEPENDENCY-CHURNKeep package, manifest, and lockfile movement out of unrelated work. Separate dependency changes make build, compatibility, and downstream risk reviewable on their own.Identify Owning Module Before EditingCHANGE-IDENTIFY-OWNING-MODULE-BEFORE-EDITINGFind the component that owns the concept before adding or moving logic. That keeps invariants, tests, and future maintenance close to the responsible code.Isolate Controversial ChangesCHANGE-ISOLATE-CONTROVERSIAL-CHANGESPut risky or contentious moves in their own review unit when they can stand alone. This lets reviewers approve, reject, or revise the decision without incidental cleanup attached.Minimal but CompleteCHANGE-MINIMAL-BUT-COMPLETEKeep the diff as small as the purpose allows while including the evidence that purpose needs. Reviewers should see one coherent unit they can understand, validate, and revert.Pin Behavior With Early TestsCHANGE-PIN-BEHAVIOR-WITH-EARLY-TESTSAdd characterization tests before changing messy behavior when the existing contract is unclear. The baseline separates intentional behavior changes from accidental drift.Prefer Small Follow-UpsCHANGE-PREFER-SMALL-FOLLOW-UPSMove adjacent cleanup or broader improvements into focused follow-up changes when the current diff can stand alone. This preserves review focus while still capturing useful work.Preserve Unowned WorkCHANGE-PRESERVE-UNOWNED-WORKTreat nearby edits from users, agents, generators, or earlier changes as outside your ownership unless the task says otherwise. Adapting around them protects parallel work and context.Respect Generated Artifact OwnershipCHANGE-RESPECT-GENERATED-ARTIFACT-OWNERSHIPFix generated outputs through their source inputs, templates, metadata, or generator configuration whenever those own the result. Hand edits are durable only when the tool workflow explicitly supports curation.Separate Structure From BehaviorCHANGE-SEPARATE-STRUCTURE-FROM-BEHAVIORSplit refactoring or layout changes from behavior changes when the combined diff obscures intent. Separate review units make meaning preservation and new behavior easier to check.Sync Generated ArtifactsCHANGE-SYNC-GENERATED-ARTIFACTSUpdate checked-in generated outputs when their source inputs change and they are part of review. Keeping them aligned prevents consumers from seeing stale artifacts.Treat And as Scope WarningCHANGE-TREAT-AND-AS-SCOPE-WARNINGUse compound change descriptions as a prompt to inspect whether the work has more than one purpose. The word is not a rule, but it catches scope creep while splitting is still cheap.Use One Purpose per ChangeCHANGE-USE-ONE-PURPOSE-PER-CHANGEShape each change around one review question and one reason for existing. Related tests, docs, and generated files can travel with it when they support that same purpose.