TL;DR
HumanLayer publishes guidance on optimizing CLAUDE.md files for AI coding agents, emphasizing concise context and progressive disclosure over instruction bloat.
Key Points
- Frontier LLMs can reliably follow ~150-200 instructions; Claude Code's system prompt already uses ~50, leaving limited budget for CLAUDE.md
- Instruction-following quality degrades uniformly as instruction count increases; smaller models exhibit exponential decay vs. linear decay for frontier models
- Recommended CLAUDE.md length: under 300 lines, ideally under 60; HumanLayer's root file stays under 60 lines
- Use progressive disclosure pattern: point Claude to task-specific markdown files instead of embedding all context in CLAUDE.md
Why It Matters
As developers increasingly use AI coding agents, understanding how context windows and instruction budgets work directly impacts code quality and agent performance. Poor CLAUDE.md files degrade agent reasoning across all tasks, making this guidance critical for anyone using Claude Code, Cursor, or similar harnesses at scale.
Source: www.humanlayer.dev