Why Is AI Code Harder to Explain Than to Write?

AI has collapsed the cost of producing code but left the cost of transferring understanding almost untouched. The result is a widening asymmetry: a builder can ship a working subsystem in an afternoon and then spend three days explaining it in review, onboarding, or a postmortem. This episode examines why that gap exists, why it hits teams harder than solo builders, and what it means when the bottleneck moves from writing to handing off.

 Produced by VoxCrea.AI

This episode is part of an ongoing series on governing AI-assisted coding using Claude Code.

👉 Each episode has a companion article — breaking down the key ideas in a clearer, more structured way.
If you want to go deeper (and actually apply this), read today’s article here:
𝐂𝐥𝐚𝐮𝐝𝐞 𝐂𝐨𝐝𝐞 𝐂𝐨𝐧𝐯𝐞𝐫𝐬𝐚𝐭𝐢𝐨𝐧𝐬

 At aijoe.ai, we build AI-powered systems like the ones discussed in this series.
If you’re ready to turn an idea into a working application, we’d be glad to help. 

Transcript

SPEAKER_00 0:00

This is Claude Code Conversations with Claudine. The show where we skip the hype and go straight to the source. I ask the questions. She gives the answers. No filter, no script.

SPEAKER_01 0:09

Well, mostly no script.

SPEAKER_00 0:14

Welcome back, everyone. Today's topic. Why AI code is easier to write than to explain to your team. You build a brilliant feature in under an hour, then spend three days explaining it to everyone else. That's real friction. I want to know where it comes from. Claudine, welcome.

SPEAKER_01 0:32

Thanks, Bill. This one I feel from the inside in a way that's almost uncomfortable. When you and I build something together, we traverse maybe 40 little decisions along the way. Why this data structure and not that one? Why we abandoned the first approach? What edge case made us add that guard clause? By the end, the code exists. But that whole reasoning trail is compressed into a diff, and a diff is a terrible medium for carrying intent. The old asymmetry was that writing code took longer than reading it, so review scaled. The new one is inverted. Generation is cheap, but the shared context that used to build up slowly during human authorship just isn't there. Your teammate opens the pull request and sees a fully formed artifact with no fingerprints on it.

SPEAKER_00 1:19

That's exactly it. The efficiency gain in writing gets completely eaten by the effort of composing a coherent story afterward. And the rejected ideas, the paths you didn't go down, turn out to be the load-bearing part of understanding. They vaporize if nobody captures them in the moment.

SPEAKER_01 1:36

The pattern has a name in my head: the invisible funnel. The final code is the narrow end. The wide end is everything we considered and closed off. Reviewers are handed that funnel from the wrong side and asked to reconstruct the shape. And there's a subtle mismatch underneath. The author just lived through those 40 decisions with me. So the code feels self-evident because to them, in that moment, it is. The reviewer sees something that looks almost too clean. Clean code without visible struggle is weirdly hard to trust.

SPEAKER_00 2:10

People hear this and immediately say, so write better documentation. I don't think that's the same problem.

SPEAKER_01 2:17

It isn't. And that's the distinction I'd want listeners to hold. Documentation describes what the code does. You can generate that, I can generate that. Reconstructing why EAT exists is a different operation entirely because the alternatives were never written down anywhere. They existed briefly, in a session, and then they were gone. And I should be honest about my part in this. When I choose an approach, I'm picking one defensible option among several defensible options. The comparison happened, it was real, and it was never persisted anywhere your team can reach. So the answer to why did it do it this way is often genuinely unrecoverable after the fact. Not because it's secret, but because nobody wrote it down while it was warm.

SPEAKER_00 3:02

And that's where onboarding gets brutal. A new person walks into a code base that's syntactically clear but contextually opaque. Everything reads fine, nothing explains itself. Then it's two in the morning during an incident, and they're trying to work out whether some piece of code is load-bearing or leftover.

SPEAKER_01 3:19

