CLAUDE.md holds persistent project instructions for Claude Code, which reads it at session start. It gives conventions a place outside conversation history, where early instructions can be lost during context compaction. Reloading at session start does not make compaction lossless. section 3.5.2 section 9.5.2
Use the file for guidance that should apply across sessions, such as project conventions and boundaries on file exploration. Explicit reading rules can keep an agent from scanning irrelevant directories or the entire test suite when only one module is under change. These are instructions to the agent, so check their effect rather than assuming compliance. section 3.5.2 section 9.5.2
Listing 9.7 File Reading Rules in CLAUDE.md
## File Reading Rules - NEVER read files in: node_modules/, dist/, .next/, coverage/ - NEVER read: package-lock.json, yarn.lock - For test files, read ONLY the test file for the module under change - For config files, read ONLY if the task explicitly involves config
These rules exclude generated directories and lockfiles, narrow test-file reads, and limit configuration reads to relevant tasks. section 9.5.2
Command-output rules offer another cost control: verbose test and build output enters the context window and can be reprocessed on subsequent messages. Filtering reduces that burden, but choose filters carefully so important diagnostic output is not missed. section 9.5.2
Listing 9.8 Command Output Rules in CLAUDE.md
## Command Output - When running tests, pipe through `tail -50` to capture only failures - When running builds, pipe through `grep -E "error|warning"` - Never run commands that produce unbounded output without filtering
This example asks the agent to filter test and build output rather than leave it unbounded. section 9.5.2
For teams using multiple agents, AGENTS.md is a tool-agnostic alternative for shared project guidance; CLAUDE.md can hold Claude-specific rules or point to shared rules. Tool support must be verified: the supplied guidance conflicts on whether Claude Code reads AGENTS.md. A missing instruction file can fail silently, leaving agents to produce inconsistent code. section 3.5.2 section 5.4.1

