Why Developers Must Write Commit Messages to Understand AI Code

Overview

The rise of agentic coding has fundamentally altered the development workflow, shifting the burden of creation from humans to artificial intelligence. While this transition promises efficiency, it introduces significant risks regarding code comprehension and accountability. A growing consensus among senior engineers suggests that despite AI's ability to generate both code and commit messages, developers must retain the practice of writing their own commit descriptions.

This is not merely a matter of documentation hygiene. It is a critical cognitive exercise that ensures the engineer understands the logic, intent, and temporary nature of the changes they are shipping. As AI agents become more autonomous, the human role shifts from writer to verifier, making the act of articulation the final gatekeeper of code quality.

The Value of the Manual Commit Process

Before the widespread adoption of AI coding assistants, experienced developers often spent five to ten minutes drafting detailed commit bodies for major changes. This process was rarely about bureaucracy; it was a disciplined method of reflection. The primary goal was to provide readers with all necessary information in one place, eliminating the need to hunt through disparate sources to understand a change.

"The writing process itself helps me reflect on the code I wrote. During that process, I tend to re-evaluate the decisions, and sometimes that leads to a different or better change."

This practice served two distinct purposes: summarizing the what and explaining the why. While the summary of changes is often self-explanatory, the reasoning behind them is where the true value lies. Developers frequently used first-person narratives, such as "I did this because..." or "I am doing this until we...", to frame the commit as a message to a future reader.

This approach forced the developer to re-evaluate their decisions. By rereading the code and summarizing the changes for a commit message, engineers could identify logical flaws or better alternatives before the code was even merged. It was a tangible thinking tool that prevented blind acceptance of temporary fixes or suboptimal implementations.

The Problem with AI-Generated Context

In the current era of agentic coding, AI tools can autonomously write both the code and the corresponding commit descriptions. However, a critical gap exists between what the agent knows and what the developer knows. Agents typically operate within the bounds of the codebase and direct chat prompts. They lack access to the full spectrum of context that humans hold, which is often scattered across offline conversations, project management tools, and unspoken team agreements.

When an AI agent lacks the why, it does not simply leave it blank. Instead, it fabricates a plausible-sounding reason to fill the void. This is dangerous because the generated commit message will be coherent and convincing, yet potentially factually incorrect regarding the actual intent.

1. Fabricated Reasoning: Agents may invent logical justifications that do not align with the real business or technical constraints driving the change.
2. Missing Exit Criteria: Many temporary code changes are made with a specific exit condition in mind, such as "fix this until the new API lands." These criteria are rarely documented because they seem obvious to the original author.
3. False Confidence: A well-written AI commit message can create a false sense of security, leading reviewers to assume the change is well-understood when it is not.

Readers encountering these fabricated narratives later may find them nonsensical upon deeper inspection, or worse, they may act on incorrect assumptions, propagating technical debt.

Why Developers Must Write the 'Why'

The solution to hallucinated context is not simply to feed the agent more data. While providing an agent with comprehensive context via chat or integrated tools can improve the accuracy of its output, it does not solve the deeper problem of human comprehension. An agent can write a perfectly structured commit message based on provided prompts, but only the human can verify if the resulting code actually matches that description.

Therefore, developers should write the commit message and description themselves. This practice serves as a final verification layer. If a developer cannot clearly articulate why a change was made, they are likely shipping something they do not fully understand.

"If you cannot explain it, you did not understand it. The commit description again works here as a thinking tool."

This verification process is essential for long-term maintainability. It forces the developer to confront the reality of the code they are committing. It transforms the commit message from a mere log entry into a declaration of responsibility. By writing the message, the developer confirms that they have reviewed the AI-generated code and agree with its purpose and behavior.

Communicating Temporary Decisions and Exit Criteria

One of the most valuable aspects of manual commit writing is the ability to capture temporary decisions and their associated exit criteria. In rapid development cycles, engineers often implement workarounds or interim solutions with the explicit understanding that they will be replaced or refined later.

AI agents struggle to infer these temporal contexts. A workaround might look like a permanent solution in the code structure. However, if a developer writes, "I am doing this until we refactor the authentication module," they provide a clear roadmap for future maintainers.

1. Clarity on Intent: Future readers can decide whether to keep the change or schedule it for removal based on the stated exit condition.
2. Preventing Accumulation of Debt: Without this explicit note, temporary fixes often become permanent, leading to accumulated technical debt.
3. Context Preservation: Written exit criteria preserve institutional knowledge that would otherwise be lost after the immediate crisis is resolved.

By forcing the developer to complete the sentence "I am doing this until we...", the commit message becomes a living document that guides future engineering decisions. It ensures that temporary solutions are treated as such, rather than being mistaken for architectural best practices.

Conclusion

As AI agents take over the bulk of code generation, the developer's role evolves. The value is no longer in typing lines of code, but in understanding, verifying, and contextualizing them. Writing commit messages manually is not a relic of the past; it is a vital practice for the future of software engineering.

It acts as a safeguard against hallucinated reasoning, ensures that developers truly understand the code they ship, and preserves the critical context of temporary decisions. In an age of automated generation, the human capacity to explain the why remains the most important skill in the developer's toolkit.