November 30, 2025
Claude left your docs on read
Writing a Good Claude.md
The one file that teaches Claude — and why devs say it keeps getting ignored
TLDR: CLAUDE.md is the briefing file for Claude, but the AI may ignore it unless it’s obviously relevant. Commenters split between using fewer instructions, enforcing behavior with tests, or spreading many small guides, while others demand updated benchmarks on newer models—because this is how we keep AI helpers useful.
Claude’s “how-to” guide just got messy. The post says large language models (think: chatty AIs) have goldfish memory, so you need a CLAUDE.md file to brief them on your project every session. But here’s the bombshell: a built‑in reminder tells Claude to ignore your doc unless it’s clearly relevant. Cue fireworks. One camp cheered the honesty; another called it a stealth nerf. The thread lit up with “Claude ghosted my .md” jokes and side-eyes at Anthropic.
The hottest take came from andersco, who says don’t beg the bot—make the codebase itself the boss. Tests, linters, and type checks as the real “Claude.md,” so the AI has to pass or fail. Meanwhile, prettyblocks wants many mini-guides spread across folders, not one mega manifesto—like post‑it notes instead of a 200‑page manual. Skeptics like jasonjmcghee demanded receipts: if you’re going to tell us what works, show results on the latest models, not yesterday’s lineup. Newcomers like eric-burel just want a “how do I even log this?” tutorial, and vladsh summed up the vibe: what even counts as a “good” Claude.md?
Bottom line: fewer bossy instructions, more real‑world checks, and maybe a flock of focused AGENTS.md files (think GitHub Copilot style). The only thing everyone agrees on? Claude will ignore fluff—so don’t feed it any.
Key Points
- •LLMs used for coding are mostly stateless and only know the tokens provided during each session.
- •Coding agents require explicit memory management; CLAUDE.md/AGENTS.md is the default context included in every conversation.
- •CLAUDE.md should outline WHAT, WHY, and HOW of the codebase, including stack, structure, and workflows to verify changes.
- •Claude may ignore CLAUDE.md due to an injected system reminder that filters non-relevant context.
- •Users can inspect this behavior by proxied logging via ANTHROPIC_BASE_URL, and should keep CLAUDE.md concise and broadly applicable.