ADHD-Optimized Technical Workflows and Development Environments

Core Principle

The best ADHD workflow is not a neurotypical workflow with accommodations bolted on. It is a workflow designed from the ground up to externalize executive function, minimize working memory load, and convert sustained attention tasks into rapid feedback loops.

---

1. Programming Paradigms and ADHD Fit

Working Memory as the Bottleneck

• ADHD participants scored highest in working memory difficulties vs. ASD and neurotypical developers (2024 study)
• Context switching requires “almost an hour to reload task structure into mind” (ICSE 2024)
• Paradigm choice directly affects working memory load

Functional Programming (FP)

ADHD alignment: High

• Immutability: “The less mutable state, the less the programmer has to keep in mind.” For limited working memory, removing state tracking is a structural accommodation.
• Pure functions: Output depends only on inputs -> enables local reasoning. No need to check global state, current variables, application context.
• Composition over imperative sequences: Small, testable units that can be understood in isolation
• Practical languages: Haskell, Elm, F#, functional TypeScript (fp-ts, Ramda)
• Even partial adoption (map/filter/reduce over loops, avoiding shared mutable state) yields cognitive benefits

Declarative vs. Imperative

• Declarative (SQL, CSS, React, Terraform): specify what, not how -> reduces working memory load by up to 40% on large projects
• Imperative code requires mentally simulating execution step by step (WM-intensive)
• Declarative delegates execution model to runtime, freeing cognitive resources

Visual/Node-Based Programming

• Unreal Blueprints, TouchDesigner, Node-RED, Zapier/n8n
• Spatially-organized graphs externalize control flow onto a canvas
• ADHD’s visuospatial working memory may be relatively stronger
• Especially effective for IoT, creative coding, workflow automation

Test-Driven Development (TDD)

ADHD alignment: Very High

TDD Property	ADHD Benefit
Failing test defines next step	Working memory offloading — external specification
Red-green-refactor cycle	Immediate feedback -> dopamine micro-rewards
”If code passes all tests, you’re done”	Explicit completion signal (ADHD can’t tell when to stop)
Tests constrain scope	Prevents lateral expansion into adjacent problems

• ICSE 2024 case study explicitly identifies TDD as ADHD coping strategy
• Community: “TDD is like a todo list that checks itself” (80hd.dev)

---

2. IDE and Editor Configuration

Research: Perceptual Load Study (JetBrains Research, 2023)

• Developers completed tasks in high perceptual load (noisy IDE) vs. low perceptual load (clean IDE)
• Low perceptual load: shorter time to first character, higher overall speed
• Effect was specifically more pronounced for ADHD-symptomatic developers

Distraction-Free Modes

• JetBrains: Distraction-Free Mode (hides all toolbars, tool windows, tabs); Zen Mode adds fullscreen
• VS Code: Zen Mode (Ctrl+K Z); Minimal layout + Peacock extension for color-coded workspaces
• Vim/Neovim: Minimal by default — steep learning curve but keyboard-modal workflow supports focus

Color and Fonts

• Dark themes with muted accents: One Dark Pro, Dracula, Tokyo Night — reduce brightness distraction
• Semantic highlighting: Color encodes meaning (type, scope, mutability) not just syntax -> faster comprehension with less sequential reading
• JetBrains Mono: Designed with larger character height, increased letter spacing to reduce cognitive load
• For dyslexia comorbidity (25-40%): JetBrains Mono or Atkinson Hyperlegible, 14-16pt, 1.5 line spacing
• OpenDyslexic: evidence mixed (no significant reading improvement in studies); use if subjectively preferred

Notification Management

• OS level: macOS Focus Modes / Windows Focus Assist on developer profile
• Slack/Teams: Do Not Disturb by default; scheduled check windows (e.g., 10:00, 14:00)
• IDE: Disable non-essential popups (updates, telemetry, suggestion interruptions)
• JetBrains Power Save Mode: Reduces background activity

---

3. Git Workflows for ADHD

Commits as Working Memory Snapshots

• Commit at every semantic boundary, not just “complete” features
• End every work block with a commit: "WIP: mid-way through extracting UserService; next: write tests"
• Write commit messages as future-self instructions: include problem, cause, and next step

Branch Naming as Context Cues

• fix/user-service-null-avatar-optional-chaining (ADHD-friendly: encodes problem + component + approach)
• fix-1 (ADHD-hostile: requires cross-referencing to restore context)

