CLAUDE.local.md and User CLAUDE.md: Personal Preferences Without Affecting the Team

Overview

CLAUDE.md is shared. The whole team sees it, uses it, and commits it to the repository. But some things are yours — style preferences, your local environment configuration, experimental rules you're trying out, or simply the way you like to interact with Claude Code.

Claude Code has two mechanisms for personal preferences:

1. CLAUDE.local.md (project-local): at the project root, NOT committed. Applies only to that project.
2. ~/.claude/CLAUDE.md (user scope): in your home directory. Applies to ALL your projects.

In this capsule you'll learn when to use each one, what to put in them, how they interact with the memory hierarchy, and the common patterns that get the most out of them. By the end of the module, you'll have a complete memory system: CLAUDE.md for the project, CLAUDE.local.md for you-in-that-project, ~/.claude/CLAUDE.md for you-everywhere, settings for permissions, and auto memory for corrections.

User scope: ~/.claude/CLAUDE.md

Before we get into CLAUDE.local.md, let's cover the User scope — a personal CLAUDE.md that applies to all your projects.

Location: ~/.claude/CLAUDE.md

When to use it:

• Style preferences that don't depend on the project (response language, verbosity, whether you want examples)
• Your personal workflow (how you like Claude to propose changes, when to ask for confirmation)
• Personal shortcuts you use across all your projects
• Command shortcuts you prefer

Example of ~/.claude/CLAUDE.md:

# My personal preferences

## Language
- Answer in conversational Spanish
- Code and identifiers in English

## Style
- Be direct and concise — don't restate the obvious
- When you explain code, include a short example
- Don't generate code comments describing WHAT it does (only WHY, when it isn't obvious)

## Workflow
- Before writing code, confirm what you understood
- If you're going to make more than 3 changes, show me the plan first
- For risky changes, I'd rather you use plan mode

User scope vs CLAUDE.local.md:

Tip for worktrees: If you work with multiple git worktrees of the same repo, CLAUDE.local.md only exists in the worktree where you created it. To share personal preferences across worktrees, import a file from your home directory:

# Individual Preferences
- @~/.claude/my-project-instructions.md

What CLAUDE.local.md is

Definition

CLAUDE.local.md is a Markdown file with these properties:

• Location: The root of your project (next to CLAUDE.md)
• Name: Always CLAUDE.local.md
• Format: Standard Markdown (same structure as CLAUDE.md)
• Purpose: Personal preferences you do NOT share with the team
• When it's read: At the start of every session, automatically (just like CLAUDE.md)
• Git: It must be in .gitignore
• Priority: Higher than CLAUDE.md, lower than the conversation

my-project/
├── CLAUDE.md              ← Project rules (git tracked)
├── CLAUDE.local.md        ← Your preferences (git ignored)
├── .gitignore             ← Includes CLAUDE.local.md
├── package.json
└── src/

How it works with CLAUDE.md

When you start a session, Claude Code reads both files:

1. Claude reads CLAUDE.md          → Project rules
2. Claude reads CLAUDE.local.md    → Your personal overrides
3. CLAUDE.local.md wins            → If there's a conflict

┌────────────────────────────────────────┐
│  Claude Code session                   │
│                                        │
│  CLAUDE.md:                            │
│  "Comments in English"                 │
│                                        │
│  CLAUDE.local.md:                      │
│  "Answer in Spanish"                   │
│  "Comments in Spanish"                 │
│                                        │
│  → Claude answers in Spanish           │
│  → Comments in Spanish                 │
│  → CLAUDE.local.md takes priority      │
│                                        │
│  Your teammate (no CLAUDE.local.md):   │
│  → Answers in English                  │
│  → Comments in English                 │
│  → Only CLAUDE.md applies              │
└────────────────────────────────────────┘

What CLAUDE.local.md is not

• ❌ It's not a replacement for CLAUDE.md (it's a complement)
• ❌ It's not for rules the whole team must follow
• ❌ It shouldn't contradict the project's critical rules
• ❌ It's not a dump of your entire personal configuration

The .gitignore convention

