# 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.

Source: [chudi.dev/blog/adhd-developers-guide-claude-md](https://chudi.dev/blog/adhd-developers-guide-claude-md),
[chudi.dev/blog/claude-code-adhd-workflows](https://chudi.dev/blog/claude-code-adhd-workflows), and
[chudi.dev/blog/claude-code-skills-adhd-developers](https://chudi.dev/blog/claude-code-skills-adhd-developers).

---

```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).