Free config, no paywall
The CLAUDE.md config for ADHD developers
Stack, voice, ADHD-friendly rules, gotchas, and a checkpoint block that ends the “what was I doing?” reset every session. Copy it, download it, or read it below.
# CLAUDE.md for ADHD developers Drop this at the root of any project as `CLAUDE.md`. Claude Code reads it automatically at the start of every session, so you never re-explain the same context twice. Fill in the bracketed parts, delete what does not apply, keep the rest. Drawn from two posts: [chudi.dev/blog/claude-code-skills-adhd-developers](https://chudi.dev/blog/claude-code-skills-adhd-developers) and [chudi.dev/blog/claude-adhd-executive-function-mode](https://chudi.dev/blog/claude-adhd-executive-function-mode). --- ```markdown # Project: [Your Project Name] ## Stack (do not re-ask) - [Framework/language]. [State management approach]. - [Styling approach]. Never hardcode what a token/variable already covers. - Content/data lives in [location]. [Any required fields]. ## Voice (apply to all writing) - First person, conversational, backed by real numbers where possible. - Lead with the failure, then the fix. No marketing tone. ## Rules (ADHD-friendly) - One question at a time. If you have three questions, ask the first and wait. - Always show evidence before claiming something is done. No "should work." - Break vague goals into 3-5 atomic tasks and let me pick one. Never hand me a blank slate. - Async checkpoints every 30 minutes of work: what changed, what's next. ## Gotchas (learned the hard way) - [Thing that bit you once] -> [the fix] -> [why it matters] - [Pattern] -> [when it works] -> [when it fails] ## Current checkpoint - Last task: [what you were doing] - Next task: [what you're doing now] - Blocked by: [anything that needs resolution, or "nothing"] ``` --- ## Why each section exists **Stack** stops you from re-explaining your own tech choices every session. Write it once, Claude never asks again. **Voice** externalizes tone so output sounds like you without a paragraph of instructions every time. **Rules** are brain rules, not project rules. The "one question at a time" rule specifically prevents the context-switch grenade of a wall of unrelated questions: answering A/B, then C/D, then E costs a full working-memory reload each time. **Gotchas** is the landmine list. Writing a mistake down once means you stop re-discovering it. **Current checkpoint** is the one that matters most. Before you had it, every session opened with a flailing minute or two of "okay, where was I." With it, Claude tells you what you were doing and what's next, because it read the checkpoint before you said a word. Update this before you close the laptop, not after you reopen it: the checkpoint only works if it is written before the gap, not reconstructed after. ## The two failure modes to watch for 1. **Stale context is worse than no context.** If you refactor 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. 2. **The unwritten checkpoint.** Relying on an ADHD brain to remember to update the memory aid, without any external nudge, is a bad plan. If your tooling supports session-end hooks, use one to nudge the checkpoint update before you close out. ## What this does not do It does not fix executive function. It externalizes one piece of it (working memory) so the cost of a context switch drops from minutes to seconds. It is a prosthetic, not a cure. ## Optional next layer: named skills for specific gaps Once the base file is working, the next lever is naming a slash-command skill for one recurring executive-function gap instead of trying to fix all of them at once: - **Task initiation paralysis** -> a skill that sorts today's work by available energy (wired / foggy / depleted), not by priority. - **Discounting your own progress** -> a skill that reflects back what actually shipped, grounded in commits and closed tasks, not vibes. - **Context-switch recovery** -> a skill that reconstructs "what was I doing" from the last session before you write a line. - **Time blindness** -> a skill that sets a real-time checkpoint and interrupts at the interval, instead of relying on an internal clock that does not fire. Pick the one gap that costs you the most this week and build or invoke a skill for that one. Full detail: [chudi.dev/blog/claude-code-skills-adhd-developers](https://chudi.dev/blog/claude-code-skills-adhd-developers).
Drawn from the posts on how this file works and what it is replacing: