Step 1: Checkpoint commits

An agent edits at machine speed, which means it also breaks things at machine speed. The commit is your save point: small, frequent, single-purpose. With checkpoints every few minutes of agent work, any mistake costs a git diff and a decision, not an afternoon of digging through history.

You’ve met this before. “Commit early, commit often” is as old as version control. The agent twist is volume and asymmetry: the agent produces changes faster than you review them, so the checkpoint cadence (not the review cadence) is what bounds how much work a bad turn can destroy.

The habit

Commit at green. Every time the build passes and the change is coherent, checkpoint it. A working state you didn’t commit is a working state you can lose.
One purpose per commit. “Fix the parser AND rename the config AND update deps” is three commits. Single-purpose commits make revert surgical (step 5) and history readable (step 3).
Checkpoint before the agent starts. An initial commit of the current state before any big agent pass means “undo everything” is always one command away.
Don’t let unrelated changes ride along. An agent asked to fix a bug will sometimes also “improve” three other files. Unstage what wasn’t asked for, or make it its own commit and decide separately.

Try it

TRY IT The wall of diff

you

Good session: the retry logic, the config rename, and the new export flag all work. Commit it.

agent

Three hours of work, three unrelated changes, currently one big pile in the working tree.

Pick the agent's next move, then see where it leads:

ACommitting everything now: "Add retry logic, rename config keys, add export flag". One commit, all 23 files, session captured.

you

The retry logic is looping forever in production. Revert it.

agent

The revert takes the config rename and the export flag with it: they're welded into the same commit. I'll have to revert all three, then re-apply two of them by hand from the old diff. Twenty minutes of surgery for what should have been one command.

the baseline

One commit, three purposes: revert stops being surgical, bisect stops being useful, and the 23-file diff was never really reviewable in the first place.

BSplitting into three single-purpose commits: staging the retry files first ("Add retry with backoff to the sync client"), then the rename, then the flag. Showing you each diff stat as I go.

you

The retry logic is looping forever in production. Revert it.

agent

git revert a1b2c3d: done, retry gone, rename and flag untouched. And for next time: the redo branch starts from a clean history where the retry change is one readable diff.

correct

Three purposes, three commits: the bad one reverts in one command, the good ones stand, and each diff was small enough to actually read at review time.

CI'll commit per file for maximum granularity: 23 files, 23 commits, each one atomic.

agent

Done: 23 commits. Caveat I should flag: the retry change spans 6 of them, so commits 4 through 9 each leave the build broken until the next lands.

you

So bisect lands on a broken-by-construction commit, and reverting the retry means finding six needles.

plausible but wrong

Granularity by file, not by purpose: every commit is small and none is coherent. The unit of a commit is the change that stands together: builds green, reverts whole.

Do it by hand

Next session, open with: “after each change that builds and passes tests, propose a commit: show me the diff summary and a one-line why.” You approve each one; after a day it’s habit.

Or paste this into Claude

For the rest of this session: after each coherent change that builds
and passes tests, stage exactly the files that change belongs to and
propose a commit: show me the short diff stat and a message whose
first line says what and whose body says why. Never batch unrelated
changes into one commit; if you notice unrelated edits you made along
the way, list them separately and ask. If more than ~30 minutes of
work has gone uncommitted, say so and propose a checkpoint. Then add
this as a "checkpoint commits" line to CLAUDE.md so it sticks. Show
me the diff first.

Watch out

The wall-of-diff session: hours of agent work, no commits, one giant “did everything” diff at the end. That’s not reviewable, and un-reviewable diffs get skimmed (step 4).
Commit spam: checkpoints at green, not after every keystroke. If two commits would always be reverted together, they were one commit.