Commit Description as a Thinking Tool
The Cognitive Value of Manual Commit Messages
By Yedhu Krishnan | Date: 2026-09-30 | Software Development | #thoughts #agentic-coding
The Traditional Approach to Documentation
Long before the rise of AI-driven development, I maintained a habit of writing extensive commit bodies for any significant architectural or logic changes. I would typically spend five to ten minutes drafting and reviewing these descriptions to ensure no critical detail was omitted.
My goal was simple: centralize all pertinent information so that any future reader wouldn't have to scavenge through various logs or documents to understand the change.
The Anatomy of a Commit
I viewed the commit message as a two-part narrative:
- The "What": A summary of the changes. While the code itself often makes the "what" obvious, this serves as the gateway to the deeper explanation.
- The "Why": The rationale behind the decision. I often wrote this in a conversational, first-person style:
"I implemented this specific workaround because the current API is unstable, and I am doing this until we migrate to version 2.0..."
Writing as a Reflective Process
The act of writing was not merely a clerical task; it was a cognitive tool. The process of articulating the change forced me to reflect on the implementation.
Often, while trying to explain the "why," I would realize a flaw in my logic or a better way to structure the code. This reflection loop frequently led to mediocre superior technical decisions.
The Challenge of Agentic Coding
We have now entered the era of agentic coding, where AI handles everything from the initial logic to the final git commit -m "...". This has sparked a debate regarding the readability and reliability of AI-generated code.
However, the most problematic area for me is AI-written commit descriptions.
The Context Gap
AI often lacks the holistic context scattered across Slack threads, Jira tickets, or verbal meetings. When an AI doesn't know the actual "why," it doesn't stop; it invents a plausible-sounding reason.
| Feature | Human-Written Commit | AI-Written Commit |
|---|---|---|
| Context | Deep, cross-tool awareness | Limited to provided prompt/code |
| Reasoning | Based on actual intent | Often inferred or hallucinated |
| Purpose | Thinking tool for the dev | Documentation artifact |
| Accuracy | High (if reflective) | Variable/Superficial |
My Current Strategy: Manual Verification
While one could provide an AI agent with every single piece of project context to generate a convincing message, that doesn't solve the core problem: Verification. Only the human developer can truly verify if the code actually executes the intent described.
Therefore, I have adopted a strict personal rule: I write the commit messages and descriptions myself.
By manually drafting the description, I force myself to audit the AI's work. If I find myself unable to explain why a certain change was made, it is a red flag that I am shipping code I don't fully comprehend—which is a recipe for disaster when bugs inevitably arise.
Capturing the "Invisible" Logic
Some decisions are temporary and come with specific exit criteria. These are often too "obvious" to be documented in a ticket, so the AI cannot possibly infer them.
- Identify the temporary workaround.
- Define the trigger for removal (the exit condition).
- Document this in the commit body.
By forcing myself to complete the sentence "I am doing this until...", I provide a roadmap for future maintainers to decide when a piece of code is no longer necessary.
Final Thought
Ultimately, the struggle to articulate the "why" is the ultimate test of whether you actually understand the code you are shipping.