AI Can Explain What Your Code Does. It Can't Explain Why.

One thing I've noticed while working with AI-assisted development:

AI has become very good at explaining what code does. Point a modern model at an unfamiliar function and it will walk you through the logic, name the patterns, flag the edge cases, and produce a summary better than most human-written comments. Reading code — genuinely one of the hardest parts of this job — has never had a better assistant.

But ask it a different kind of question and the picture changes. AI usually can't tell you:

• ▸Why this pattern was chosen over the obvious alternative
• ▸Why another solution was tried and rejected
• ▸Why the business needed this behavior in the first place
• ▸What trade-offs were accepted, and what was knowingly sacrificed

It can't tell you because that information was never in the code. It can guess — fluently, plausibly, sometimes correctly. But a plausible guess about intent is more dangerous than an honest "I don't know," because it reads exactly like an answer, and nobody fact-checks an explanation that sounds confident and costs nothing to accept.

Software is a collection of decisions

Here's the mental model this pushed me toward: software isn't just code. It's a collection of decisions, and the code is merely the residue those decisions leave behind.

Why is there a caching layer here but not there? A decision — probably made after an incident. Why does this service tolerate duplicate events? A decision, born from a hard lesson about network retries. Why is this obvious refactor not done? A decision, made deliberately, for a reason that was compelling at the time and is invisible now.

The code tells you what was decided. It is structurally incapable of telling you why. And "why" is where all the value lives when you're deciding whether to change something.

The asymmetry that AI makes worse

This gap always existed — developers have been archaeology-ing through legacy code forever. But AI-assisted development widens it in a specific way.

When a human writes code by hand, the reasoning at least passes through a human mind. Some of it leaks into commit messages, PR descriptions, code review threads. Colleagues absorb fragments. The knowledge is fragile, but it exists somewhere.

When AI generates the implementation from a prompt, even that thin trail disappears. The developer decided what to ask for; the model decided how; and the reasoning behind both lives in a chat transcript that gets discarded the moment the tab closes. We're producing more code than ever with less preserved intent per line than ever. More decisions are being made — and fewer are being recorded.

ADRs are aging in reverse

This is why I think Architecture Decision Records — and project documentation in general — will become more valuable in the coming years, not less. Most documentation gets less useful as AI gets better. API references, how-to guides, code walkthroughs: AI regenerates those from source on demand, better and fresher than the static version. Documentation that describes what is dying, and deservedly.

Documentation that describes why is the opposite. It cannot be regenerated, because its source material — the meeting, the outage, the constraint, the rejected prototype — no longer exists anywhere else. An ADR is the only artifact in your repository that AI fundamentally cannot recreate. That makes it the scarcest resource in the codebase.

And ADRs are cheap. Mine follow a boring template: context, decision, alternatives considered, consequences. Ten sentences, written in the twenty minutes after the decision while the reasoning is still warm. The discipline isn't in the writing — it's in noticing that a decision worth recording just happened.

ADRs aren't the only vessel, either. A commit message that says why instead of restating the diff. A PR description that names the alternative you rejected. A comment on the one genuinely strange line, explaining what breaks without it. None of these take real time; all of them survive in the repository, which is the only place future readers — human or AI — will actually look. The format matters far less than the habit: when you make a decision, leave a trace where the code lives.

Intent is also what makes AI useful

There's a practical bonus beyond protecting future maintainers. Recorded intent makes your AI tools better today. A model with access to your ADRs stops suggesting the refactor you deliberately rejected last year. It stops "simplifying" the code whose complexity is load-bearing. It starts generating solutions consistent with your actual constraints instead of generic best practices.

Intent documentation isn't just an archive. It's context — and context is the entire game in AI-assisted development.

The division of labor is becoming clear

So this is where I've landed on how the work splits:

AI generates implementations. It does this brilliantly, tirelessly, and increasingly better than we do.

Humans preserve intent. We're the only ones in the loop who know why anything happened — and we're the only ones who can write it down.

The teams that thrive won't just be the ones that generate code fastest. They'll be the ones that can still answer "why is it like this?" five years from now — because someone, at every important fork in the road, spent twenty minutes writing down the answer while it was still true.

Code is becoming abundant. Reasons are becoming scarce. Invest accordingly.