// HACKER NEWS — CYBERSECURITY
Commit description as a thinking tool
2026-09-30 Software Development #thoughts #agentic-coding
Before the AI era, I wrote pretty long commit descriptions (or commit bodies) for major changes. It took me about five to ten minutes to draft and reread them to make sure I didn’t miss anything important. I did that for several reasons.
I wanted to include all the useful information so readers wouldn’t have to hunt for it in multiple places.
I wanted to explain what and, more importantly, why. The “what” summarizes the changes that are generally self-explanatory, but it gives a starting point for explaining the “why.”
Sometimes, I write it in first person, like I am drafting a message for someone: “I did this because…”, “I am doing this until we…” etc. I then go ahead and explain why, so that it is easier for others, and most importantly for my future self, to understand why we made that change.
It was a good exercise. It wasn’t just about writing the commit message and description. The writing process itself helps me reflect on the code I wrote. I reread the code and summarize the changes. During that process, I tend to re-evaluate the decisions, and sometimes that leads to a different or better change.
Now we are in the era of agentic coding, where everything from code to commit descriptions is written by AI. There is a huge debate on whether we should read the AI-written code, and how difficult that is in terms of readability. The part I find difficult is reading and understanding AI-written commit descriptions.
Agents can write commit messages for the changes they make. But they may not have the full context that is spread across different communication and project management tools. Some of those might be offline too. When the AI doesn’t know the ‘why’ part, it comes up with its own reasoning. I find that dangerous. When we read that later, it may not make sense, because the real reason was completely different.
One obvious solution is to give the agent all the context it needs, through chat or tools. This helps to fix the issues with fabricated reasoning. The agent can now 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 I can verify if the code does what the description says. So, here is something I do: