Writing a good CLAUDE.md | HumanLayer Blog
Research shows LLMs can only follow ~150-200 instructions reliably, and Claude Code already uses 50 of them - so your CLAUDE.md file needs to be a minimal, strategic onboarding doc, not a comprehensive reference manual.
Read Original Summary used for search
TLDR
• Frontier LLMs exhibit linear decay in instruction-following after ~150-200 instructions, and adding more instructions degrades performance uniformly across all instructions (not just the new ones)
• Claude Code injects a system reminder telling Claude to ignore CLAUDE.md unless it's "highly relevant" - so stuffing it with task-specific instructions backfires
• Use "progressive disclosure": keep CLAUDE.md minimal and point to separate markdown files (like agent_docs/building_the_project.md) that Claude reads only when needed
• Never use LLMs for code formatting/linting - they're expensive and slow compared to deterministic tools like Biome, and style guidelines bloat your context window
• CLAUDE.md is the highest leverage point of the entire harness (affects every phase of workflow) - don't auto-generate it with /init, craft it carefully
In Detail
The core insight is that CLAUDE.md is a high-leverage configuration point that most developers misuse by treating it as a comprehensive reference. Because LLMs are stateless, CLAUDE.md is the only file injected into every conversation, making it critical for onboarding. However, Claude Code adds a system reminder telling the model to ignore CLAUDE.md content unless it's "highly relevant" to the current task - likely because users were stuffing it with too many non-applicable instructions.
Research on instruction-following reveals key constraints: frontier thinking models can reliably follow ~150-200 instructions before performance degrades, and smaller models degrade exponentially faster. Critically, as instruction count increases, the model doesn't just ignore new instructions - it begins ignoring all of them uniformly. Since Claude Code's system prompt already contains ~50 instructions, you have limited budget remaining. The solution is "progressive disclosure": keep CLAUDE.md minimal (the author's is under 60 lines) with only universally-applicable context about your project's WHY, WHAT, and HOW. Point to separate markdown files in an agent_docs/ directory for task-specific instructions, letting Claude decide what to read.
The author argues strongly against common anti-patterns: never include code style guidelines (use linters like Biome instead - LLMs are expensive, slow, and in-context learners anyway), don't auto-generate with /init (CLAUDE.md affects every artifact produced, making it the highest leverage point), and keep content concise and universally applicable. The key is understanding that CLAUDE.md is for strategic onboarding, not comprehensive documentation.