AI code change intent documentation: capture the why before the session dies

A recent thread on r/devops asks a question that will sound familiar to anyone running coding agents: has anyone lost the reasoning behind an AI-generated Terraform change after the session ended? The change works, it merged, and six months later nobody can say why a timeout is 47 seconds or why the pipeline retries exactly three times. The reasoning existed once, in a prompt session, and then the session closed. AI code change intent documentation is the unglamorous fix: write the why down while it still exists, because nothing else will preserve it.

The session is not a record

It is tempting to treat the agent transcript as documentation: everything is in there, after all. But transcripts are the wrong shape for the job. They are long, unordered explorations full of dead ends, they live outside the repo, and they are routinely deleted, truncated, or lost to tool churn. Even when a transcript survives, nobody debugging an incident at 2 a.m. is going to replay four hundred turns to find the one where a constraint was mentioned. As Addy Osmani notes in his essay on agentic code review, the defining problem of reviewing agent-written code is that the author cannot explain itself; the reviewer reconstructs reasoning that was never written down. The cheapest time to write it down is the moment it is still in front of you.

AI code change intent documentation: the four parts

Keep the artifact small enough that it actually gets written. Four sections cover what future readers need:

• What was asked. The task as given to the agent, including constraints that shaped it: compatibility requirements, deadlines, the bug report it answers.
• What the agent chose. The approach in the merged code, and the reason you accepted it. One sentence of judgment: this is the part no tool can generate.
• What was rejected. Alternatives the agent tried or proposed that you turned down, and why. This is the section that saves the next person from re-walking a dead end, or from mistaking a deliberate choice for an oversight.
• What is untested. The honest list: paths you did not exercise, edge cases you are trusting the agent on, behavior you verified only by reading. Reviewers should spend their attention here first.

Where the artifact lives

Durability and proximity decide the home. The PR description carries the four sections for the change as a whole; it is the durable record after the branch is deleted. Commit messages carry per-step reasoning, which works best when the work is split into atomic commits: one decision per commit, one why per message, instead of a single squashed blob labeled with the prompt. And when an agent change settles an architectural question (a new dependency, a schema shape, a service boundary), the why belongs in a decision log or ADR, because PR archaeology is a bad way to learn your own architecture. The common thread: if git and the repo do not carry the reasoning, the reasoning does not exist.

Self-review is the capture moment

The practical question is when this writing happens, and the answer is: during author self-review, before requesting review. Walking your own diff is exactly when the gaps announce themselves: here is a line I cannot explain, here is a file I did not expect the agent to touch, here is the tolerance it loosened without asking. Each of those observations is either a fix or a sentence in the intent doc. Self-review used to be good manners; for agent-written changes it is the only point in the pipeline where a person who still has the context inspects the change. Skip it, and the first human to really read the code is a reviewer with none of the reasoning, or an on-call engineer with even less.

What this buys you

The payoff is not tidiness; it is speed at the two moments that matter. At review time, a reviewer with the four sections reads the diff against a stated intent instead of guessing at one, which is most of what makes agentic code review harder than the classic kind. And at incident time, the question why is it built this way has an answer that does not depend on whoever ran the agent still being on the team, or still remembering. The r/devops thread reads like a warning from that future: infrastructure nobody can explain, merged by a process everyone trusted. Ten minutes of writing at generation time is the entire insurance premium. Pay it while the reasoning is still yours to write down.