DEV Community

gentic news
gentic news

Posted on • Originally published at gentic.news

Use CLAUDE.md as External Working Memory

#ai #tech #opinion #analysis

Use CLAUDE.md as external working memory: add Stack, Voice, Gotchas, and Current checkpoint sections to cut session restart time from 5–15 minutes to under 1 minute, per self-reported data.

What Changed — The Specific Insight

A developer with ADHD tracked their Claude Code sessions and found that reopening a project without a CLAUDE.md cost them 5 to 15 minutes of "where was I" each time. After writing a structured CLAUDE.md, that time dropped to under 1 minute. The key wasn't a new feature—it was using CLAUDE.md as external working memory.

CLAUDE.md is a Markdown file that Claude Code reads automatically at the start of every session. You don't paste it. You don't 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).

Why It Works — The Working Memory Argument

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.

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?"

How To Apply It — Step-by-Step

Do not engineer the perfect file. Open the project, create CLAUDE.md at the root, and write four headers:

Cover image for The ADHD Developer's Guide to CLAUDE.md

# Project: my-app

## Stack (do not re-ask)
- Next.js 14 + TypeScript
- Tailwind CSS v3
- PostgreSQL + Prisma ORM

## 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.
- Reading time is auto-calculated. Do not hardcode it.

## Current checkpoint
- Last task: shipped user authentication flow.
- Next task: implement password reset endpoint.
- Blocked by: nothing.
Enter fullscreen mode Exit fullscreen mode

The Current checkpoint block is the one that matters most. Before it, every session opened with a flailing minute or two of "okay where was I." Now the first thing Claude tells you is what you were doing and what is next, because it read the checkpoint before you said a word.

The Global File Handles the Re-Decided Stuff

The project file handles per-project facts. The global ~/.claude/CLAUDE.md handles the things you were 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.
Enter fullscreen mode Exit fullscreen mode

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 you in one decision at a time.

Try It Now

  1. Run touch CLAUDE.md in your project root.
  2. Paste the four-section template above.
  3. Fill in what you know right now. Leave the rest blank.
  4. Also run mkdir -p ~/.claude && touch ~/.claude/CLAUDE.md for global rules.
  5. Every time Claude asks you something you wish it already knew, write that answer into the file.

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.

Watch out for stale context. An out-of-date CLAUDE.md does not just fail to help—it actively lies to you with full confidence. When you change something structural, update the file in the same breath.

Source: dev.to

[Updated 16 Jun via hn_claude_code]

A new community-built extension, Claude Code for Visual Studio, brings the same protocol used by official IDE plugins to Microsoft's IDE, adding a native diff viewer with accept/reject buttons and the ability to reject with a reason for Claude to retry. It also shares compiler errors and current selection automatically [per HN].

Originally published on gentic.news

Top comments (0)