Mark Dominus has a confession that should make every senior dev wince: programmers are perfectly happy to write detailed CLAUDE.md and PROJECT.md files for AI assistants, but they won't lift a finger to document things for their human coworkers. It's a complaint he's seen repeatedly on Hacker News, and one that's clearly been rattling around his head for a while.

The Handoff Document Trick

What Dominus figured out is that Claude (presumably Claude Code or similar) can maintain a running handoff document between sessions—essentially a living record of what was planned, what's been done, and other pertinent project state. When he wraps up one session, the next Claude reads this file to get context. Then he has the new instance update it for the next iteration. It's a clever use of AI as institutional memory, but Dominus admits he was making one critical mistake: deleting these documents at the end of each project.

Stop Throwing Away Your AI's Notes

The breakthrough came when Dominus realized these handoff docs had value beyond just passing context between sessions. He started copying them into repositories and committing them. Someone in the future, wondering what was going on with a particular feature or refactor, could stumble across these notes with git grep and actually learn something useful. Revolutionary concept, I know—but apparently not obvious to everyone.

The Project Summary Workflow

But Dominus didn't stop there. Now at project end, he asks Claude to write a detailed but high-level explanation from scratch: what problem they were solving, what changes were made, the overall architecture decisions. Not just raw running notes, but an actual structured overview that could stand on its own. He reviews it carefully before committing—his signature's on the line, after all—but here's the kicker: Claude's explanations haven't required much editing at all.

Quality That Holds Up

Dominus says his most recent project summary was around as good as what he could have written himself, maybe slightly worse in some areas, maybe slightly better in others. The difference? It took ten seconds to generate instead of an hour of his own time, and reviewing it didn't take anything like the same mental effort as writing from scratch. One bug he did catch: Claude had copied a previous report's 'Approved-by' section verbatim because that older document served as its template. Dominus had to update CLAUDE.md with a note preventing this in future sessions—a minor oversight, easily fixed.

Key Takeaways

  • Don't throw away AI-generated handoff documents—they're valuable git history
  • Ask your AI to write project summaries from scratch at the end of engagements
  • Review everything before committing, but expect minimal edits if you've been clear throughout
  • Use CLAUDE.md to catch recurring issues like template copying

The Bottom Line

Let's be real: developers have always been bad at documentation. This isn't new. What's new is that we finally have a tool that makes the cost near-zero. If your pride won't let you use AI-generated docs, that's a you problem—don't pretend it's some righteous stance against 'AI slop' when you're just being lazy.