Why Developers Write Better Docs for AI Than for Their Coworkers

There’s an old joke among developers: “Documentation? The code is the documentation.” The same people who used to sigh when a coworker asked “how do I use this function?” are now up at midnight, carefully tuning a file meant for an AI to read. Same fingers, opposite behavior. This strange scene keeps coming up in developer circles lately — and it’s more than a punchline. It quietly exposes the real reason we write docs, and the real reason we don’t.

Let me be upfront: this isn’t a fresh controversy that flared up in the last 30 days. It’s closer to a long-running irony that has always run through engineering culture. So instead of waving comment counts at you, I want to slow down and look at why this actually happens.

CLAUDE.md and the Birth of a New Documentation Culture

Open almost any project built with AI coding tools today and you’ll spot an unfamiliar file. Something named CLAUDE.md, or its cousins like .cursorrules or AGENTS.md. Inside: project structure, coding conventions, gotchas, build steps — all laid out with real care.

Here’s the funny part. In the very same repo, the README.md meant for humans often reads “TODO: write later.” One document is rich. The other is a husk. Same codebase, same author, wildly different effort.

Why? An AI agent reads that file every single time. Write it well and the output improves instantly. Write it lazily and the model spits out nonsense. The feedback is immediate. Docs for human coworkers, by contrast, take weeks or months to pay off — if they ever pay off at all.

It Wasn’t Laziness. There Was Just No Reward

Here’s the first uncomfortable truth. Developers never actually hated documentation. There was just no reward structure behind it.

Think about it. Docs for a coworker offer brutally thin returns. You spend an hour writing something clear, and if they never read it, the hour is gone. If they do read it, you get a thumbs-up emoji. Meanwhile the code keeps changing while the doc stays frozen, so it turns into a liar within a sprint. “Just ping me on Slack” starts to feel like the efficient move.

Docs for an AI work differently. The rule you just wrote shows up in the next response. The five minutes you spent come back as better code on the spot. Suddenly there’s an immediate, unmistakable reward. And humans, in the end, are reward-seeking animals.

The AI Doesn’t Get Annoyed, Ignore You, or Judge You

The second truth stings a little more. Part of why we skip docs for people is the emotional cost.

Leaving a coworker a written note that says “do it this way” is oddly loaded. Too detailed and it reads like nagging. Too sparse and it looks careless. You worry they’ll spot something you don’t know. You worry they’ll think “obviously, I already knew that.” A single doc gets tangled up in the quiet politics of working with other humans.

The AI waives all of it. It doesn’t sulk at being told twice. It doesn’t ignore you. It doesn’t size you up. It just takes the instruction and runs. The most comfortable audience a developer has ever had for putting their thinking into words turns out, ironically, to be a machine.

The Plot Twist: These Docs Are Useful for Humans Too

This is where it gets genuinely interesting. A new hire opens that CLAUDE.md you wrote for the AI. Then they say: “This has everything I would’ve spent a week figuring out.”

To explain anything to an AI, you’re forced to make the context explicit. All the tacit knowledge you’d normally skip with “everyone knows this” has to be spelled out, because the AI can’t read the room. And in doing that, you accidentally produce the friendliest onboarding doc your team has ever had.

In other words, under the cover story of “writing docs for the AI,” we’re finally doing the proper documentation we’d been putting off for years. Whatever the motive, the artifact becomes an asset for the whole team.

The Takeaway

What this irony tells us is simple. Developers were never incapable of documentation. They just lacked a reason to do it. The AI supplied the missing reason — instant reward, zero social friction. So here’s the question I’ll leave you with. If we redirected even half that care toward the human sitting next to us, how much would our collaboration change? Maybe the best documentation is the kind both people and machines can read.