ADHD Devs: Claude Code Workflows

I couldn’t start coding. Not “couldn’t focus”—literally couldn’t START. The blank editor stared at me. I stared back. Forty-five minutes later, I’d written nothing, felt nothing but guilt, and closed the laptop.

This is the ADHD task initiation wall. It’s not laziness. It’s not motivation. It’s your executive function hitting a physical barrier. Then Claude Code’s intelligent caching and workflow orchestration gave me a system that bypasses the wall entirely. Here’s how ADHD developers use it.

The Problem: Your Brain vs. Your IDE

I’ve shipped code for five years. I understand programming deeply. But my ADHD brain creates four specific friction points that Claude Code solves:

1. Task Initiation Paralysis

The blank screen is paralyzing. Not because I don’t know what to do—I do. It’s that executive function barrier between knowing and starting. Research from the NIH shows ADHD involves significant deficits in task initiation and planning. Your brain literally can’t transition from planning mode to action mode without external structure.

2. Context Switching Cost

The APA has measured this: recovering from a context switch takes an average of 23 minutes. For ADHD developers, it’s longer. Your brain involuntarily context-switches—a Slack message, a random thought, an email notification—and pulling back to what you were building requires rebuilding the entire mental model. Every rebuild is 23+ minutes of dead time.

3. Time Perception Distortion

“I’ll just fix this one thing” becomes a 4-hour rabbit hole. Time blindness is an ADHD hallmark. You can’t feel time passing. You can’t estimate how long tasks take. You ship code on deadline-driven panic, not because you’re lazy, but because your brain can’t perceive duration without external markers.

4. Documentation Fatigue

Writing documentation requires sustained attention on low-novelty tasks. Your ADHD brain treats novelty as the fuel that sustains focus. Repetitive explanation—redefining context, re-explaining decisions, re-documenting the same patterns—burns that fuel fast. It’s not that you don’t want to document. It’s that the task doesn’t sustain your executive function.

Claude Code doesn’t fix ADHD. But it offloads all four of these problems.

Why Claude Code Works for ADHD Brains

Claude Code has three features that directly address ADHD friction points:

Feature 1: Context Caching

Every conversation with Claude ends. The context disappears. Tomorrow, you re-explain everything from scratch. For ADHD developers, this is devastating—you’ve just lost the external structure that carried your task.

Context caching means Claude remembers your project state across sessions without you re-explaining. You close the laptop. You come back. Claude has the context cached. No re-explaining. No rebuilding the mental model. You pick up where you left off.

Feature 2: CLAUDE.md Templates

Instead of managing documentation yourself, you offload it to a template. CLAUDE.md is a single Markdown file in your project that lives at ~/.claude/CLAUDE.md. It captures:

• Project context (what are we building?)
• Rules (what constraints help your brain?)
• Known learnings (what have we discovered?)
• Async checkpoints (where can I restart if interrupted?)

Claude reads this automatically. You don’t have to re-explain. The template does the explaining for you.

Feature 3: Multi-Agent Orchestration

Instead of you decomposing tasks into steps, Claude does it. You describe a goal. Claude breaks it into atomic tasks. You pick ONE task and start there.

This solves initiation paralysis. The barrier isn’t “what do I do?” anymore. It’s “do THIS one thing.” Picking one thing from a list is infinitely easier than deciding what to do from a blank slate.

The 5-Step Workflow

This is the system I use daily. It’s not complicated. It’s sequential.

Step 1: Start with CLAUDE.md, Not Code

Before you write a single line of code, create a CLAUDE.md file in your project root:

# Project: [Your Project Name]

## Context
- What are we building?
- Who are we building it for?
- What's the current state?

## Rules (ADHD-Friendly)
- No multi-step questions in one message
- Always show evidence before claiming completion
- Async checkpoints every 30 minutes of work

## Known Learnings
- [Issue] → [Fix] → [Why it matters]
- [Pattern] → [When it works] → [When it fails]

