What Is CLAUDE.local.md and When to Use It
By Tyler Cyert
CLAUDE.local.md is a personal instruction file that sits next to your project's CLAUDE.md but is gitignored — it never gets committed. Use it for developer-specific preferences, local environment quirks, and personal workflow shortcuts that should not be shared with your team.
If CLAUDE.md is the team contract, CLAUDE.local.md is your personal addendum. Both get loaded every session. Both use the same markdown format. The only difference is visibility.
When to Use CLAUDE.local.md
| Goes in CLAUDE.md | Goes in CLAUDE.local.md |
|---|---|
| Project stack and architecture | Your local dev environment paths |
| Team coding conventions | Your verbosity preferences |
| Build and test commands | Your editor-specific quirks |
| Shared rules and guardrails | Temporary debugging instructions |
| Agent role definitions | Personal shortcuts and aliases |
The test is simple: if removing this instruction would break another developer's experience, it belongs in CLAUDE.md. If it only matters to you, it goes in CLAUDE.local.md.
How CLAUDE.local.md Loads
Claude Code loads instruction files in this order:
~/.claude/CLAUDE.md— global personal instructionsCLAUDE.md— project team instructionsCLAUDE.local.md— project personal overrides
Later files take precedence on conflicts. If CLAUDE.md says "be concise" but your CLAUDE.local.md says "explain your reasoning step by step," the verbose style wins for your sessions.
What to Put in CLAUDE.local.md
Environment-Specific Paths
Your local database might be on a different port. Your Python venv might live in a non-standard location. Your Docker setup might differ from the team default.
Verbosity Preferences
Some developers want Claude to explain its reasoning. Others want terse responses with no commentary. This is personal preference — do not inflict it on the team.
Temporary Debugging Context
When you are tracking down a specific bug, add context to CLAUDE.local.md: "The issue is in the auth middleware. Focus on token refresh logic. The bug manifests as 401 errors after exactly 30 minutes." Delete it when you are done.
Personal Workflow Shortcuts
If you always run a specific sequence of commands after making changes, document it in CLAUDE.local.md so Claude follows your personal workflow without the team needing to adopt it.
CLAUDE.local.md vs. settings.local.json
Both are gitignored. Both are personal. They serve different purposes:
| CLAUDE.local.md | settings.local.json | |
|---|---|---|
| Format | Markdown prose | JSON config |
| Purpose | Behavioral instructions | Tool permissions, hooks, env vars |
| Controls | How Claude thinks and responds | What Claude can access and run |
Use CLAUDE.local.md for instructions and context. Use settings.local.json for permissions and configuration.
Gitignore Setup
Add CLAUDE.local.md to your project's .gitignore:
CLAUDE.local.md
Most Claude Code projects already include this in their gitignore. If you scaffolded your project with DotBox, it is included automatically.
Team Workflow
A healthy team setup looks like this:
- CLAUDE.md — committed, shared, reviewed in PRs like any other code
- CLAUDE.local.md — gitignored, personal, never reviewed
- .claude/settings.json — committed, shared tool permissions
- .claude/settings.local.json — gitignored, personal overrides
This pattern lets your team enforce standards through CLAUDE.md while giving each developer room to customize their own experience. The combination of shared and personal files across both the instruction layer and the configuration layer covers every use case.
Setting Up CLAUDE.local.md with DotBox
DotBox generates the complete .claude/ directory structure including the gitignore entries for CLAUDE.local.md and settings.local.json. The exported zip separates team files from personal files so your git history stays clean from the first commit.