A feature built with AI in two hours can take three days to explain in review, because the finished code carries no trace of the choices that produced it.
Writing code with AI assistance compresses dozens of small decisions into a single clean output. The alternatives that got tried and dropped, the edge case that forced a guard clause, the abandoned first approach: none of that survives into the pull request. Reviewers see the narrow end of a funnel and are asked to guess the wide end.
The Details:
- Documentation alone does not solve this. It describes what code does, which AI handles well. It cannot explain why this shape was chosen over another, because that answer depends on knowing what was rejected and why, and that record only ever existed inside a working session that is now closed.
- Solo developers feel a muted version of the problem; they carry context in their heads until they return to old code and no longer recognize their own reasoning. Teams get no such grace period, since every handoff crosses the same gap, and onboarding multiplies it into a codebase that reads clean but explains nothing.
- The fix has to be cheap or it will not survive a busy afternoon. Before closing an AI session, write one paragraph naming three rejected options and why they lost, then paste it into the pull request. Reviewers should ask what got ruled out rather than why the chosen path was picked, since the second question invites defense instead of a real trail.
- Culture reinforces the habit more than any template does. When a senior engineer publicly credits a teammate for showing why an approach was skipped, that visible praise does more to spread the practice than a mandated field in a PR form ever will.
Bottom Line: The code is not the deliverable anymore; the code plus the record of what almost got built instead is.