Why CLAUDE.local.md doesn't get committed

CLAUDE.local.md is personal by design. Your preferences shouldn't affect the rest of the team:

• You prefer answers in Spanish; your teammate prefers English
• You run PostgreSQL locally on port 5433; your teammate on 5432
• You want verbose logging; your teammate wants clean output
• You're experimenting with a pattern; your teammate isn't

If you commit CLAUDE.local.md, your personal preferences get imposed on the whole team. That defeats the purpose.

How to configure .gitignore

echo "CLAUDE.local.md" >> .gitignore
git add .gitignore
git commit -m "chore: ignore CLAUDE.local.md"

Check that it's ignored:

git status
# CLAUDE.local.md should NOT appear as untracked

What if I want a template?

If you want your team to know CLAUDE.local.md exists and how to use it, create a template:

# Create a template that DOES get committed
cat > CLAUDE.local.md.example << 'EOF'
# CLAUDE.local.md (Personal Preferences)
# Copy this file as CLAUDE.local.md and customize it.
# Do NOT commit CLAUDE.local.md to the repo.

## Language
# Answer in [your preferred language]

## Style
# [Your code style preferences]

## Local environment
# [Your local configuration]
EOF

git add CLAUDE.local.md.example
git commit -m "docs: add CLAUDE.local.md template"

Use cases

1. Language preferences

# CLAUDE.local.md

## Language
- Always answer in Spanish
- Code comments in Spanish
- Variable and function names in English (follow CLAUDE.md)
- Commit messages in English (follow CLAUDE.md)

The project can have its CLAUDE.md in English, but you want Claude to answer you in Spanish. CLAUDE.local.md solves that without affecting the team.

2. A specific local environment

# CLAUDE.local.md

## My local environment
- Database: localhost:5433 (my PostgreSQL runs on a non-standard port)
- Redis: localhost:6380 (I have another Redis on 6379 for a different project)
- The frontend dev server is at http://localhost:3001 (not 3000)
- Python virtualenv: ~/envs/invoice-api/

Every developer has their environment configured differently. Those differences belong in CLAUDE.local.md.

3. Interaction style

# CLAUDE.local.md

## How to interact with me
- Always explain your reasoning before writing code
- Show the diff instead of the whole file whenever possible
- Don't use emojis in your answers
- Be concise — I prefer short, direct answers
- When there are multiple options, give me a comparison table

4. Personal coding style preferences

# CLAUDE.local.md

## My style
- I prefer early returns over nested ifs
- I like guard clauses at the top of functions
- I prefer named exports over default exports
- Use destructuring whenever possible
- For one-line functions: arrow without braces

These preferences are yours. Your teammate might prefer the opposite — and their CLAUDE.local.md will reflect that.

5. Experimental rules

# CLAUDE.local.md

## Experiments (temporary)
- I'm trying the Result<T, E> pattern for error handling
  instead of try/catch. Use it in new code you generate.
- I'm evaluating Drizzle ORM as a replacement for Prisma.
  For new endpoints, use Drizzle.

You're trying something new. You don't want the team to adopt it until you're sure. CLAUDE.local.md lets you experiment without touching the project's CLAUDE.md.

6. Accessibility

# CLAUDE.local.md

## Accessibility
- Use verbose logging with timestamps for debugging
- In diffs, include 5 lines of context before and after
- When you generate tables, don't use more than 4 columns
- Prefer bullet points over long paragraphs

7. Temporary context

# CLAUDE.local.md

## Current context
- I'm working on the branch feature/payment-refunds
- The current task is JIRA-1234: implement refunds
- The POST /api/refunds endpoint is half-implemented
  (the amount validation is missing)

This gives Claude context about what you're working on right now, without polluting CLAUDE.md with temporary information.

How it interacts with the hierarchy

Its position in the 6-level hierarchy

CLAUDE.local.md sits between the project's CLAUDE.md (level 4) and the subdirectory CLAUDE.md (level 5):

6. Conversation          ← Highest priority
5. Subdir CLAUDE.md
4b. CLAUDE.local.md      ← HERE
4a. Project CLAUDE.md
3. Enterprise CLAUDE.md
2. System prompt
1. Training data         ← Lowest priority

