I worried this blog post was going to pivot into a marketing pitch for some product, but no, it just describes the issue where the AI tool that generates your code probably won't document its reasons for the choices it makes. That documentation problem exists in the pre-AI era too, except that the reasons might exist in the heads of your co-workers and could possibly be teased out.

I know nothing about AI code generation (or about AI in general), but I wonder if you could include in your prompt a request that the AI describe the reasons for its choices and actually include those reasons as comments in the code.

The AI can't really describe its reasoning, though. It can only look at its context history and find a justification (which it will then present as reasoning). In my experience asking the model "why did you do that" carries substantial hallucination risk.

I think the issue that majority of agentic developers don't understand their design fully. Those holes, perviously, were have to be closed by a person eventually, and inherently you gain understanding in the process.

This is not the case eny more. I never thought LLMs write bad solutions, but when you let it think for you you loose something important, understanding. And when something brekas, some people consider this being a proof that the llm is the problem. And in a sense it is. But you are also to blame. And that's exactly the issue with this all industry - in order to move faster you don't need to "type" faster. A person bashing his hands on the keyboard randomly at top velocity can get pretty high wpm. In order to move master you need to _think_ faster, be _snappier_ and _sharper_ and most people aren't.

I like how one of my colleagues phrased it in a company meeting. He asked one of the c levels "for llm s to 10x me, I need to let them make all decitions and dictate intentions. By percentage, how much of the code you want me to _know_?"

Isn't one of the common criticisms of AI code that it's a bit too keen to write extensive comments - even when they probably aren't needed?

Perfectly possible IME, it just requires more time. Even if you understand all the (important) parts of your code and validate it, Ai still helps with productivity a lot. It's just not as fast as blindly vibe coding - not at first at least. Agents on their own without checks, and superficial prompts without understanding, result in agents either introducing bugs, or if you have an appropriate test harness, painfully slow, in my experience. It requires skill to use an agent effectively.

But I don't relate to "it probably won't document its reasons"... I spend more time telling it that it has over-documented than under-documented.

It always wants to include the specific thing it is fixing in the API docs for methods it touches. No, this is not the place for a changelog of why this method is implemented the way it is! Describe the interface and the contract, these details are non sequiturs and they are a distraction.

Isn't this what good commit messages are intended to address? If a person has gone so far as to allow an agent to write all their code, they're likely having it commit on their behalf too.

Writing a skill / set of rules around what makes a good commit message would encourage the LLM to record it's reasoning (however much we truly consider it to be "reasoning").

By default, Claude is set to avoid comments. Eventually I got tired of it deleting my own explanatory comments and overrode the behavior with an addition to CLAUDE.md.

I think Claude is just behaving like all those programmers who make a VERY BIG DEAL about how much they HATE HATE HATE comments that might reiterate what the code does so will go to extreme measures to avoid them.

Very few developers do that especially on early / key parts of the codebase.