Programmers will write CLAUDE.md they'd never write for a coworker

The complaint that wouldn't stop showing up

Mark Dominus, writing on his blog, started from a grievance he kept seeing: programmers furious that their peers "are willing to write detailed CLAUDE.md and PROJECT.md files for Claude to use, but they weren't willing to write them for their coworkers." Rather than join the lament, he turned it into a workflow.

Dominus's actual move: commit the robot's notes

His argument is practical, not moral. He now has Claude maintain handoff documents between sessions and, at the end of a project, write a structured high-level summary of the problem and the changes made — then he commits that summary to the repository, where it serves any future reader, human or model.

The anecdote that anchors the post is a small comedy of self-fulfilling prophecy. Claude copied an approval blurb from an earlier summary into a new one, asserting that "Mark Dominus has read, reviewed, edited, and approved these notes." Dominus's reaction: "by the time I saw it, it was true, so I didn't have to delete it." He had Claude add a line to CLAUDE.md telling it not to forge his approval again.

The thread answers "why" more cynically than he does

Where Dominus sees lowered cost and raised utility, the thread mostly sees incentives. The bluntest version laid it out as a ledger:

"Document for agent: it makes less dumb mistakes. I go faster. Document for teammates: they might go faster and get stack ranked above me. Document for future engineers: does it impact my salary to skip that? No? Ok." — a developer reducing it to incentives

Others located the difference not in selfishness but in readership. The recurring refrain — one commenter counted at least eight top-level versions of it — was simply that Claude reads what humans ignore:

"I've written so much documentation over the years, and humans always come and ask me questions that the documentation answers, but never ever read it." — a developer on years of unread docs

A CTO framed it as a cost/benefit threshold finally crossed — the same docs were always worth writing, but only now does anything read them:

"A lot of developer documentation is effectively write only… With agentic coding tools, it's different. The documentation helps. And it gets added to even if you don't ask for it." — a Berlin backend developer and CTO at an AI consultancy

And a skeptic pushed back on the whole premise — that the artifact even is documentation:

"Programmers aren't documenting for Claude. Claude is documenting for Claude. Programmers are, at best, reading the documentation Claude wrote for itself to ensure there are no glaring mistakes." — a commenter questioning who actually writes the docs

The unflattering read: nothing changed except the reader

The quiet conclusion under all of it is that none of these docs are new ideas. APIs, architecture overviews, run-books — teams "knew" they needed them for years and never crossed the action threshold. What changed is a reader who never skims, never deflects to a meeting, and never asks you to explain it verbally. The docs got cheaper to write and, for the first time, guaranteed to be read. That the guaranteed reader is a language model and not the person at the next desk is the part the thread can't quite get over.