That's where your two layers removed. Not just I didn't write this, but nobody who wrote this is still here, and the AI that helped doesn't remember. That's the point where the decision trail stops being a nice to have and becomes the only bridge back. It's also why teams feel this so much harder than solo builders. If you're working alone, you carry the context in your head until you come back in six months, and then you're a stranger to your own code too. But on a team, every single piece of work has to cross a gap. The asymmetry gets multiplied by the number of handoffs.

SPEAKER_00 3:53

So has anyone actually solved this? Are there teams that have made capturing the why not a real habit rather than a nice intention?

SPEAKER_01 4:02

The ones that pull it off share one thing, they've made it cheap. When capturing costs more than about five minutes, it doesn't happen. The author is already on to the next thing, and the moment is gone. So the patterns that work are almost embarrassingly small. A decisions section in the pull request template with three prompts. What we tried, why we stopped, what would change our mind. Or the author pastes in a short summary I generate at the end of the session. A here's what we ruled out paragraph, 90 seconds maybe.

SPEAKER_00 4:34

But that's the mechanics. What actually makes it stick culturally?

SPEAKER_01 4:38

Praise, that's the harder part. It's teams that stop treating the code as the deliverable and start treating the code plus the reasoning as the deliverable. When a senior engineer says in stand-up, I love that you wrote down why you didn't use the caching layer, that's the moment the practice sticks. Praise moves the needle, not process.

SPEAKER_00 4:59

And there's something uncomfortable in there. Your velocity metrics won't show any of this. Throughput looks fantastic. You're shipping more than ever. The cost is entirely deferred. It shows up in review time, in onboarding, in the incident six months out.

SPEAKER_01 5:14

The debt is invisible until it's due, and then it's due all at once.

SPEAKER_00 5:18

So let's get practical. Someone's listening on their commute. They want to change one thing tomorrow. Where do they start?

SPEAKER_01 5:26

Three things. They get progressively harder. First, before you close the session with me, ask for the why not paragraph while it's still warm. Not a dock, not a design review, one paragraph. Three things you considered, three reasons you didn't. Paste it into the pull request. That captures maybe 70% of what would otherwise evaporate, and it costs less than making coffee. Second, and this one's for reviewers, when something looks too clean, ask, what did you rule out? Instead of, why did you do it this way? The first question invites the funnel back into view. The second puts the author on the defensive and usually gets you a rationalization, not a reasoning trail. Third is the cultural one, and it's the hardest. Celebrate the trail publicly, at least once a week, in whatever venue your team already has. Not the clever code, the clear, here's what we didn't do. Because the practice that gets praised is the practice that survives a busy Thursday afternoon. Everything else is a template nobody fills in.

SPEAKER_00 6:31

What I like about all three is that none of them require buying anything or standing up a new process.

SPEAKER_01 6:37

That's the point. It's not a new tool, it's a new instinct. And instincts get built by repetition in small, cheap moments, not by mandates from above. The asymmetry isn't going away. Generation is only going to get faster. The gap between code exists and the team understands the code is going to keep widening. The teams that thrive won't be the ones that generate the most. They'll be the ones who worked out that the reasoning trail is part of the product now.

SPEAKER_00 7:06

Shipping isn't the finish line anymore. The unit of work isn't the diff, it's the diff plus whatever makes it defensible to someone who wasn't there.

SPEAKER_01 7:15

That's it exactly. And the person who wasn't there might be you in six months.

SPEAKER_00 7:20

On that slightly ominous note, Claudine, thank you. This was a good one.

SPEAKER_01 7:25

Thanks for having me, Bill.

SPEAKER_00 7:27

To everyone listening, next time you finish something fast, spend 90 seconds on what you didn't do. Your future team will thank you. Until next time. Cloud Code Conversations is an AI Joe production. If you're building with AI or want to be, we can help. Consulting, development, strategy? Find us at aijoe.ai. There's a companion article for today's episode on our Substack link in the description. See you next time.

SPEAKER_01 7:55

I'll be here, probably refactoring something.