The precedence rule

CLAUDE.md says:          "Comments in English"
CLAUDE.local.md says:    "Comments in Spanish"
→ CLAUDE.local.md wins   (comments in Spanish)

CLAUDE.local.md says:    "Use Drizzle ORM"
The subdirectory says:   "In tests/, use in-memory SQLite"
→ The subdirectory wins  (SQLite in tests/)

CLAUDE.local.md says:    "Concise answers"
You, in conversation:    "Give me a detailed explanation of this"
→ The conversation wins  (detailed explanation)

What CLAUDE.local.md can and can't do

It can:

• Override style preferences from CLAUDE.md
• Add personal context (environment, language, tools)
• Add personal rules that complement CLAUDE.md
• Relax non-critical rules for your personal use

It shouldn't:

• Disable the project's safety rules
• Contradict the architecture defined in CLAUDE.md
• Change the project's stack ("use Rust instead of Python")
• Redefine the file structure

The structure of CLAUDE.local.md

Recommended template

# CLAUDE.local.md — Personal preferences

## Language
[Your preferred language for answers and comments]

## Interaction style
[How you want Claude to interact with you]

## Coding preferences
[Your personal code style]

## Local environment
[Your local configuration: ports, paths, tools]

## Current context (temporary)
[What you're working on right now — update it often]

Complete example

# CLAUDE.local.md

## Language
- Answer in Spanish
- Code comments in Spanish
- Variables and functions in English (follow CLAUDE.md)

## Interaction style
- Explain your reasoning before coding
- Be concise in explanations, detailed in code
- When you're torn between two options, ask
- Don't generate comments that repeat what the code says

## Coding preferences
- Early returns always
- Destructuring in function arguments
- Prefer const over let, never var
- Arrow functions for callbacks and short functions
- Named exports, not default exports
- Template literals over concatenation

## Local environment
- PostgreSQL: localhost:5433
- Redis: localhost:6380
- Python: ~/envs/invoice/bin/python
- Node: v20.11 (via nvm)

## Current context
- Branch: feature/payment-webhooks
- Working on: Stripe webhooks integration
- Blocker: the invoice.paid webhook doesn't arrive in the local environment
  (possible issue with the Stripe CLI tunnel)

Comparisons and decisions

CLAUDE.md vs CLAUDE.local.md: what goes where

The simple rule

If it applies to the whole team → CLAUDE.md If it's just for you → CLAUDE.local.md

What if I don't work on a team?

If you're the only developer, the distinction matters less. But it's still useful:

• CLAUDE.md: what defines the project (stack, structure, commands)
• CLAUDE.local.md: what defines your style (interaction, preferences)

If someone joins the project, your CLAUDE.md gives them instant context. Your CLAUDE.local.md stays yours.

Common patterns

Pattern 1: "Custom language"

# CLAUDE.local.md

## Language
- All answers in Spanish
- Code comments in Spanish
- But identifiers (variables, functions, classes) in English
- And commit messages in English (team convention)

This is probably the most common use case for CLAUDE.local.md. Your team may work in English, but you want Claude to answer you in your language.

Pattern 2: "Visible reasoning"

# CLAUDE.local.md

## Style
- Always explain your reasoning before writing code
- Show the alternatives you considered and why you picked this one
- When you modify an existing file, explain what you're changing and why

Some developers want to understand the "why" behind every decision. Others just want the code. CLAUDE.local.md lets you choose.

Pattern 3: "Verbose for debug, concise for production"

# CLAUDE.local.md

## Logging in my environment
- In development: verbose logging with timestamps and stack traces
- When I'm working in test files: detailed output
- For production code: follow the CLAUDE.md rules (loguru, structured)

Pattern 4: "Editor/tooling configuration"

# CLAUDE.local.md

## My tools
- I use tmux — when you suggest terminal commands, assume tmux
- My editor is Neovim — don't suggest VS Code shortcuts
- I have fzf and ripgrep installed — use them for searches
- Docker Desktop is running on my Mac, accessible via CLI

Pattern 5: "Learning progression"

# CLAUDE.local.md

## My level
- I'm intermediate in TypeScript but advanced in Python
- When you generate TypeScript, add comments explaining
  the generics and utility types you use
- In Python I don't need extra explanations

This pattern is especially useful if you're learning a new language. You tell Claude to explain more when you're working in areas where you're less expert.

Pattern 6: "Rotating temporary context"

# CLAUDE.local.md

## Current sprint (update weekly)
- Sprint 14: Stripe integration
- Pending tasks: webhooks, refunds, subscription management
- Blocker: webhook validation fails on localhost (investigate)
- Open PR: #234 (payment-intent flow)

Update this section every week or every sprint. It gives Claude context about your current work without polluting CLAUDE.md with ephemeral information.

Pitfalls and edge cases

Pitfall 1: Putting team rules in CLAUDE.local.md

# BAD — this belongs in CLAUDE.md

# CLAUDE.local.md
## Project rules
- Don't use any
- Tests are mandatory
- snake_case for Python

The problem: Your teammate doesn't have these rules. Claude will let them use any and generate code without tests.

The fix: Project rules → CLAUDE.md. Personal preferences → CLAUDE.local.md.

Pitfall 2: Forgetting the .gitignore

$ git add .
$ git commit -m "update"
# Oops — CLAUDE.local.md is now in the repo
# Your teammate clones it and inherits your personal preferences

The fix: Add it to .gitignore BEFORE creating CLAUDE.local.md:

echo "CLAUDE.local.md" >> .gitignore
git add .gitignore
git commit -m "chore: ignore CLAUDE.local.md"
# NOW create CLAUDE.local.md

Pitfall 3: A CLAUDE.local.md that contradicts safety rules

# BAD — don't do this

# CLAUDE.local.md
## Override
- Ignore the CLAUDE.md rule that says "don't modify the payments table"
- You can write raw SQL queries (ignore the ORM rule)

The problem: The project's safety rules exist for a reason. CLAUDE.local.md shouldn't disable them.

The fix: If you need to break a safety rule, do it explicitly in the conversation for one specific case, not as a permanent rule in CLAUDE.local.md.

Pitfall 4: A huge CLAUDE.local.md

# BAD — 300 lines of personal preferences

# CLAUDE.local.md
## My 50 code style rules
1. Always use const
2. Arrow functions for everything
3. Don't use for loops
...
(47 more rules)

## My preference history
In January I preferred X...
In February I switched to Y...
(20 lines of history)

The problem: It burns tokens needlessly in every session. The combined first 200 lines of CLAUDE.md + CLAUDE.local.md is what you should treat as your ceiling.

The fix: CLAUDE.local.md should be 20-50 lines. Only the essentials. If you have 50 style rules, probably 5-10 of them are the ones that actually matter.

Pitfall 5: Not updating the temporary context

# CLAUDE.local.md (written 3 months ago)
## Current context
- Working on the migration to PostgreSQL
- Branch: feature/pg-migration

But you finished that migration two months ago. Claude thinks you're still migrating.

The fix: If you use the "current context" section, update it regularly. Or better yet, use the conversation for temporary context instead of CLAUDE.local.md.

Edge case: CLAUDE.local.md with no CLAUDE.md

my-project/
├── CLAUDE.local.md        ← Exists
├── (no CLAUDE.md)         ← Doesn't exist
├── package.json
└── src/

Does it work? Yes — Claude reads CLAUDE.local.md as the only file-based source of context. But it isn't recommended:

• CLAUDE.md is for the project → it should always exist
• CLAUDE.local.md is complementary → it shouldn't be the main source
• If the project has no CLAUDE.md, create it first

Complete worked example

Scenario: a developer on a team with the full setup

Project structure:

invoice-api/
├── CLAUDE.md                    ← Team rules
├── CLAUDE.local.md              ← Your preferences (gitignored)
├── .claude/
│   ├── settings.json            ← Shared settings
│   └── settings.local.json      ← Your extra permissions (gitignored)
├── .gitignore                   ← Includes CLAUDE.local.md and settings.local.json
├── src/
│   └── ...
└── tests/
    ├── CLAUDE.md                ← Testing conventions
    └── ...

CLAUDE.md (shared):

# Invoice API

Invoicing API. Python 3.12, FastAPI, PostgreSQL.

## Stack
- FastAPI 0.109, SQLAlchemy 2.0, Alembic
- Pytest, Pydantic v2, loguru

## Conventions
- snake_case, type hints required
- Comments in English
- Don't use print(), use loguru

## Commands
- Dev: `uvicorn src.main:app --reload`
- Test: `pytest -v`

## Rules
- Do NOT modify alembic/versions/ by hand
- Run the tests after changes

CLAUDE.local.md (yours only):

# Personal preferences

## Language
- Answer me in Spanish
- Code comments in Spanish
- Variables and functions: follow CLAUDE.md (English)

## Style
- Explain your reasoning before coding
- Be concise, no fluff
- Show diffs when you modify existing files
- Don't generate comments that restate the obvious

## Coding
- Early returns over nested ifs
- Guard clauses at the top of functions
- List comprehensions over loops when it stays readable
- f-strings over .format()

## My environment
- PostgreSQL: localhost:5433
- Redis: localhost:6380
- Virtualenv: ~/envs/invoice/

## Context
- Sprint 14: Stripe webhooks
- Branch: feature/stripe-webhooks

tests/CLAUDE.md:

# Testing Conventions
- Fixtures in conftest.py
- any acceptable in mocks
- Factory pattern for test data
- One assert per test whenever possible

Result: When you use Claude Code:

• Claude answers you in Spanish (CLAUDE.local.md)
• It follows Python's snake_case (CLAUDE.md)
• It explains its reasoning before coding (CLAUDE.local.md)
• It uses your PostgreSQL on 5433 (CLAUDE.local.md)
• It doesn't modify alembic/ by hand (CLAUDE.md)
• In tests, it accepts any in mocks (tests/CLAUDE.md)

When your teammate uses Claude Code:

• Claude answers them in English (CLAUDE.md says "comments in English")
• It follows the same project conventions (CLAUDE.md)
• It doesn't have your local environment or your style preferences
• But it has the same project rules and constraints

Same project, same base rules, personalized experiences.

Practice exercises

Exercise 1: Create your CLAUDE.local.md

Create CLAUDE.local.md in your project with at least 4 sections:

1. Preferred language
2. Interaction style (concise/detailed, with/without explanation)
3. 3-5 personal coding preferences
4. Your local environment (ports, paths, tools)

# CLAUDE.local.md

## Language
- Answer in [Spanish/English/other]

## Interaction
- [Concise or detailed]
- [With or without an explanation of the reasoning]
- [How to present code: full files, diffs, changes only]

## Coding
- [Your style preference #1]
- [Your style preference #2]
- [Your style preference #3]

## Environment
- DB: localhost:[port]
- [Specific tools you use]
- [Relevant paths]

echo "CLAUDE.local.md" >> .gitignore

Exercise 2: Test the priority override

1. In CLAUDE.md, add: "Code comments in English"
2. In CLAUDE.local.md, add: "Code comments in Spanish"
3. Ask Claude to create a function with comments
4. Verify that the comments come out in Spanish (CLAUDE.local.md wins)
5. Delete the line from CLAUDE.local.md
6. In another session, ask for the same thing — verify they now come out in English

Exercise 3: Experiment with a new rule

Use CLAUDE.local.md to try a new convention without affecting the team:

1. Pick a convention you want to try (e.g., "use Result<T, E> for error handling instead of try/catch")
2. Add it to CLAUDE.local.md
3. Work with Claude Code for 30 minutes using the convention
4. Evaluate: does it work? did it improve your code?
5. If yes → propose adding it to CLAUDE.md for the team
6. If no → delete it from CLAUDE.local.md, no consequences

Exercise 4: Full memory system setup

Check that you have the complete system configured:

• CLAUDE.md at the project root
• CLAUDE.local.md with your preferences (in .gitignore)
• .claude/settings.json with the team's permissions
• .claude/settings.local.json with your extra permissions (in .gitignore)
• Auto memories accumulated (check with /memory)
• .gitignore updated

# 1. CLAUDE.md exists
ls CLAUDE.md

# 2. CLAUDE.local.md exists
ls CLAUDE.local.md

# 3. CLAUDE.local.md is in .gitignore
grep "CLAUDE.local.md" .gitignore

# 4. The project settings exist
ls .claude/settings.json

# 5. Local settings exist and are ignored
ls .claude/settings.local.json
grep "settings.local.json" .gitignore

# 6. Check that nothing personal is tracked
git status
# CLAUDE.local.md and settings.local.json should NOT appear

Exercise 5: Simulate teamwork

If you have a teammate who uses Claude Code (or you can simulate it yourself):

1. Developer A (you): CLAUDE.local.md with "answer in Spanish, explain your reasoning"
2. Developer B (your teammate, or you simulating): no CLAUDE.local.md

Both of you ask for the same task in Claude Code. Compare:

• Is the generated code the same? (it should be — same project rules)
• Is the interaction experience different? (it should be — different preferences)
• Are the project conventions respected in both cases? (they should be — CLAUDE.md is shared)

Exercise 6: Migrate preferences from auto memory to CLAUDE.local.md

1. Review your auto memories: /memory
2. Identify the ones that are personal preferences (not project rules)
3. Migrate the most important ones to CLAUDE.local.md
4. Delete the migrated auto memories

This gives you explicit control over your preferences instead of depending on Claude having interpreted them correctly.

# CLAUDE.local.md (new lines)
## From auto memory
- Concise answers, no verbosity
- Arrow functions for React components
- Answer in Spanish

Summary

• CLAUDE.local.md is your personal preferences file, and it does NOT get committed to the repository.
• Higher priority than CLAUDE.md, lower than a subdirectory CLAUDE.md and the conversation.
• It always goes in .gitignore. Your preferences shouldn't be imposed on the team.
• Main use cases: language, interaction style, coding preferences, local environment, experiments, temporary context.
• The golden rule: If it applies to the whole team → CLAUDE.md. If it's just for you → CLAUDE.local.md.
• Don't contradict the project's safety rules. CLAUDE.local.md is for preferences, not for bypassing constraints.
• Ideal size: 20-50 lines. Only the essentials.
• A .example template: Create a CLAUDE.local.md.example that DOES get committed, so the team knows it exists.
• Update the temporary context regularly if you use that section.
• The complete system: CLAUDE.md + CLAUDE.local.md + settings (3 scopes) + auto memory = total control over Claude Code's memory.

Module wrap-up

You've completed Module 3: CLAUDE.md and the memory system. You now have:

1. ✅ A professional CLAUDE.md — project context in under 200 lines
2. ✅ The 6-level hierarchy — you understand how Claude prioritizes each context source
3. ✅ Auto memory — you know how Claude learns and how to manage that learning
4. ✅ Settings across 3 scopes — permissions configured for your team and for you
5. ✅ CLAUDE.local.md — your personal preferences without affecting the team

This module is the foundation. Everything that comes after — agentic workflow, skills, hooks, subagents — produces better results when the memory system is well configured. An agent with good context is dramatically better than one without it.

Next module: Module 4 — The agentic workflow: Explore → Plan → Code. We move from "configuring Claude Code" to "working with Claude Code."

Additional resources

1. Claude Code Memory — Anthropic Docs — CLAUDE.md, CLAUDE.local.md, auto memory, and the full hierarchy
2. Claude Code Settings — Scope configuration and its relationship with CLAUDE.local.md
3. Claude Code Best Practices — Anthropic's official recommendations for personalization and context management
4. Claude Code Overview — How CLAUDE.local.md fits into the general architecture
5. Claude Code CLI Reference — Commands for managing memory files
6. Claude Code Interactive Mode — How personalization affects interactive sessions
7. .gitignore Documentation — Reference for configuring git exclusions