CLAUDE.md
A plain markdown file that Claude Code reads at the start of every session. It is the cheapest upgrade in the whole pond, and most people either skip it or write a novel.
My CLAUDE.md is one line. It says: flies.
Start one in a minute
- Open Claude Code in your project.
- Run
/init. Claude reads the codebase and writes a starting CLAUDE.md with build commands, test instructions and the conventions it finds. If one already exists, it suggests improvements instead of overwriting. - Cut it down. Keep what Claude would otherwise get wrong. Delete what any developer could see from the files.
- Commit it. The project file is meant to be shared with your team through git.
Where the files live
| File | Who it is for |
|---|---|
./CLAUDE.md or ./.claude/CLAUDE.md | The team. Project architecture, coding standards, common workflows. Checked in. |
./CLAUDE.local.md | Just you, just this project. Sandbox URLs, test data. Add it to .gitignore. |
~/.claude/CLAUDE.md | Just you, every project. Personal style and tooling preferences. |
| Managed policy file | Your whole organization, set by IT. On macOS it lives under /Library/Application Support/ClaudeCode/. |
Claude Code loads CLAUDE.md files from your working directory and every directory above it, and joins them together rather than letting one override another. Files in subdirectories load when Claude works in that subdirectory.
Rules of thumb from the docs
- Under 200 lines per file. Longer files use more context and Claude follows them less reliably.
- Import instead of pasting.
@READMEor@path/to/filepulls another file in. Wrap a path in backticks to mention it without importing it. - It is context, not a lock. Claude treats CLAUDE.md as guidance. To truly block an action, use a PreToolUse hook.
- Already have an AGENTS.md? Claude Code can read that instead.
Auto memory
Separately from the file you write, Claude keeps its own notes from your corrections and preferences, per repository. The first 200 lines or 25KB load into every session.
Clodhopper move: Pasting the whole style guide, the onboarding doc and last quarter's roadmap into CLAUDE.md. It is read every single session. You are paying for that novel on every prompt.
Source: the Claude Code documentation at code.claude.com/docs, read on November 11, 2026.