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

Use a personal global memory, a shared project CLAUDE.md, and an untracked local override so each layer holds the right kind of instruction.

9 minIntermediate

Visit Claude Code

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.

File	Location	Scope	Commit it?
Global memory	~/.claude/CLAUDE.md	Every project you work on	No (personal)
Project memory	./CLAUDE.md	This repo, shared with the team	Yes
Local override	./CLAUDE.local.md	Just you, just this repo	No (gitignore it)

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.

~/.claude/CLAUDE.md

# 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.

Editor - repo root

Explorer

CLAUDE.md

CLAUDE.local.md

.gitignore

src/

CLAUDE.md

1# Project: payments-service

3## Rules (all contributors)

4- Run `make test` before every commit.

5- Never log card numbers or tokens.

6- Migrations go in db/migrations, one per PR.

Project memory is committed; local overrides are ignored.

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.

terminal

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

Never put secrets in committed memory

API keys and tokens belong in environment variables, not in any CLAUDE.md. Even CLAUDE.local.md can be backed up or synced. Memory files are for instructions, not credentials.

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.