Skip to content

Effective CLAUDE.md covers three dimensions (WHAT/WHY/HOW) and stays under 300 lines
Source type Practitioner
Confidence Medium
Last verified 2026-03-25
Topics claude-code

Insight: Effective CLAUDE.md files cover three dimensions (project architecture/tech stack, functional purpose, development workflow/testing procedures) while staying under 300 lines. Research indicates frontier LLMs reliably follow 150-200 instructions; since Claude Code's system prompt contains ~50, CLAUDE.md should contain only universally applicable guidance. Progressive disclosure stores specialized guidance in separate files (agent_docs/building_the_project.md), letting Claude decide relevance per task.

Detail: Critical anti-pattern: never use CLAUDE.md for linting rules—'Never send an LLM to do a linter's job.' Avoid auto-generation; each line warrants careful consideration. Smaller models degrade much faster with instruction count, making conciseness critical across model scales.

Sources