## Current Checkpoint
- Last task: [what we were doing]
- Next task: [what we're doing now]
- Blocked by: [anything that needs resolution?]

This file is your external executive function. It travels with you across sessions. Claude reads it automatically. You never re-explain again.

Step 2: Define ADHD-Friendly Rules

Not project rules—brain rules. These are the constraints that help YOUR specific brain function:

## Rules for ADHD Developers

1. **One Question Rule**
   - Never ask Claude multiple questions in one message
   - If you have three questions, send three messages
   - Context-switching costs are real

2. **Evidence-First Completion**
   - Don't accept "should work" claims
   - Require actual build output, test results, screenshots
   - Decision paralysis dies when evidence is clear

3. **Async Checkpoint Updates**
   - Every 45 minutes, pause and update CLAUDE.md with current state
   - Document what worked, what blocked, what's next
   - If you get interrupted, you can resume without rebuilding context

4. **Task Atomicity**
   - Break work into tasks completable in 45 minutes or less
   - ADHD brains can hyperfocus on novelty—use it
   - One complete task beats three half-finished ones

5. **No Re-Explaining**
   - If it's in CLAUDE.md, don't explain it again
   - Point Claude to the section instead
   - This saves context and reduces cognitive load

These aren’t universal rules. They’re rules for YOUR brain. Customize them.

Step 3: Let Claude Decompose the Work

Instead of you deciding what to build, describe the outcome:

Goal: Add user authentication to the API

Before: I used to spend 30 minutes breaking this into steps,
getting overwhelmed, and giving up.

After: I tell Claude the goal. Claude breaks it into:
  1. Define auth schema
  2. Create login endpoint
  3. Add JWT validation middleware
  4. Write login tests

I pick task #1 and start there.

This removes initiation paralysis. You’re not deciding “what do I do?” anymore. You’re deciding “which of these four things do I want to do first?” The second decision is 100x easier.

Step 4: Use Caching to Beat Context Switching

Claude Code caches your context across sessions. This means interruptions don’t destroy your workflow:

Session 1 (45 minutes):
  - Read the project context
  - Analyze the existing code
  - Implement the auth schema
  - Update CLAUDE.md checkpoint

[You close the laptop. Interruption happens. Context lost.]

Session 2 (next day):
  - Claude reads CLAUDE.md
  - Claude knows: "Last task was auth schema. Next is JWT validation."
  - You continue immediately
  - No mental rebuild required

For ADHD developers with time perception issues, this is everything. You don’t lose track of the work. Claude carries the context for you.

Step 5: Ship with Evidence Gates

Don’t trust “should work” claims. Require proof:

Before: "I think this works. Deploy it."
Result: 3 bugs in production. Guilt spiral.

After: Three gates before shipping:
  1. Build output: pnpm build → Exit code 0
  2. Type checking: pnpm check → Zero type errors
  3. Test output: pnpm test → All tests pass

Only when all three gates pass do you ship.

For ADHD developers with decision paralysis, evidence removes the guesswork. You don’t have to “believe” it works. You can see it works.

It Works: A Developer’s Story

Maya is a full-stack engineer with ADHD. She’s been coding for five years. Before Claude Code workflows, she’d started twelve projects. Completed zero.

Task initiation paralysis. Context switching made her re-learn the codebase every session. Time blindness meant she’d lose entire afternoons to unplanned deep dives. Documentation felt impossible.

She implemented the 5-step workflow:

Month 1: Set up CLAUDE.md. Define ADHD-friendly rules. Shipped one small feature (user profile display).

Month 2: Got comfortable with evidence gates. Shipped the second feature (profile editing with validation). Noticed: less decision paralysis because the gates made the quality objectively clear.

Month 3: Added async checkpoint updates to CLAUDE.md every 45 minutes. Shipped a third feature—a full API integration—in a single 6-hour focused session, something that would have taken her two weeks of scattered work before.

Her actual quote: “I stopped fighting my brain and started building systems for it. Claude Code carries the executive function load. I carry the engineering.”

Three features in three months. Not because she became “more disciplined.” Because she replaced her broken executive function system with an external one that works.

Start Building Systems, Not Fighting Your Brain

ADHD doesn’t mean you can’t code. It means you need different systems.

Most developers build systems assuming neurotypical executive function. Task management assumes you can initiate easily. Code reviews assume you can re-read code without context-switching recovery. Docs assume you’ll write them for the joy of documentation.

Claude Code workflows assume nothing. They assume you context-switch involuntarily. They assume you’ll forget context without external storage. They assume you’ll initiate better with a list of atomic tasks than a blank editor.

That’s not accommodation. That’s design.

Ready to try it? Start with a simple CLAUDE.md file in your project root. Use the template structure from the “Step 1” section above—context, rules, learnings, and checkpoint updates. Customize it for your brain.

Want to share? Drop your workflow modifications in the comments. ADHD developers solve problems differently—I want to see how you’re adapting these systems.

The cognitive load of project management shouldn’t rest on the neurodivergent brain. Offload it. Cache the context. Define the rules. Ship the evidence. Build the systems.

Your brain is good at engineering. Let Claude Code handle the executive function.