Write a Minimal, High-Leverage CLAUDE.md

CLAUDE.md should onboard Claude to your codebase with only the essential and universally relevant WHY/WHAT/HOW. Because instruction-following declines with instruction count (and the harness already adds many), keep it short and rely on Progressive Disclosure for task-specific details via separate, referenced docs. Use linters/formatters and hooks instead of stuffing style rules into CLAUDE.md, and avoid auto-generating this high-leverage file.

Key Points

• LLMs are stateless; CLAUDE.md is the persistent, session-wide way to onboard the agent with your project’s WHY/WHAT/HOW.
• Claude often ignores CLAUDE.md if it’s not clearly relevant; include only universally applicable information.
• Instruction-following degrades as instructions increase; keep CLAUDE.md very concise, given the harness already adds ~50 instructions.
• Use Progressive Disclosure: keep task-specific guidance in separate docs and reference them via pointers instead of copying content.
• Don’t use CLAUDE.md as a linter; rely on deterministic tools (linters/formatters, hooks, slash commands), and avoid auto-generating CLAUDE.md.

Sentiment

The community is generally supportive of the article's core thesis that CLAUDE.md should be minimal and data-driven. The praise centers on the instruction-following research and the practical progressive disclosure approach. However, there is meaningful pushback from two camps: those who believe CLAUDE.md is unnecessary entirely (just write good docs), and those who have found success with larger, more detailed files. The overall tone is constructive and experience-sharing rather than hostile.

In Agreement

• The 'Mr. Tinkleberry' canary test validates the article's claim that Claude stops following instructions as CLAUDE.md grows — keeping it minimal is essential for reliability
• Progressive disclosure via directory-specific CLAUDE.md files and pointers to separate docs is the most effective way to provide rich context without overwhelming the model's instruction budget
• The research graph showing instruction-following quality degrades uniformly with instruction count is a genuinely novel and useful data point that most developers haven't seen before
• Code style rules belong in deterministic linters and formatters, not in CLAUDE.md — hooks and slash commands can enforce this without burning context
• Claude Code's system-reminder injection explains why CLAUDE.md sometimes gets ignored, making the case for brevity even stronger

Opposed

• CLAUDE.md is unnecessary if you simply document your code well — good README files, inline comments, and standard engineering practices give LLMs all the context they need
• The only good Claude.md is a deleted Claude.md — the entire concept of writing special instructions for an LLM is a waste of engineering effort
• Large, detailed CLAUDE.md files with targeted context for agents, hooks, and skills work well in practice, contradicting the minimalist thesis
• Newer frontier models like Opus 4.5 already infer coding style and preferences from existing code, making explicit CLAUDE.md instructions increasingly redundant
• Prompt instability across model versions means any carefully crafted CLAUDE.md may break when models are updated, undermining the investment in hand-crafting it
• The article lacks a concrete example of an actual good CLAUDE.md, which is what most readers actually want