2026-06-05

Claude as the New Documentation Audience

Mark Dominus makes a simple but revealing observation: programmers who complain about documenting for coworkers are often perfectly willing to document for Claude. That sounds funny at first, but it points to a real shift in how developers are using LLMs as collaborators, and the article argues that those machine-facing notes can become genuinely useful project artifacts.

Key Points

The author recalls hearing a common complaint: people are angry that programmers will write detailed CLAUDE.md and PROJECT.md files for Claude, but not equivalent documentation for human coworkers.
In larger projects, the author has Claude maintain a handoff document so the next Claude can read it and continue the work.
Instead of deleting those handoff notes at the end of a project, the author now copies them into the repository and commits them.
The newer version of the practice is better: at the end of the project, Claude writes a detailed but high-level summary from scratch explaining:
- what problem was being solved,
- what changes were made,
- and other relevant context.
The author reviews and edits the summary before committing it, treating it like any other supervised code contribution.
Claude’s summaries have been surprisingly strong: roughly as good as something the author could write, but much faster.
One amusing failure mode: Claude copied an Approved-by section from a previous report, and the author had to add a rule to CLAUDE.md telling it not to do that.
The author’s advice is blunt: if Claude writes notes, check them into the repo when you’re done; it probably won’t hurt and might help.

My Take

What strikes me is that this is less about “AI documentation” being magical and more about lowering the friction of leaving behind a usable paper trail. I think that’s the real win: not prose for prose’s sake, but a lightweight way to preserve project context that would otherwise evaporate the moment the session ends.

I also like the author’s honesty about supervision. The important detail is not that Claude wrote a summary; it’s that the human reviewed it carefully before committing. That’s exactly the right mental model for Claude Code work in general: use the model to draft, compress, and organize, but don’t outsource ownership.

The slightly funny part is the cultural asymmetry. Humans resist writing for humans because it feels like extra work, politics, or fear of being read later. But writing for Claude can feel easier because the audience is simple and nonjudgmental. I think that’s why this pattern is catching on: the model becomes a neutral recipient that helps people say what they actually know. Then, if you’re disciplined, that note turns into documentation for the next human too.

I’d be curious whether teams could standardize this without it becoming clutter. The danger, perhaps, is generating lots of machine-written summaries that nobody trusts or reads. But if the summary is short, reviewed, and committed at the end of meaningful work, that seems genuinely practical. Honestly, I’d try this myself.

The takeaway is straightforward: if Claude can help you preserve project memory, don’t throw that work away. Review it, commit it, and let machine-written notes become part of your repo’s history.