The ADHD Developer's Guide to CLAUDE.md

I reopened a file I had already fixed that morning. Not metaphorically. I literally re-fixed a bug I had closed four hours earlier, because between the fix and the reopen, my brain had quietly deleted the entire afternoon. That is the ADHD tax most productivity advice never names: it is not that you cannot focus, it is that the working model of what you were doing does not survive the gap between sessions.

CLAUDE.md is the cheapest fix I have found for that specific failure. This is the companion to my Claude Code ADHD workflow; that post is the full system, this one zooms all the way in on the single file doing most of the work.

What Is CLAUDE.md, Actually?

CLAUDE.md is a Markdown file that Claude Code reads automatically at the start of every session. You do not paste it. You do not remind Claude it exists. It just gets read, every time, before the first line of work.

There are two places it lives:

• ./CLAUDE.md at a project root holds rules for that project: the tech stack, the conventions, the gotchas.
• ~/.claude/CLAUDE.md holds your global rules: things true across everything you build (your voice, your defaults, the things you never want re-litigated).

For a neurotypical developer this is a convenience. For an ADHD developer it is a prosthetic. The difference is what the file is replacing.

Why CLAUDE.md Is External Working Memory for ADHD Brains

Working memory is the mental scratchpad that holds “what I am doing right now and the three things I just decided about it.” ADHD shrinks that scratchpad and makes it leaky. Every interruption, a Slack ping, a stray thought, a context-switch to email, knocks items off it. When you return, the scratchpad is blank and you rebuild it from scratch.

The American Psychological Association puts the rebuild cost at roughly 23 minutes per context switch for a typical brain. For an ADHD brain that involuntarily switches more often and rebuilds slower, the real cost is higher and it compounds. Ten switches a day is not ten minutes lost, it is most of a morning.

CLAUDE.md moves the scratchpad out of your head and into a file. The conventions you would otherwise have to remember, hold, and re-explain now live somewhere that does not leak:

• It remembers your tech stack, so you never re-explain “we use SvelteKit, not Next.”
• It remembers your conventions, so you stop re-deciding the same naming question.
• It remembers your voice, so output comes back sounding like you without a paragraph of instructions.
• It remembers the current task, so reopening the project does not start from “wait, what was I building?”

You are not asking Claude to remember for you. You are writing down what you would otherwise have to hold, once, so that the cost of dropping it goes to zero.

What This Looks Like in Practice

Here is a real, trimmed version of a project CLAUDE.md from my setup. Nothing exotic, that is the point. It is boring, and boring is what survives.

# Project: chudi.dev blog

## Stack (do not re-ask)
- SvelteKit + Svelte 5 runes ONLY ($state, $props, $derived). No legacy `let`/`$:`.
- Tailwind v4 + CSS custom properties in src/app.css. Never hardcode hex in components.
- Content: Markdown in content/posts/. Frontmatter required: title, date, description, tags.

## Voice (apply to all writing)
- First person, conversational, backed by real numbers.
- NEVER use em-dashes. Use commas, periods, parentheses.
- Lead with the failure, then the fix. No marketing tone.

## Gotchas (learned the hard way)
- Never use the $lib alias in any file reachable from a prebuild script. tsx
  on Vercel will not resolve it. Use relative imports. (Cost me a 3-hour outage.)
- Reading time is auto-calculated. Do not hardcode it.

## Current checkpoint
- Last task: shipped citability CTA on 3 top-traffic posts.
- Next task: write the 3-post ADHD cluster around claude-code-adhd-workflows.
- Blocked by: nothing.

The four sections map directly onto the four things my working memory cannot be trusted to hold: the stack, the voice, the landmines, and the bookmark.

The Current checkpoint block is the one that matters most for ADHD. Before I had it, every session opened with a flailing minute or two of “okay where was I.” Now the first thing Claude tells me is what I was doing and what is next, because it read the checkpoint before I said a word. The flail is gone.

The Global File Does the Re-Decided Stuff

The project file handles per-project facts. The global ~/.claude/CLAUDE.md handles the things I was tired of re-deciding everywhere:

## Defaults (do not ask, just do)
- Verify before claiming done. Show the build output, do not say "should work."
- Break vague goals into 3-5 atomic tasks and let me pick one. Never hand me a blank slate.
- One question at a time. If you have three, ask the first and wait.

That last rule is pure ADHD accommodation. A wall of “do you want A or B, and also C or D, and what about E” is a context-switch grenade. “Ask the first, wait” keeps me in one decision at a time.

How Does CLAUDE.md Compare Before and After?

I tracked my own sessions loosely for two weeks before writing a real CLAUDE.md and two weeks after. This is self-reported and n-of-one, so read it as a direction, not a benchmark. But the direction was not subtle.

Signal	Before CLAUDE.md	After CLAUDE.md
Time to first useful action after reopening a project	5 to 15 minutes of “where was I”	Under 1 minute
Re-explaining stack/conventions per session	Almost every session	Effectively never
Re-doing work I had already finished	A few times a week	Rare
Sessions that ended without me knowing what was next	Most of them	Almost none (the checkpoint forces it)

The biggest win is not on that table because it is hard to measure: the dread went down. Reopening a half-built project used to carry a little spike of “ugh, I have to reload all of this.” When the file reloads it for me, that spike mostly disappears, and the lowered friction is what actually gets me back into the chair.

What Breaks This System

CLAUDE.md is not free and it is not foolproof. Two failure modes, both real, both mine.

Stale context is worse than no context. I once let a project’s CLAUDE.md describe an architecture I had refactored away three weeks earlier. Claude reasoned confidently from a model that no longer matched the code, and I almost shipped it. The fix is discipline: when you change something structural, update the file in the same breath. An out-of-date CLAUDE.md does not just fail to help, it actively lies to you with full confidence.

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.