What Is a CLAUDE.md File?
CLAUDE.md is a plain Markdown file of instructions that Claude Code reads at the start of every session: build commands, conventions, project layout, and the rules you'd otherwise repeat. It's context, not enforcement. To guarantee something is blocked, use a hook or permission rules.
The earlier version relied on a Reddit discussion and described loading behaviour loosely. It now follows the official Claude Code memory docs.
Where it can live
| Scope | Location | Use for |
|---|---|---|
| Managed policy | macOS /Library/Application Support/ClaudeCode/CLAUDE.md · Linux/WSL /etc/claude-code/CLAUDE.md · Windows C:\Program Files\ClaudeCode\CLAUDE.md | Organisation-wide rules set by IT |
| User | ~/.claude/CLAUDE.md | Your preferences in every project |
| Project | ./CLAUDE.md or ./.claude/CLAUDE.md | Team rules, committed to git |
| Local | ./CLAUDE.local.md | Your personal project notes; add it to .gitignore |
Files from your working directory upwards load at launch, broadest first. Files in subdirectories load when Claude reads files there, including when it views a file with a shell command such as cat or head (a fix in 2.1.293; before it, viewing a file that way did not load them). Run /init to generate a starting file from your codebase, and /memory to view and edit what's loaded.
AGENTS.md
If a repository already has an AGENTS.md for other coding tools, Claude Code can read it, either on its own when there's no CLAUDE.md (since v2.1.277) or alongside one. You no longer need a CLAUDE.md that just points to it.
Keeping it effective
- Under about 200 lines. It loads into every session, and longer files reduce how well Claude follows them.
- Be verifiable: "Use 2-space indentation" and "Run
npm testbefore committing", not "format code properly". - Remove contradictions. When two rules conflict, Claude may pick either one.
- Move specifics out: path-scoped rules go in
.claude/rules/(they load only for matching files), multi-step procedures go in skills, and other files can be pulled in with@pathimports. - Add to it when Claude makes the same mistake twice, or you type the same correction as last session.
Auto memory is the other half: notes Claude writes itself from your corrections, stored per repository. The first 200 lines or 25 KB load each session.
Starter template
# Project: <name>
## Commands
- Build: npm run build
- Test: npm test (run before every commit)
- Lint: npm run lint
## Layout
- src/api/handlers/ HTTP handlers
- src/db/ schema and queries
## Rules
- TypeScript strict; no "any" types
- Never push to main; open a PR
Source: Claude Code docs: how Claude remembers your project. Checked 2026-10-09.
← Back to Claude Cowork FAQ · See also: System Prompts Guide · OpenClaw SOUL.md