CLAUDE.md

1# CLAUDE.md
2 
3A markdown file that gives Claude persistent context about your project. Loaded into every session automatically, no manual prompting required.
4 
5## Quick Start
6 
71. Run `/init` in Claude Code. It analyses your codebase and generates a starter `CLAUDE.md`
82. Review and refine what it creates. Add what Claude can't infer on its own
93. Commit to version control so your team shares the same context
104. Iterate over time. Add instructions as you discover friction points
11 
12## What to Put in It
13 
14| Section | Purpose | Example |
15|---|---|---|
16| Project overview | Orient Claude in your codebase | Tech stack, architecture, key directories |
17| Build & test commands | Let Claude run your workflows | `npm test`, `cargo build`, `make deploy` |
18| Code conventions | Enforce your team's style | Naming, imports, error handling patterns |
19| Common workflows | Prevent rework | Branch naming, PR process, deploy steps |
20| Tool & MCP notes | Connect Claude to your environment | Custom scripts, [MCP](^Model Context Protocol: a standard that lets Claude connect to external tools and services) server usage notes |
21| Gotchas & warnings | Avoid known pitfalls | Files not to edit, quirks, env requirements |
22 
23## Where It Can Live
24 
25| Location | Scope | Use For |
26|---|---|---|
27| `./CLAUDE.md` | Project (shared) | Team standards, architecture, build commands |
28| `./.claude/CLAUDE.md` | Project (shared) | Same as above, alternate location |
29| `~/.claude/CLAUDE.md` | Personal (all projects) | Your preferences across every project |
30| `./CLAUDE.local.md` | Personal (this project) | Your sandbox URLs, preferred test data. [Gitignored](^Automatically added to .gitignore so it stays local and is never committed to version control) |
31| [Managed policy path](^A system-level path managed by IT/DevOps. macOS: /Library/Application Support/ClaudeCode/CLAUDE.md, Linux: /etc/claude-code/CLAUDE.md, Windows: C:\Program Files\ClaudeCode\CLAUDE.md) | Organisation-wide | Company security policies, compliance rules |
32 
33More specific locations take precedence over broader ones. Claude also discovers `CLAUDE.md` files in subdirectories and loads them on demand when working in those directories.
34 
35## Importing Files
36 
37Use `@path/to/file` syntax to pull additional files into context:
38 
39```markdown
40See @README.md for project overview.
41Git workflow: @docs/git-instructions.md
42```
43 
44- Relative paths resolve from the file containing the import
45- Imports can chain up to 5 levels deep
46- First use in a project triggers an approval dialog
47- Great for pulling in READMEs, package.json, or workflow guides without duplicating content
48 
49## Writing Effective Instructions
50 
51- **Be specific**: [Use 2-space indentation](^A concrete, verifiable instruction Claude can follow exactly) not [Format code properly](^Too vague for Claude to act on consistently. What does 'properly' mean?)
52- **Be concise**: Target under 200 lines. Longer files [dilute adherence](^The more instructions Claude has to track, the less reliably it follows each one)
53- **Use structure**: Markdown headers and bullets. Claude scans structure like a reader does
54- **Avoid conflicts**: If two instructions contradict, Claude picks one arbitrarily. Review periodically
55- **Split when large**: Use [@ imports](^The @path/to/file syntax described above that pulls other files into CLAUDE.md context) or `.claude/rules/` files to break up long instructions
56 
57## Tips
58 
59- CLAUDE.md is [context, not enforcement](^Claude reads it and tries to follow it, but there is no strict guarantee. Specific, unambiguous instructions get the best results). Specific instructions are followed more reliably than vague ones
60- `/init` works on existing projects too. It suggests improvements rather than overwriting
61- Use `/clear` between unrelated tasks to reset accumulated context while keeping CLAUDE.md loaded
62- CLAUDE.md [survives /compact](^When you run /compact, Claude re-reads CLAUDE.md from disk and re-injects it fresh. Instructions given only in conversation will be lost, but CLAUDE.md persists). It is re-read from disk and re-injected fresh
63- Never include secrets, API keys, or credentials. Treat it as public documentation
64- Start simple. Expand based on real friction, not hypothetical needs
65 
66## Further Reading
67 
68- [Official docs: How Claude remembers your project](https://code.claude.com/docs/en/memory#claude-md-files)
69- [Blog: Using CLAUDE.md files](https://claude.com/blog/using-claude-md-files)