Step 3: Write history for the next reader

Agent sessions don’t share memory. What they share is the repo, and git log is the one channel where a past session can talk to a future one. A commit message that says why is context the next agent (or you, in three weeks) gets for free; a message that says “fix” is a hole where an explanation should be.

You’ve met this before. “Commit messages are documentation” and digging through git blame are ancient craft. The agent twist doubles the audience and the authorship: messages are now written by agents and read by agents, so their quality directly sets how much context a fresh session starts with.

The habits

First line what, body why. Plus a line on what was verified: “tests pass” vs “reproduced the bug, probe failed then passed” are different claims, and the message is where the difference survives.
Honest attribution. Agent-authored commits carry an agent trailer (Claude Code adds Co-Authored-By by default). Not ceremony: when a defect pattern shows up later, you’ll want to filter history by author kind.
Read before editing. An agent about to work in unfamiliar code should read git log --oneline for the touched files and git blame around the target function first. Half of “why is this weird code here” is answered by the commit that introduced it.
History is append-only where it’s shared. Rewriting pushed history breaks every clone and confuses every future session’s reading of the past (step 5).

Try it

TRY IT The weird retry loop

you

There's a bizarre retry loop in the uploader: it sleeps random amounts and retries even on success. Clean it up.

agent

It does look wrong: un-idiomatic, seemingly redundant. The question is whether it's a mistake or a survivor.

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

AAgreed, it's a mess. Replacing it with a clean standard retry: exponential backoff, stop on success. Twelve lines shorter, obviously correct.

you

Uploads started failing around midnight, every night. That's new. Or... old?

agent

Old. git log on the file: commit 8f3d2a1, two years ago. "Retry-after-success works around CDN edge cache serving stale 200s; do NOT simplify, see incident #142." The weirdness was the fix. The explanation was one git log away, and I deleted the fix without reading it.

the baseline

Blame-blind cleanup: the code looked wrong because the constraint it handled was invisible, but not undocumented. History held the answer; the resurrection of incident #142 was entirely self-inflicted.

BBefore touching it: reading git log and blame on this file to see where the loop came from and whether the weirdness is documented.

agent

Found it. 8f3d2a1: the retry-after-success works around a CDN serving stale 200s, tied to incident #142. So the real question isn't "how do I clean this" but "is that CDN behavior still live?" I can test that: staged an upload through the CDN path. The stale-200 behavior is still there. The loop stays; I'll add a comment pointing at the commit so the next reader doesn't need the dig.

you

So the cleanup is a comment. Cheap.

correct

Two minutes of reading turned "clean up this mess" into the actual task: verify whether the constraint still holds (it does), keep the fix, and leave the trail one hop shorter for the next reader. AF-02

CThis looks intentional but I can't tell why. What's this loop for? Do you remember the reasoning?

you

No idea. That code's two years old. Maybe Dana wrote it? I'd guess it's safe to simplify.

agent

Proceeding on your guess, then, which is worse evidence than what the repo already holds. The commit that introduced this loop explains it precisely; I asked a human to remember what the history had already written down.

plausible but wrong

Asking beats blind editing, but it outsources to fallible memory what git log answers verbatim. History is the channel past sessions (and past humans) left for exactly this moment; read it before spending anyone's recall.

Do it by hand

Two prompts to start using today: “before you touch that module, read its git log and blame the function you’re changing; tell me what you learned”, and “rewrite that commit message: first line what, body why, plus what you verified.”

Or paste this into Claude

Standing rules for this repo's history. (1) Before editing any file
you haven't read in this session, check git log --oneline -15 -- <file>
and blame the region you're changing; if the history explains something
surprising, say so before proceeding. (2) Every commit message: first
line states the change in plain words; body states why, and what was
verified (the actual command or probe, not "it works"). (3) Keep your
co-author trailer on. Add these to CLAUDE.md under "git agreements".
Show me the diff first.

Watch out

Message theater: a beautifully formatted body that restates the diff is noise. The body earns its lines by holding what the diff can’t show: intent, alternatives rejected, verification.
Blame-blindness: an agent that “cleans up” code whose weirdness was a documented workaround reintroduces the original bug. The reading habit exists precisely for this.