Claude tends to just narrate the change when it writes the commit message. Which is not very interesting. Anyone can read the diff and figure out _what_ it does. The interesting is why.

So I've been instructing Claude to commit like Jeff King.

At first, Claude would mainly just cosplay Peff. Emulate the prose and not the process. Over the last few months I've been iterating on it and now Claude writes vastly better commit message than by default.

Initially, Claude would produce A LOT of plausible sounding reasons the LLM "thought" made sense. Instruct an LLM to give reason and it'll give you reasons -- whether they are real or not. After trying to instruct it not to lie, make shit up etc (which did not work) I instead started forcing it to articulate the source of the rationales. Especially which claims where unsubstantiated, and this seems to have helped a lot.

Then I instructed it to do some thorough investigation before it commits.

Start by writing a brief that gathers different "evidence" that underpins a change. The diff itself. The surrounding context. A bit short git log. A blame on the touched lines to see what previous commits touched this code and for what reasons.

Once it's done the agent has to tag each claim according to a category. I.e. what claims are attributed to the change itself (the diff), the inciting incident (gathered from session or if missing, by follow-up questions), what's inferred by the model (unsubstantiated claims.)

Only after this supersize is it tasked with writing a commit message given this brief. Or to ask follow-up questions if there's only unsubstantiated claims or gaps in the brief. Furthermore, it is tasked with writing a note to detail assumptions it has made and, or other relevant bits of information that are not commit message worthy, but possibly still interested in noting down. Decisions made. Options not taken. Possible rationales for the change that didn't make the cut.

All of this tends to make pretty good commit messages. Not perfect, but a good starting point.

Right now my biggest challenge is finding instructions to write the Goldilocks message. Not too brief and not too long. Instruct it to be clear and concise and relevant information gets left out. Say nothing and get a Dostoevsky novel. At least when it writes too long messages it's easy enough to go in afterwards with a `git history reword` and take out the axe.

One of the biggest upsides has been, just as when you read a human that writes commit messages like this, is spotting misunderstandings. Several times I've spotted gaps in the reasoning of the message that doesn't match reality, and caught mistakes. A bit like when you use plan mode.

Commit description as a thinking tool