Writing a good CLAUDE.md | HumanLayer Blog
CLAUDE.md is the highest-leverage configuration point in Claude Code, but most developers sabotage it by stuffing in too many instructions—research shows LLMs can only follow ~150-200 instructions reliably, and Claude Code already uses 50 of them.
Read Original Summary used for search
TLDR
• Claude Code injects a system reminder telling Claude to ignore CLAUDE.md if content isn't relevant—bloated files actively degrade performance
• Frontier LLMs can follow ~150-200 instructions max; Claude Code's system prompt already consumes ~50, leaving limited budget for your instructions
• Use Progressive Disclosure: keep task-specific instructions in separate markdown files, reference them in CLAUDE.md only when needed
• Never use LLMs for linting/formatting—they're expensive, slow, and instruction-heavy compared to deterministic tools like Biome
• HumanLayer's production CLAUDE.md is under 60 lines; keep yours under 300 lines and universally applicable
In Detail
The core thesis is that CLAUDE.md functions as a high-leverage onboarding document that goes into every single Claude Code session, but most developers treat it wrong. Because LLMs are stateless, CLAUDE.md is the only persistent memory—making it either your biggest asset or liability. The author reveals that Claude Code actually injects a system reminder telling the AI to ignore CLAUDE.md content if it's not relevant to the current task, meaning bloated files with task-specific instructions actively hurt performance.
The key framework is understanding instruction-following capacity. Research shows frontier thinking LLMs can reliably follow ~150-200 instructions with linear decay, while smaller models exhibit exponential decay. Claude Code's system prompt already contains ~50 instructions, consuming a third of your budget before you write a single line. This means every instruction in CLAUDE.md must be universally applicable. The author recommends Progressive Disclosure: keep task-specific instructions in separate markdown files (like building_the_project.md, code_conventions.md) and only reference them in CLAUDE.md, letting Claude decide what to read.
The practical implications are significant. Never use CLAUDE.md for code style guidelines—LLMs are in-context learners and will pick up patterns from your codebase. Use deterministic tools (linters, formatters) instead, potentially via Claude Code hooks. Keep CLAUDE.md under 300 lines (HumanLayer's is under 60). Don't auto-generate it with /init—since it affects every phase of your workflow (research, planning, implementation), a bad line in CLAUDE.md has exponentially more impact than a bad line of code. The file should define your project's WHY, WHAT, and HOW in the most concise, universally applicable way possible.