Like many teams, we started using AI coding tools when they became genuinely useful. Our backend is Golang. The promise was simple: generate the boilerplate faster, spend more time on the hard problems. It worked. PRs were moving faster. Code looked clean. Engineers were shipping more. Photo by Compagnons on Unsplash Then a new engineer joined the team. He spent three days trying to understand the code we had written — with AI assistance — six months earlier. The code ran fine. The tests passed. Nobody on the team could explain why we had chosen that particular concurrency configuration, or why the retry logic was structured the way it was. The code was perfect. The reasoning was gone. AI Writes the What This is the part Agile teams learn the hard way. AI tools are excellent at generating syntactically correct, well-structured code. They are not good at capturing intent. When we used an AI assistant to build our queue processing system, it produced solid, idiomatic Golang. What it did not produce: why we chose a priority queue over a single general queue, why we capped worker concurrency at five, why the high-priority jobs had a separate retry policy. Those decisions lived in our heads and in a Slack thread from six months ago. The code encoded our decisions. It did not explain them. Agile had already done the damage We had been moving fast for years. Documentation was always the thing we would clean up later. In a Rails monolith this was manageable — the code itself was expressive, naming was readable, and the team had shared context. Sloppy but survivable. AI-generated code tends toward the generic. It does not know that the 30-second timeout exists because of a specific upstream API limitation. It does not know that we rejected the obvious approach because we had tried it the previous year and it caused a cascade failure. It generates code that looks right and is right — for the requirements it was given. The requirements it was not given live only in someone’s memory. When that memory leaves the team, it is gone. What we changed We landed on a simple rule. Before any PR that includes AI-assisted code is merged, the author adds a short comment block. We call it the “why this exists” block. It is not a line-by-line explanation. It is three things: the constraint we were working within, the alternative we considered, and why we chose this approach over that one. Three sentences. Takes five minutes to write. Saved hours on every code review and onboarding since. It does not need to be a formal system. A comment is enough. The goal is not documentation for its own sake — it is making sure the next engineer who reads the code does not have to reverse-engineer a decision that took the team a day to make. AI is not going to write this for you AI tools will keep getting better at generating code. They will not get better at understanding your business context, your historical mistakes, or the upstream constraint that shaped a specific decision eight months ago. That part is still your job. The engineers who figure this out early will have codebases that stay readable as AI-assisted development becomes the default. The ones who don’t will spend increasing amounts of time debugging perfect code that nobody understands. We found out the hard way. You don’t have to. A message from our Founder Hey, Sunil here. I wanted to take a moment to thank you for reading until the end and for being a part of this community. Did you know that our team run these publications as a volunteer effort to over 3.5m monthly readers? We don’t receive any funding, we do this to support the community. If you want to show some love, please take a moment to follow me on LinkedIn , TikTok , Instagram . You can also subscribe to our weekly newsletter . And before you go, don’t forget to clap and follow the writer️! AI Writes the Code. Nobody Writes the Why. We Found Out the Hard Way. was originally published in Artificial Intelligence in Plain English on Medium, where people are continuing the conversation by highlighting and responding to this story.