The Setting You Must Not Commit: settings.local.json in Claude Code

July 24, 2026 · Claude Certified Architect (CCA) Prep (part 31)

▶ Watch on YouTube & subscribe to The Stack Underflow

You’ve been tinkering with Claude Code all morning — you flipped on a permission you’re not sure you want the whole team to have, pointed a tool at a local port only your machine runs, and turned off a confirmation prompt because it was slowing you down while you debugged. None of that is a team decision. All of it is currently sitting in a config file. If you git add . and push without thinking, your one-off experiment becomes everyone’s default. This is exactly the trap Domain 3 of the Claude Certified Architect exam tests: not “do you know a file name,” but “do you know which file is safe to commit and which one isn’t.”

The one-sentence version: Claude Code splits settings into a shared, committed file and a personal, gitignored one — and knowing which is which is the difference between a config tweak and an incident.

The question

A personal, experimental setting must NOT be committed to the shared repo. Which file?

• A) .claude/settings.json
• B) .claude/settings.local.json (gitignored)
• C) CLAUDE.md
• D) ~/.bashrc

Pause here and pick before you scroll — this is a CCA-style scenario question, and the value is in reasoning it through, not in seeing the letter.

The answer

The correct answer is B — .claude/settings.local.json.

Claude Code’s project-level configuration deliberately splits into two files that live side by side in the same .claude/ directory but are treated completely differently by version control:

your-repo/
├── .claude/
│   ├── settings.json          ← SHARED, committed to the repo
│   │                             team-wide permissions, hooks, model config
│   │
│   └── settings.local.json    ← PERSONAL, gitignored automatically
│                                  your experiments, your machine, your habits
│
└── .gitignore                 ← already excludes .claude/settings.local.json
                                   (Claude Code scaffolds this for you)

The mechanism is the beat-sheet rule from the episode: “Settings hierarchy: local (personal) vs shared (project).” settings.json is the file your team reviews in a pull request — it’s the contract for how everyone on the repo runs Claude Code. settings.local.json is the file that exists specifically so you can override or extend that contract on your own machine without touching the contract itself. When Claude Code scaffolds a project’s .claude/ folder, it adds settings.local.json to .gitignore for you, so the personal file is structurally prevented from ending up in a commit unless someone goes out of their way to force-add it.

The settings actually merge at runtime — Claude Code reads both files and layers your local overrides on top of the shared project settings — so you still get the team’s baseline plus whatever you’re experimenting with locally. What changes is not the behavior, it’s the blast radius: a broken experiment in your local file breaks nothing for anyone else.

Why the other options fail

• A) .claude/settings.json is the tempting wrong answer precisely because it lives in the same directory and looks like “the settings file.” But it’s the shared one — it’s meant to be committed and reviewed. Putting a personal, experimental permission here means the next git pull hands your untested change to every teammate, with no review step catching it.
• C) CLAUDE.md is a different mechanism entirely: it’s memory (persistent instructions and context the model reads), not settings (permissions, hooks, and tool configuration the harness enforces). Even the personal variant of memory — your user-level ~/.claude/CLAUDE.md — isn’t the file for a permission tweak. Memory and settings solve different problems, and this question is specifically about settings.
• D) ~/.bashrc isn’t a Claude Code concept at all. It’s your shell’s startup file — it could set an environment variable Claude Code happens to read, but it has no awareness of Claude Code’s permission model, hooks, or tool configuration, and it says nothing about what does or doesn’t get committed to this repo.

The concept behind it

The pattern here — a shared, committed config file paired with a personal, gitignored override file — isn’t unique to Claude Code. It’s the same shape as .env and .env.local in web frameworks, or settings.json and settings.local.json in editors like VS Code. Once you recognize the pattern, you can predict the answer to a whole class of questions without memorizing Claude Code’s specific file names:

The exam-relevant instinct to build is: whenever a scenario mentions “personal,” “experimental,” “just for me,” or “shouldn’t affect the team,” look for the file that’s gitignored by default — not the one that merely sounds personal. The local settings file exists so individual engineers can try a permission, a hook, or a tool configuration without asking for a PR approval first. That’s a deliberate design choice, not an accident of naming: it lowers the cost of experimentation while keeping the shared contract stable. If your team wants an experiment to graduate into policy, the move is to promote the setting from settings.local.json into settings.json explicitly, as its own reviewed change — not to let it leak in through a careless commit.

This also connects to a broader theme across Domain 3: Claude Code’s configuration surface is organized by scope, not just by file type. Memory (CLAUDE.md) has project and user scope. Settings (settings.json) have project, local, and — as later questions in this same practice set cover — managed/enterprise scope, each sitting at a different level of a precedence ladder. Learning the scope axis once means you can reason through memory questions, settings questions, and permission-precedence questions with the same mental model instead of memorizing each answer independently.

FAQ

Is .claude/settings.local.json gitignored automatically, or do I have to add it myself? Claude Code scaffolds the ignore rule for you when it sets up the .claude/ directory in a project, so in a normal setup you don’t need to add it manually. Still, verify the current .gitignore in any repo you inherit — if someone customized the scaffolding or the repo predates that default, the exclusion might be missing and worth adding explicitly.

What actually happens if I accidentally commit settings.local.json? Git will track it going forward, and your personal, possibly half-finished settings become the shared baseline the next time someone pulls. The fix is a normal git history cleanup (remove it from tracking, confirm the .gitignore entry is in place, commit that fix) — it’s not a Claude Code-specific problem, just a standard “don’t commit local config” mistake with Claude Code’s particular file names.

Do settings.json and settings.local.json fully replace each other, or do they merge? They merge. Claude Code layers your local file’s values on top of the shared project file at runtime, so you get the team’s baseline settings plus whatever you’ve added or overridden locally — you don’t lose the shared config by having a local one.

Does this same local-vs-shared split show up anywhere else in Claude Code? Yes — it’s worth checking whether the current docs extend the same personal/shared pattern to other config surfaces (like local vs. project-level command or agent directories), since Claude Code’s configuration model consistently favors separating “reviewed and shared” from “personal and disposable.”

Not affiliated with, authorized, or endorsed by Anthropic. “Claude” and “Claude Certified Architect” are trademarks of Anthropic. These are original practice questions for study, not real exam content — verify current exam details on Anthropic’s official pages.

Where this fits in the CCA series

This question sits in Domain 3 — Claude Code Configuration & Workflows (20% of the exam), the domain that tests live, day-to-day Claude Code behavior rather than model theory. If you’re just starting the practice series, the Claude Certified Architect (CCA) Exam Guide lays out all five domains on one diagram, including current logistics (Pearson VUE, $125, retakes, 60 questions in 120 minutes, pass at 720/1000 as of mid-2026 — verify on Anthropic’s official pages before you register).

Within Domain 3, this question pairs closely with a few siblings:

• A Rule for You, Not Your Team: Local vs Shared Claude Code Settings — the deeper dive into exactly this split, beyond just the “don’t commit it” framing.
• Where Does a Team Convention Live? Project CLAUDE.md Explained — the memory-hierarchy counterpart to this settings question; useful for keeping “memory” and “settings” straight under exam pressure.
• Enterprise Denies, You Allow — Who Wins? Claude Code Permission Precedence — what happens when your local settings and a higher-scoped policy actually conflict, one level up from this question.
• Allow npm test, Gate Destructive Git: Claude Code Permissions — the permission-rule mechanics that often live inside the settings files this question is about.

Browse the full library at all tutorials.