The unwritten checkpoint. The checkpoint only works if you write it before you close. The times I closed mid-thought and skipped it, the next session opened cold, exactly the problem the file was supposed to solve. I eventually added a hook that nudges me to update the checkpoint before the session ends, because relying on ADHD memory to maintain the ADHD memory aid is, predictably, a bad plan.
How Do You Start?
Do not engineer the perfect file. Open the project, create CLAUDE.md at the root, and write four headers: Stack, Voice, Gotchas, Current checkpoint. Fill in what you know right now. Leave the rest blank. The file gets better every time Claude asks you something you wish it already knew, because that question is the exact thing you should write down.
Your working memory is not a character flaw to push through. It is a constraint to design around. CLAUDE.md is the cheapest way I know to design around it.
Frequently Asked Questions
What is CLAUDE.md and where does it live?
It is a plain Markdown file Claude Code reads automatically at the start of every session. Project rules go in ./CLAUDE.md at the project root; global rules go in ~/.claude/CLAUDE.md. You never have to tell Claude to read it, it just does, every time.
How is it different from explaining context in chat?
Chat context dies when the session ends. CLAUDE.md persists across sessions. For an ADHD brain that loses the mental model across interruptions, that persistence is the entire value: the file holds your conventions so your working memory does not have to.
Will CLAUDE.md fix my ADHD?
No. It externalizes one slice of executive function, working memory, so the cost of switching back into a project drops from minutes to seconds. It is a prosthetic, not a cure.
How long should it be?
Short enough that you would actually read it, long enough that Claude stops asking you things you already decided. Mine run 40 to 120 lines per project. Prune it when it drifts out of date, because stale context is worse than none.
If CLAUDE.md is the working-memory layer, the next layer is the executive-function gaps it does not cover. I wrote about the specific Claude Code skills every ADHD developer needs for that, and the bigger clinical picture in how I use AI as an executive function prosthetic.
Originally published on chudi.dev