As artificial intelligence increasingly generates code and commit messages, a developer has made the case that manually writing commit descriptions remains a valuable practice for understanding and verifying AI-generated changes.
According to the post, the author historically spent five to ten minutes writing detailed commit descriptions for major code changes, including explaining not just what changed but why. This practice served multiple purposes: ensuring readers had all necessary information, clarifying decision-making, and helping the developer reflect on their own work.
Now in the era of agentic coding, where AI systems generate both code and commit messages, the author identifies a significant problem: AI agents may not have full context about a change’s reasoning, which is often spread across various communication and project management tools. When this context is missing, agents can generate plausible-sounding but inaccurate reasoning for why a change was made. “When the AI doesn’t know the ‘why’ part, it comes up with its own reasoning. I find that dangerous,” the author states.
While providing agents with full context through chat or tools can help address fabricated reasoning, the author argues this doesn’t solve a deeper issue: only the developer can verify whether the code actually does what the description claims.
The author’s solution is straightforward: write commit descriptions manually, even when AI generates the code. This practice serves as a verification step—if a developer cannot explain why a change was made, they may be shipping code they don’t fully understand, making future fixes difficult. The author references the principle that inability to explain something indicates a lack of understanding.
The post also highlights a specific case where AI falls short: temporary decisions with exit criteria. Developers often make code changes intended to last only until certain conditions are met, but these exit conditions are rarely documented because they seem obvious. Writing a commit message forces developers to articulate these criteria, helping future readers determine whether the change should be kept or removed.
Ultimately, the author argues that while AI can handle code and commit description generation, the reasoning behind changes remains where developers must engage critically. Writing the commit description yourself becomes a thinking tool that confirms understanding of what is actually being shipped.
Key facts
- Writing commit descriptions manually helps developers verify AI-generated code and clarify reasoning
- AI agents often fabricate reasoning when they lack full context about why changes were made
- Manually written commit messages force developers to articulate temporary decisions and exit criteria that are rarely documented
- The practice serves as a check for developer understanding—inability to explain a change suggests insufficient comprehension