Git Stash as Interrupt Handler

git stash push -m "implementing UserService refactor: mid-extraction, tests failing on line 47"

• Named stashes are navigable: git stash list shows all pending context threads
• Cognitive bookmarks for inevitable ADHD context switches

Interactive Rebase as Cleanup

• Commit messily during flow (multiple small “oops” commits, experiments)
• Clean up history afterward with git rebase -i HEAD~N
• Decouples need for discipline during flow from need for clean history

End-of-Session Ritual

Two-bullet note in commit message, NOTES.md, or pinned comment:

1. State: “UserService refactor 60% complete; email validation done, password reset not started”
2. Next tiny action: “Next: write failing test for resetPassword method”

Prevents blank-page paralysis on return.

---

4. Claude Code / AI-Specific Workflows

CLAUDE.md as Externalized Executive Function

• Loaded at session initialization without requiring explicit retrieval
• Structurally isomorphic to occupational therapy “environmental modifications for executive dysfunction”
• Bypasses unreliable selective memory retrieval by embedding context in filesystem

Recommended CLAUDE.md sections:

# Project Context
[One paragraph: what and why]

# Current State
[Working, in progress, blocked]

# Established Decisions
[Architectural choices and WHY -- prevents relitigating]

# My Working Agreements
["Always async/await not .then()", "Tests before implementation"]

# Active Work
[Current focus area and next concrete action]

# Known Landmines
[Things that have caused problems before]

The Four-Layer Memory Architecture

1. System prompt (static, session-level)
2. User memories (abstracted facts, unreliably retrieved)
3. Conversation history (rolling ~190K tokens, compacts)
4. Current message (immediate input)

Design implication for ADHD: Do NOT rely on layers 2-3. Treat CLAUDE.md as the reliable memory channel. Design for sessions as independent contexts with deliberate information bridges.

Body Doubling with AI

• 2024 ACM study: body doubling confirmed as naturally effective for neurodivergent individuals
• 2025 VR study: AI body doubles -> participants finished tasks faster, perceived greater sustained attention
• Zack Proser’s setup: WhisperFlow for voice-to-structure (bypasses blank-text-field paralysis), Oura Ring for biometrics-aware planning, Claude for compassionate pushback on perfectionism

Structured Prompting Patterns

Task decomposition:

I have ADHD. Break [feature] into smallest possible steps,
each under 15 minutes with testable result. Number them.
Start with the step I can do RIGHT NOW.

Context restoration:

Here's where I left off: [paste Current State section]
Three most important things to know before continuing,
and the single next action?

Decision triage:

Stuck between [A] and [B]. Give recommendation in one sentence,
then reasoning in bullets. I don't need exhaustive analysis.
I need to move.

---

5. The Pomodoro Problem

Why Standard Pomodoro Fails for ADHD

1. 25-minute block assumes steady moderate attention — ADHD is bimodal (under-engaged OR hyperfocused)
2. Break interrupts hyperfocus — the rare state of peak productivity
3. Interruption cost: Context reloading takes nearly an hour for ADHD developers
4. Timer anxiety: Countdown creates stress competing with focus

Alternative Time Structures

Method	Structure	ADHD Benefit
Energy-Based Scheduling	Map peak energy -> demanding work; troughs -> admin	Aligns with natural attention states
Ultradian Rhythm (90/20)	90-min focus + 20-min genuine rest	Long enough to reach/sustain hyperfocus
50/10 Cadence	50-min work + 10-min physical movement	Movement resets ADHD arousal system
Flexible Wrap-Up	Timer = signal to begin wrapping, not hard stop	Prevents catastrophic thought-interruption

Key principle: Start shorter than expected (10-15 min) when motivation is low to build initiation momentum, then extend naturally when flow arrives.

Body Doubling Implementations

• Human: Focusmate, Flow Club, Study Stream (video co-working)
• AI: Claude in persistent session with hourly check-in prompts
• Research: Productivity up to 40% higher with body double

---

6. Environment Design

Acoustic Environment

• White noise: Strongest evidence for ADHD focus (stochastic resonance — moderate noise brings underaroused nervous system to optimum)
• Brown noise: Weaker formal evidence but strong community support
• Lo-fi music (60-80 BPM): Consistent, repetitive, no lyrics -> supports sustained attention
• Avoid: Music with lyrics (interferes with language processing tasks)
• Stack: Brown noise base + lo-fi beats + noise-cancelling headphones (also social “do not disturb” signal)

