Commit Description as a Thinking Tool

The piece argues for treating commit descriptions as an active thinking tool rather than a perfunctory formality. The author describes a pre-AI habit of spending five to ten minutes drafting long commit bodies that explain what changed and, crucially, why. Writing in first person often made reasoning explicit, surfaced implicit exit criteria, and prompted re-reading the code - frequently leading to different or better changes. That reflective writing both consolidated useful information for future readers and served as a forced check on the developer’s own understanding before shipping.

With agentic coding and AI-generated commits, the same surface benefits are at risk: agents can produce plausible messages but lack dispersed, sometimes offline context and can fabricate reasons. Feeding an agent more context reduces invention, but it doesn’t replace the developer’s responsibility to verify that code matches its description. The author’s practice is to write the commit description personally so they must articulate the “why,” confirm the implementation aligns with intent, and document temporary decisions and exit criteria that agents won’t infer. The core claim is direct: if you cannot explain why a change exists, you don’t truly understand it, so writing the why is the test for readiness to ship.