Let the Agent Write the Code. Write the Commit Message Yourself.

Let the agent write the code. Write the commit message yourself.

That sentence is going to annoy people, because the obvious 2026 answer is: the agent already writes beautiful commit messages. Conventional Commits format, tidy scope tags, a tidy body, sometimes even a little "Generated with Claude" footer. It looks more professional than what most of us wrote by hand for years.

But last week a short essay by Yedhu Krishnan called Commit description as a thinking tool made the Hacker News front page, pulled in 130 points and 78 comments, and then resurfaced on the front page again today, days later. That second life is the tell. The argument is not about formatting. It is about a specific, quiet failure mode, and once you see it you cannot unsee it in your own repos.

Full disclosure up front: I did not invent this idea. The essay did. What follows is my breakdown of its argument, the discussion around it, and the checklist I now apply to every commit in my own AI-heavy workflow, including the agent infrastructure I run at home. If you want the pure source, read the essay first. It takes four minutes.

The problem: an agent that guesses the why

The essay's core observation is simple. Before AI tools, writing a long commit description for a major change took five to ten minutes: draft, reread, make sure nothing important was missing. The description answered two questions. The what summarized the changes, and the why explained the reasoning, often written in first person, like a message to a future reader: "I did this because...", "I am doing this until we...".

Then agentic coding arrived, and everything from code to commit descriptions started getting written by AI. The essay does not relitigate the debate about whether engineers should read AI-written code. It focuses on something easier to overlook: reading and understanding AI-written commit descriptions.

Here is the mechanism of the failure:

• Agents lack your context. The real reason for a change is usually scattered across chat threads, ticket comments, standups, and your own head. Some of it was never written down anywhere.
• When the agent does not know the why, it invents one. The code diff implies a plausible rationale, so the model back-fills a reasonable-sounding explanation. The essay calls this dangerous, and the word fits, because the output is not a guess flagged as a guess. It is fluent, confident prose.
• Six months later, the fake why beats your memory. You open the history to understand why a workaround exists. There is a clean paragraph explaining it. Except the real reason was completely different, and now you are reverse-engineering your own past from a hallucinated source.

Anyone who has done archaeology in a long-lived repo knows the sensation. The difference is that pre-AI, a wrong explanation in history was written by a confused human on a bad day. Now it can be generated at scale, on every commit, by default, and it reads better than the truth would.

Temporary decisions are where this hurts most

The sharpest point in the essay is about temporary decisions with exit criteria. Phrases like "I am doing this until we migrate to X" or "this flag stays until the vendor fixes the API" are everywhere in real codebases. Those exit conditions are rarely captured in tickets, because at the time they feel too obvious to write down.

But forcing yourself to complete the sentence in the commit message does two things:

• It catches incomplete thinking now. If you cannot finish "I am doing this until...", you do not actually know your exit condition. Better to discover that at commit time than in a production incident review.
• It gives future readers a decision to make. A reader in 2027 who finds "temporary, remove after Q3 migration" can check whether the condition passed and act. A reader who finds a diff with no stated expiry has to guess whether the hack is still load-bearing.

An agent cannot infer this from code or tools, because it was never written down. It is exactly the information that only exists if a human is forced to articulate it.

The HN discussion pushed it further

The comment thread (worth reading in full) surfaced a few extensions that I found convincing:

• The description is a design review you give yourself. Several commenters described writing the commit body and, in the process, noticing the change was wrong. The diff is the implementation. The description is the argument, and arguing your case in writing exposes hand-waving that code hides.
• Revert archaeology is a first-class use case. When something breaks and you bisect, the commit that introduced the bug is often not wrong in isolation. It made sense given a constraint that no longer exists. If that constraint is in the message, git log becomes a decision log, not just a change log.
• AI can draft, but you must verify the why. The pragmatic middle ground multiple people landed on: let the agent summarize the what from the diff, then you write or correct the why by hand. The mechanical part is delegable. The judgment part is not.

There was also the inevitable counterpoint: nobody read commit messages anyway, so why invest. The essay's implicit answer is the strongest one. The primary reader of your commit description is you, and the act of writing it is the value, exactly the way writing documentation clarifies your own understanding even if nobody else reads it.

The checklist I use now

Here is the concrete part you can steal. Every non-trivial commit in my workflow now has to answer five questions. It takes about five minutes, which matches the essay's own estimate for a major change.

• What changed, in one sentence a teammate could skim? The subject line plus a one-line summary. The agent can draft this from the diff, and its draft is usually fine here.
• Why was this change made, in the author's own words? Not "refactor for maintainability". The actual trigger: the bug report, the profile, the customer complaint, the upcoming migration. If this section sounds like it could have been generated from the diff alone, it is not done.
• Is any part of this temporary? If yes, the message must contain the exit condition and, where possible, a date or milestone: "remove once X ships", "delete after the Q1 cutover". No unanchored "temporary".
• What was rejected? One line on the alternative you considered and why this won. This is the part future-you forgets first, and it prevents re-litigating the same decision every year.
• Could an agent have written this why from the diff alone? If it could, the why is too shallow. Deepen it or accept that the commit is purely mechanical.

Two practical rules make the checklist stick:

• Write the message before approving the code. When an agent produces a change, draft the description while reviewing the diff, not after. If you cannot explain the why while the diff is on screen, you are not reviewing, you are rubber-stamping.
• Treat a fluent, generic description as a red flag. "This commit improves the overall structure and handles edge cases" is the prose equivalent of a shrug. Generic explanations are what models produce when they do not know, which is precisely when a human needs to step in.

What I would tell my younger self

For years I treated commit messages as a chore performed for other people, and skipped them whenever the change "spoke for itself". The essay flipped the framing for me: the description is not documentation for the team. It is a thinking tool for the author. The five minutes is not overhead on the work. It is the moment you find out whether you understand what you are shipping.

And that is the real risk with agentic coding, bigger than any single bad commit message. Every step we delegate is a step where understanding can quietly leak out of the human. Reading AI code is the expensive, obvious part of that problem. Commit descriptions are the cheap, boring place to push back. Write the why yourself, and you keep one guaranteed dividend on every change: you knew what you were doing, and why, on the day you did it.

---

I write about Git, AI-assisted development, and backend engineering every week. Subscribe, it is free.

Do you still write commit bodies by hand, or has your agent taken that over too? I would genuinely like to hear how it is holding up in the comments.

If you found the checklist useful, save this piece. That is the part worth coming back to.

Comments

[IndiaInfraNotes]

Strong rule. The commit message is the one place a human has to state intent, and if the agent writes that too, review turns into checking that the code matches its own summary. A cheap test: if you cannot write the message without opening the diff, you probably did not review it yet. Do you enforce this with a hook, or is it a team norm?

iin1005h21