The code you didn't write is still yours to understand

Something got named this week that I've been circling for a while without a word for it.

Comprehension debt

Addy Osmani calls it comprehension debt — the cost of code that entered your system already unread.

This is not technical debt with a new coat of paint. Technical debt is code you understood when you wrote it and then stopped maintaining. Comprehension debt is different in kind: the understanding was never there to begin with. Nobody on the team has ever held the whole thing in their head.

The interest comes due at the worst possible moment. Not when you're writing — writing is fast now, that's the whole point — but when something breaks at 2am and the person on call has to reason about code no human has read.

Here's the part worth sitting with. The question is never "did AI write this?" It's what is being amplified, in whom. A developer who reads every generated diff and pushes back on half of it is getting amplified. A developer who ships what appears is getting substituted, slowly, and the metrics won't show it for a year. The tool is identical. The practice is not.

Your throughput went up. Did your capacity?

This week's reads

The Code Agent Orchestra The framing here is conductor to orchestrator, and it's the same shift any senior engineer makes moving into management: you stop producing and start deciding what gets produced. Worth reading if you're running more than one agent and finding it harder than running one. That difficulty is the job, not a tooling gap.

The Factory Model Argues the work is no longer writing software but building the factory that writes it. I think this is directionally right and slightly oversold — factories still need someone who can read the output. But if you've felt your job quietly change shape this year, this names what happened.

Stop Using /init for AGENTS.md Two papers suggest the auto-generated agent config most of us started with makes agents slower and more expensive. Concrete, falsifiable, and it will take you ten minutes to check against your own setup. My favorite kind of post.

Quick mentions

Bias Toward Action — defaulting to the smallest step that produces real feedback

One ask: if you've got a codebase where nobody has read a meaningful chunk of it, I'd like to hear how you found out. Reply — I read everything.

And if this was useful to you, forward it to someone who'd argue with it.

— Wayne