The era of AI-written code has arrived, and with it comes a new problem: commit descriptions that make no sense. A developer who once spent five to ten minutes crafting detailed notes on every major change now finds himself staring at machine-generated explanations that read like gibberish. The source of the trouble is simple: the AI has no idea why it did anything.
Commit descriptions are meant to be records. They capture what changed and why, so anyone reading the code later can understand the thought behind it. When a human writes one, the act of composing forces reflection. The writer rereads the code, summarizes the changes, and explains the reasoning — a process that often reveals flaws or better paths before the code ever lands. Now, that loop is broken.
The Old Way of Writing Commits
Before AI entered the picture, commit descriptions were a deliberate act. The writer included everything useful so readers wouldn’t have to hunt for details across multiple places. The goal was to explain both what and why — the “what” being the self-explanatory changes, the “why” being the reasoning behind them.
The writer used first-person phrasing to make the message personal. Phrases like “I did this because…” and “I am doing this until we…” served as anchors for the reasoning that followed. The result was a note that explained the code to future readers and, more importantly, to the writer’s future self.
This was a good exercise. It wasn’t just about drafting a commit message. The writing process forced reflection on the code itself. Reading the code and summarizing the changes led to re-evaluating decisions, which sometimes produced a different or better outcome. The commit description worked as a thinking tool — a way to work through ideas before committing to them.
Agentic Coding Arrives
Today, everything from code to commit descriptions is written by AI. That shift has sparked a debate over whether we should even read AI-written code, and how readable it is. The part that troubles the writer is reading and understanding AI-written commit descriptions.
Agents can generate commit messages for the changes they make. But they lack the full context that spreads across different communication and project management tools. Some of those tools might be offline. When the AI doesn’t know the “why” part, it invents its own reasoning. That invented reasoning is dangerous, the writer argues — when we read it later, it may not make sense because the real reason was completely different.
The AI fills in reasons that aren’t there, and the result is a commit description that reads like a fiction. The writer describes finding this difficult. The reasoning gap is the core problem — the AI doesn’t have the information needed to explain why, so it substitutes its own guesses.
Why The Writer Writes Them Himself
One obvious solution is to give the agent all the context it needs. Through chat or tools, the writer can feed the AI the missing information. With the right context, the agent can explain the “why” clearly. But this doesn’t fix the other problem.
The agent with the right context will write a convincing commit message. But only the human can verify if the code does what the description says. That verification gap is where the trouble starts. The AI can explain its reasoning, but it can’t check whether that reasoning matches reality.
So the writer does something else: he writes the commit message and description himself. Here is why he does it.
Commit Descriptions As Thinking Tools
Writing a commit description forces reflection on the changes AI made. It is also a way to check if everything is as intended. If the writer cannot explain “why,” he is shipping something he doesn’t understand — which will be hard to explain or fix if it breaks later. The old quote applies here: if you cannot explain it, you did not understand it.
Some parts of a commit message are temporary decisions with exit criteria. We sometimes set conditions for when a change stops being necessary, and AI cannot infer those from code or other tools because they are usually not written down anywhere. Those conditions seem too obvious to mention. But writing the commit message forces the writer to complete that sentence, and it helps future readers decide whether to keep that change.
The agent can write the code and the description. But writing why is where you find out whether you understand what you are shipping. That distinction matters. Code can be generated without comprehension; reasoning cannot.
What The Writer Actually Does
The writer’s process is straightforward. He reads the code, summarizes the changes, and explains the reasoning. The first-person phrasing — “I did this because…” — serves as a prompt to anchor the explanation. The act of writing forces him to work through the logic before committing to it.
The goal is to produce a note that captures the whole picture — what changed, why it changed, and what the next steps are. That note becomes the record of the decision.
The writer’s method is a form of self-checking. By writing the description himself, he ensures the reasoning matches the code. The AI can generate the code, but it cannot verify that the reasoning holds. The human can.
The Reasoning Gap
The reasoning gap is the central issue. The AI generates code based on available data, but it cannot access the full context that humans carry around in their heads. That context includes conversations held in chat, decisions made in meetings, and assumptions that seem obvious at the moment but vanish from written records.
When the AI lacks that context, it fabricates reasoning. The writer describes this as dangerous — when we read that reasoning later, it may not make sense because the real reason was completely different. The fabricated reasoning is a symptom of a problem: the AI is working without the full information it needs.
The Verdict On AI-Generated Commit Descriptions
The writer’s conclusion is blunt: AI-generated commit descriptions are hard to read because the AI fills in its own reasons. That reasoning gap is the source of the difficulty. The machine doesn’t know why it did something, so it invents an answer — an answer that will likely confuse anyone reading it later.
The writer’s solution is to write the commit messages himself. He does this for two reasons:
- To force reflection on the changes AI made
- To check if everything is as intended before shipping
That second reason is the crux. Shipping something you don’t understand is a recipe for disaster. The commit description becomes a test of comprehension — if you can’t explain the reasoning, you haven’t understood the code.
The writer’s approach is a practical one. It doesn’t reject AI entirely; it simply assigns the reasoning task to the person who actually understands the problem. The AI writes the code, the human writes the why, and the human verifies the fit.
The Future Of Commit Descriptions
The reasoning gap is a fundamental problem — one that requires human insight to close. The writer’s method is a stopgap. It works now because it forces the kind of attention that machines currently lack.
Until machines can truly understand the reasoning behind their actions, the human writer will remain the keeper of the why. The commit description remains a thinking tool — a way to work through ideas before committing to them. Whether that tool is wielded by hand or by machine is secondary to the question of comprehension. The writer who understands what he ships will always have the edge, regardless of who writes the code.
Source material: “Commit description as a thinking tool,” yedhu.me.
Get the Notebook.
The day's best stories and every fresh verdict, in plain English, in your inbox by seven. One email a day, no more.