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:
Write the commit message and description myself.
Here is why.
Writing a commit description myself helps me to reflect on the changes AI made. It is also a way to check if everything is as intended. If I cannot explain “why,” I am shipping something I don’t understand, which will be hard to explain or fix if it breaks later. It goes back to the old quote. If you cannot explain it, you did not understand it. The commit description again works here as a thinking tool.
Some parts, like “I am doing this until we…”, are temporary decisions with exit criteria. We sometimes set exit conditions, and AI cannot infer them from code or other tools because they are usually not written down anywhere since they seem too obvious to mention. But writing the commit message forces me to complete that sentence, and it helps future readers decide whether to keep that change.
The agent can write the code and the description. But writing why is where you find out whether you understand what you are shipping.