Physical Movement

• Fidgeting in ADHD correlates with sustained attention during cognitive tasks (Frontiers in Psychiatry 2024)
• 2015 study: ADHD children performed better on working memory tasks when allowed to move
• Recommended fidgets: Tactile, non-visual (smooth stones, mesh toys, analog rings)
• Avoid: Fidget spinners (may capture visual attention, detriment in one study)
• Standing desks: Increase prefrontal blood flow, allow natural movement
• Balance boards/walking pads: Continuous proprioceptive stimulation

Workspace

• Dedicated physical zone: Environmental conditioning as focus trigger
• Minimal desk clutter: Visual stimulation from clutter competes for attention (perceptual load principle)
• Dual monitors: Primary for code, secondary for docs/tests -> reduces context-switching cost through spatial separation
• Lighting: Bright blue-spectrum morning (alertness); warm dim evening (circadian alignment)

---

7. Documentation-as-You-Go Systems

The ADHD Documentation Problem

1. Feels separate from “real work” (low intrinsic motivation)
2. Requires context switching from implementation flow
3. Audience is abstract and distant
4. Writing may be effortful (up to 65% of ADHD may meet criteria for writing LD)

AI-Powered Solutions

Architecture Decision Records (ADRs):

• Short (1-2 pages), structured (template-driven)
• AI can generate during the session when decision is made
• CLAUDE.md instruction: “When we make architectural decisions, remind me to create an ADR”

Inline comments:

1. Write code (no comments during flow)
2. At session end: "Add inline comments explaining non-obvious parts"
3. Review and accept/modify (evaluating is easier than generating for ADHD)

Decision comments over implementation comments:

• // Using redis because postgres queries timed out under load (see ADR-004) > // Get user from database
• Captures the why that working memory won’t retain

Video documentation (Loom):

• Leverage verbal fluency as alternative channel
• Talk through code instead of writing about it

---

8. The “Second Brain” Architecture

Tools Comparison

Tool	ADHD Strength	ADHD Liability
Obsidian	Local-first, graph view suits associative thinking, daily notes as low-friction capture	Customization depth is a rabbit hole
Notion	Same data in multiple views (kanban/calendar/table), lower technical barrier	Online-only, endless customization
Logseq	Open-source, outliner model naturally externalizes hierarchical decomposition	Smaller ecosystem

Claude Code + Obsidian Integration

• /init creates CLAUDE.md at vault root
• Combines second brain’s knowledge graph with AI’s execution capacity
• Contextual retrieval, knowledge synthesis, documentation generation, project state persistence

PARA Method (Tiago Forte)

• Projects (active, defined completion) | Areas (ongoing responsibility) | Resources (reference by topic) | Archives (inactive)
• Only 4 top-level categories -> eliminates unlimited folder-nesting that ADHD brains create and can’t navigate
• A four-choice decision is tractable; unlimited hierarchy is not

Capture-First, Organize-Later

1. Minimize capture friction: Single keypress inbox (Quick Capture, voice memo, index card)
2. Defer organization: Process inbox at scheduled time, not during work
3. Accept imperfection: Some items will never be processed. Capture still provides searchable artifact.

---

The ADHD Developer’s Toolkit Summary

Layer	Tool/Practice	What It Externalizes
Paradigm	FP, TDD, Declarative	Working memory, completion detection
IDE	Zen mode, semantic highlighting, managed notifications	Perceptual filtering, distraction blocking
Version Control	Named branches, WIP commits, stash-as-bookmark	Context persistence, session continuity
AI	CLAUDE.md, structured prompts, body doubling	Executive function, task initiation, context restoration
Time	Energy-based scheduling, 90/20 blocks	Time perception, energy matching
Environment	Brown noise, standing desk, dual monitors, fidgets	Arousal regulation, spatial context
Documentation	AI-generated ADRs, commit-time comments, video docs	Writing burden, motivation for meta-work
Knowledge	Obsidian/Notion + PARA, capture-first workflow	Long-term memory, knowledge organization

The ADHD developer’s advantage is not in fighting their neurology but in building an external cognitive infrastructure so comprehensive that the bottleneck shifts from executive function to creative capacity — where ADHD excels.