How to Layer Global, Project, and Local CLAUDE.md Files

Claude Code reads more than one memory file and merges them. Knowing which file holds which instruction keeps your team's shared rules in version control while your personal preferences and secrets stay private. This guide sets up all three layers correctly.

What you need

• Claude Code installed
• A git-tracked project you share with others (or will)
• About 10 minutes

Step 1: Understand the three layers

The agent merges memory from a personal global file, the project file, and an optional local override. Each has a job.

Step 2: Set your global preferences

Put preferences that apply everywhere in the global file: tone, how you like commits written, tools you always have installed.

# Personal defaults
- Keep explanations short; show the diff, not a lecture.
- Prefer ripgrep (`rg`) over grep.
- Conventional commit messages (feat:, fix:, chore:).

Step 3: Put shared rules in the project file

Anything every contributor must follow goes in the committed CLAUDE.md so the whole team and their agents stay aligned.

Step 4: Add a private local override

Use CLAUDE.local.md for things only you need: a scratch staging URL, a personal shortcut, a reminder. Then make sure git ignores it so it never reaches the shared repo.

echo 'CLAUDE.local.md' >> .gitignore
printf '# My local notes\n- Staging API: http://localhost:8081\n' > CLAUDE.local.md
git status   # confirm CLAUDE.local.md is NOT listed

Result: shared conventions travel with the repo, your personal habits follow you across projects, and private notes stay off the team's radar, all merged automatically each session.