Writing a good CLAUDE.md

LLMs are stateless functions with frozen weights, meaning they know absolutely nothing about your codebase at the start of each session. CLAUDE.md is the only file that by default goes into every single conversation, making it the primary mechanism for onboarding the agent into your project context.

An effective CLAUDE.md should cover three dimensions: WHAT (tech stack, project structure, codebase map), WHY (purpose of the project and its components), and HOW (workflows, build commands, testing, and verification steps). This gives Claude the minimum viable context to do meaningful work.

Claude Code injects a system reminder telling Claude that the CLAUDE.md context 'may or may not be relevant' and to ignore it unless highly relevant. This means instructions that aren't universally applicable are likely to be skipped entirely, undermining the user's intent.

Research suggests frontier thinking LLMs can reliably follow approximately 150-200 instructions, and Claude Code's system prompt already consumes about 50 of those. This means CLAUDE.md should contain as few instructions as possible to avoid degrading instruction-following quality uniformly across all instructions.