Mostly Done.
Contents

9 Keep changes small and reversible

Coding agents lower the cost of parallel implementation. They do not lower the cost of deciding which integrated revision deserves trust. Fan the work out across branches and worktrees, then pull it back through a narrow integration path. Production can happen in parallel. Shared truth is established one revision at a time.

9.1 One decision per branch

A branch should represent one coherent claim. That keeps the diff reviewable, the failure local, and the revert meaningful.

In practice the rule looks unglamorous. Keep the new language frontend off the renderer branch. Give each issue its own branch. Hold pixel-changing work until its safety net exists. When a complexity gate refuses to let a feature hide inside an oversized entry function, decompose the function first, on its own branch.

The point is not branch purity. The point is causality. When a branch mixes a parser, a renderer, a migration, and a structural rewrite, a red test has too many parents and a revert removes too much.

A branch boundary holds when it has:

Branch discipline covers other people’s branches too. Consider an outside contributor’s fix that has been open for half a day when an internal duplicate lands by fast-forward, putting the contributor’s branch into conflict. The contributor’s tests then find a real defect in the merged duplicate: quote termination that ignores escape parity. The right repair is to fix the gap, salvage the unique test cases with credit, and apologize. Repository state includes open pull requests. Conflicting code can be redundant while its tests contain unique evidence.

9.2 Isolate implementation with worktrees

Separate worktrees give each agent a stable checkout and reduce accidental overlap. They also preserve reasoning: a reviewer can see which assumptions belonged to the branch before later changes blurred them.

Isolation alone is not enough. Each worktree should receive the same standing rules: current base, commit discipline, local gates, required documentation, critical review, and completion bundle. Set the rules once so the conversation can stay terse.

The agent should report the exact revision it tested. Green in my worktree means something only when you know the worktree’s base and commit.

9.3 Merge one change, then test the new tree

Feature branches establish local facts. Integration creates a new object.

Take two pull requests, both green on their own branches: one introduces new language frontends, the other an edge-label linter. After both merge, a lint-cleanliness test fails on main. A fixture from the first branch left a 7-point label stub against the second branch’s 10-point minimum. The fixture and the rule first shared a tree at the merge. Neither branch was wrong. The combination was.

This suggests a strict sequence:

  1. refresh the branch against current main;
  2. rerun its targeted and full checks;
  3. merge one coherent change;
  4. run the full suite on the resulting tree;
  5. inspect generated and public artifacts;
  6. continue only after the integrated revision is understood.

A merge queue can automate the mechanics. It cannot change the fact that green belongs to a specific tree.

9.4 Build the net before changing the pixels

Order the work: safety nets, then correctness, then structure, then features. Land the CI graph and the render harness before the fix they are meant to protect. Make pixel changes wait for a pixel detector that has itself survived tampering. Let structural cleanup follow the correctness repair instead of riding along as an unreviewable rewrite.

This order looks slow because the feature you want appears last. The net turns each later edit into a smaller risk, and that is where the time comes back.

9.5 Reversibility requires more than Git

Any commit can be reverted mechanically. A product change is reversible only when its data, compatibility, and public surfaces can also move backward without guesswork.

For language and workflow changes, ask:

When runtime reality disproves a shipped feature, you want the reversal to be ordinary: no sunk cost to defend, no concept to salvage. That is only possible when the work was bounded in the first place.

9.6 Completion reaches the user

A merged PR is not a release, and a green release workflow proves less than it appears to. Consider a project whose release automation and required checks live in separate workflows. The publish workflow stays green and ships two releases while a required CI step, a migration parity check, has been red for weeks. Nothing connects the green workflow to the red one, so the green one publishes. The rule that survives the repair is blunt: verify the whole CI run, not one job.

The completion path should be explicit:

source -> integrated tests -> whole required CI graph -> built artifact -> published release -> live surface

Be as skeptical of regeneration as of any other publishing step. A gallery regenerates in CI on every push. One run marks 62 images dirty; a pixel comparison at 2 percent fuzz finds 52 of them byte-different but visually identical, and exactly the ten meaningful changes are committed. Regeneration reports rewritten artifacts. Pixel comparison reports visual changes.

Small increments help here too. A release containing one coherent change is easier to inspect, explain, and roll back.

Agents make it cheap to create branches. Engineering still happens where those branches become one product.

use ← and → to turn pages