Developers Write Better Docs for AI Than for Coworkers. One Fix: Commit Them.

Here's a pattern anyone using Claude Code or Cursor has probably noticed: developers who haven't written a README in years will spend 20 minutes crafting a detailed CLAUDE.md file so the AI understands their codebase.

Mark Dominus, a veteran programmer, called this out in a recent blog post. The same people who push back on writing onboarding docs, architecture notes, or even inline comments will happily produce structured project context files for an AI assistant. The inconsistency is almost funny until you realize how much institutional knowledge stays locked in people's heads because "nobody reads the docs anyway."

The Accidental Documentation Pipeline

Dominus's fix is pragmatic rather than philosophical. Instead of shaming anyone into writing better docs, he treats Claude's own output as documentation:

1. He keeps running handoff documents that Claude reads at the start of each session to pick up where it left off
2. When a project wraps up, he asks Claude to write a comprehensive summary of what was built, why, and how
3. He reviews and edits the summary, then commits it to the repo

The results, he says, are surprisingly close to what he'd write himself. The difference is time: Claude produces a draft in seconds versus the hour it would take him manually. Review typically needs only minor edits, though he flags one case where Claude copy-pasted an approval section from a previous document without thinking.

His rule is clear: "It's my signature on the commit, and my bank account receiving the paycheck, so nothing goes into the repository that I haven't read carefully and understood."

A Workaround for a Human Problem

This is less about AI and more about incentives. Programmers have always known documentation matters. They just don't do it because the payoff is delayed and invisible. Writing for Claude feels different because the feedback loop is immediate: better context in, better code out. You see the return on investment in the same session.

Dominus is essentially hijacking that motivation. If people will document for Claude, let Claude turn around and produce documentation for humans. The AI becomes a laundering service for knowledge that would otherwise evaporate when someone switches projects or leaves the company.

Two takeaways worth stealing:

• Commit Claude's session notes. Even informal handoff docs are better than nothing. Future you (or future teammates) will benefit from knowing what decisions were made and why.
• Ask for a project summary before closing out work. It takes five seconds to prompt and five minutes to review. That's a fraction of the cost of writing it from scratch.

The approach won't replace proper architectural documentation on large projects. But for the vast majority of codebases where the alternative is zero documentation, having Claude ghostwrite it and a human sign off is a net win.