CLAUDE.md

CLAUDE.md is a markdown file of persistent instructions that Claude reads at the START of every session. Verified locations, in load order from broadest to most specific: managed policy (/Library/Application Support/ClaudeCode/CLAUDE.md on macOS, /etc/claude-code/CLAUDE.md on Linux and WSL, C:\Program Files\ClaudeCode\CLAUDE.md on Windows); user instructions (~/.claude/CLAUDE.md); project instructions (./CLAUDE.md or ./.claude/CLAUDE.md); local instructions (./CLAUDE.local.md, which should be gitignored). All discovered files are CONCATENATED into context rather than overriding each other, walking up the directory tree from your working directory. Files can import others with @path/to/import syntax, relative to the importing file, with a maximum depth of four hops. However, imports do not save context, since imported files load at launch too. Target under 200 lines: longer files consume more context and reduce adherence.

Key mechanical fact: CLAUDE.md content is delivered as a user message AFTER the system prompt, not as part of it. Claude reads it and tries to follow it, but there is no guarantee of strict compliance. It is context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead. Run /init to generate a starting CLAUDE.md. Project-root CLAUDE.md survives compaction: after /compact, Claude re-reads it from disk and re-injects it. This mechanism is related to how agents-md files provide persistent instructions for agents. Unlike a strict configuration file, CLAUDE.md functions more like a set of guidelines within the context-window, influencing behavior but not rigidly enforcing it. Consider it a form of auto-memory that persists across sessions.