Equipping Claude Code
7. CLAUDE.md
Learn how to create the CLAUDE.md file that guides Claude Code in your project. Essential setup for accurate responses.
It's not an installation, but it's the first thing to set up in any project. CLAUDE.md is persistent memory — Claude reads it automatically to understand your project.
Where to place it
| File | Scope | Typical use |
|---|---|---|
./CLAUDE.md | Project (root) | Architecture, stack, conventions |
./.claude/CLAUDE.md | Project (hidden) | Same, but organized inside .claude/ |
./CLAUDE.local.md | Personal | Developer preferences, not committed |
~/.claude/CLAUDE.md | Global | Personal defaults for all projects |
The .claude/ folder should be committed — it contains shared team configurations (settings, commands, CLAUDE.md). The convention for separating personal items is the .local suffix: files like CLAUDE.local.md and settings.local.json stay out of version control.
Same concept, different names: every AI coding assistant uses a project memory file.
| Assistant | File |
|---|---|
| Claude Code | CLAUDE.md |
| OpenAI Codex | AGENTS.md |
| Google Antigravity | GEMINI.md |
| Cursor | .cursorrules / .cursor/rules/ |
| Windsurf | .windsurfrules |
| GitHub Copilot | .github/copilot-instructions.md |
If you use more than one assistant, you can keep both files in the repository — each agent only reads its own.
What to include
- Project description and stack
- Code conventions (naming, imports, patterns)
- Commands to run, build, and test
- Directory structure
- Rules that Claude should always follow
Ready-made templates
To make creating your CLAUDE.md easier, we've prepared templates with structures tested in real projects:
Global CLAUDE.md
Universal rules for any project. Save at ~/.claude/CLAUDE.md
53 lines, 9 sections
Next.js Full-Stack CLAUDE.md Single file with global rules + Next.js project 171 lines, 18 sections
Next.js (project) CLAUDE.md Next.js project-specific rules, requires global CLAUDE 100 lines, 11 sections