What you will be able to do
- Choose the right CLAUDE.md scope for team, personal, and organization-wide instructions
- Predict when a nested CLAUDE.md file enters Claude's context
- Place a settings key in the scope that wins, including rules developers must not weaken
- Pick a permission mode for a task and know where each mode can be set
Key concept
Scope decides reach and authority — Every CLAUDE.md file and settings file in Claude Code belongs to a scope: managed, user, project, or local. The scope controls who the file affects and whether a different file can override it. Most configuration mistakes come from putting the right content in the wrong scope.
1.Four places a CLAUDE.md can live
A CLAUDE.md file holds standing instructions that Claude Code loads into every session, so you don't have to repeat a correction you already made last week. You write it in plain markdown, and where you save it decides who it reaches. There are four scopes. The managed policy file is installed by IT and applies to everyone in the organization. ~/.claude/CLAUDE.md holds your personal preferences for all your projects. ./CLAUDE.md or ./.claude/CLAUDE.md holds project instructions that the team shares through source control. ./CLAUDE.local.md holds your personal notes for one project. Running /init generates a starter project file.
| Scope | Location | Shared with |
|---|---|---|
| Managed policy | /etc/claude-code/CLAUDE.md (Linux and WSL); /Library/Application Support/ClaudeCode/CLAUDE.md (macOS) | All users in organization |
| User instructions | ~/.claude/CLAUDE.md | Only you (all projects) |
| Project instructions | ./CLAUDE.md or ./.claude/CLAUDE.md | Team members via source control |
| Local instructions | ./CLAUDE.local.md | Only you (current project) |
The local file fits personal sandbox URLs and preferred test data. It lives at the repository root, applies only to that repository, and is meant to be listed in .gitignore so it never reaches a teammate. The other places people try have problems. A heading in the shared CLAUDE.md is still committed and still loaded for everyone. ~/.claude/CLAUDE.md follows you into every project. The env block of a committed .claude/settings.json sets environment variables for the whole team, and it is not where instructions go.
Writing a CLAUDE.md well is mostly about being specific and short. "Run npm test before committing" is better than "Test your changes". Keep each file under about 200 lines, because longer files cost more context and Claude follows them less reliably. Splitting a file with @path imports makes it easier to organize, but it doesn't make it cheaper: an imported file loads together with the file that imports it. Imports, path-scoped .claude/rules/, and AGENTS.md handling are covered in customizing Claude Code. Use /memory to open and edit the CLAUDE.md files a session is using.
Checkpoint 1 of 8· Match them up
Match each CLAUDE.md location to who its instructions reach.
Tap a term, then the definition that fits it.
Where you save a CLAUDE.md decides who it reaches. The managed policy file covers the whole organization. The user file follows you into all your projects. The project file is committed and shared with the team. The local file is personal to one repository and is gitignored, which makes it the place for things like sandbox URLs.
“Local instructions | ./CLAUDE.local.md | Personal project-specific preferences; add to .gitignore | Your sandbox URLs, preferred test data | Only you (current project)”Source: code.claude.com
Checkpoint 2 of 8· Exam question
A developer wants their personal sandbox URLs and local test preferences applied by Claude Code in one repository only. The notes must not be committed and must not affect teammates. Where should they go?
Correct answer: D — Put them in a CLAUDE.local.md file at the repository root, and add an entry for that file to the repository's .gitignore.
- A. The env block defines environment variables for Claude Code sessions; it is not where instruction-style notes go. The project .claude/settings.json is also committed, so teammates would receive the values, and prefixing the keys does not change that.
- B. The repository's CLAUDE.md is committed and loaded in every teammate's sessions. A personal heading does not keep the notes private, and asking teammates to skip the section does not stop Claude from reading it.
- C. ~/.claude/CLAUDE.md is user-level memory that loads for all of the developer's projects, not one repository. An instruction to ignore the notes elsewhere depends on Claude following it, so the notes are not scoped to a single repository.
- D. CLAUDE.local.md at the repository root is read alongside the project's CLAUDE.md for that repository only. Listing it in .gitignore keeps the personal notes out of commits, so teammates are unaffected. This meets both constraints.
2.When each CLAUDE.md file enters the context
CLAUDE.md files load at two different times. At session start, Claude Code reads every CLAUDE.md in the working directory and in each directory above it. A CLAUDE.md lower in the tree is not scanned at launch. It loads the first time Claude reads a file in that folder. In the monorepo example, a session spent fixing a CSV export in packages/ingest never pays for the billing conventions unless Claude opens a billing file. Relaunching from the subdirectory isn't needed to get those conventions either, because touching the folder is enough. /memory is an editor for these files, not a way to load them.
Because files from several scopes and directories end up in one context, a contradiction between them is a real failure. Claude doesn't apply a precedence rule between conflicting sentences. It may simply follow one of them. Reviewing root, nested, and rules files together and deleting outdated lines is the only way to fix this.
Checkpoint 3 of 8· Check yourself
In a monorepo, the root CLAUDE.md says "use 4-space indentation". An older line in packages/billing/CLAUDE.md says "use 2-space indentation". Claude is now editing billing files, so both files are in context. What happens, and what is the right fix?
CLAUDE.md content is guidance, and Claude Code doesn't apply a precedence rule between conflicting sentences. Claude may follow either instruction. The fix is to review the root, nested and rules files together and remove the instruction that is out of date.
“Consistency: if two instructions contradict each other, Claude may pick one arbitrarily.”Source: code.claude.com
Checkpoint 4 of 8· Exam question
A monorepo has a root CLAUDE.md plus packages/billing/CLAUDE.md with billing-specific conventions. A developer starts Claude Code at the repo root and asks about a CSV export bug in packages/ingest. Which statement describes how the billing file is treated?
Correct answer: A — It is loaded when Claude first reads a file under packages/billing, since subdirectory files are added as their folder is touched.
- A. CLAUDE.md files in subdirectories are not read at launch. Claude Code adds them to context when it reads files in that subtree. Because the work stays in packages/ingest, the billing conventions are not loaded until Claude touches packages/billing.
- B. Relaunching is not required. At startup Claude Code reads the CLAUDE.md in the launch directory and in its parent directories, plus user-level memory. A nested file such as the billing one is added automatically once Claude reads files in its folder, even though the session started at the repo root.
- C. Nested CLAUDE.md files need no manual selection. The /memory command is for viewing and editing memory files, not for choosing which nested files get loaded. Loading happens automatically when Claude works with files under the subdirectory.
- D. Claude Code does not scan the tree below the launch directory at startup. It loads the launch directory's file and its parents' files, then adds subdirectory files lazily. Preloading every nested file would bloat context in a large monorepo, and the billing file is irrelevant to an ingest bug.
3.settings.json scopes and which value wins
CLAUDE.md shapes what Claude does. settings.json configures Claude Code itself: permission rules, default model, hooks, environment variables, and plugins. Settings use the same four scopes as CLAUDE.md, but a key that appears in several files resolves by a strict order. Managed settings come first. Next is JSON passed with --settings for one session. Then come .claude/settings.local.json, the shared .claude/settings.json, and finally ~/.claude/settings.json.
| Scope | File | Use it for |
|---|---|---|
| Managed | managed-settings.json, MDM policy, or server-managed settings | Security policy and compliance requirements |
| Command line | --settings <file-or-json> | One session only |
| Project local | ./.claude/settings.local.json | Personal overrides for one project, and testing before you share |
| Shared project | ./.claude/settings.json | Team permissions, hooks, plugins, and environment variables |
| User | ~/.claude/settings.json | Theme, editor mode, default model, your own permission rules |
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": [
"Bash(npm run lint)",
"Bash(npm run test *)"
],
"deny": [
"Read(./.env)",
"Read(./.env.*)"
]
}
}Claude Code writes the local file on its own. When you answer a Bash permission prompt with "Yes, and don't ask again", it saves that approval to .claude/settings.local.json as an allow rule. The first time it writes that file in a git repository, it adds the file to your global git excludes so you don't commit it by accident. If you create the file by hand, add it to .gitignore yourself. Settings errors are handled per file. A file with invalid JSON triggers a Settings Error dialog at startup. A single malformed permission rule is skipped with a warning, and the rest of the file stays in effect.
For a rule that no developer may weaken, only one scope works. User, project, and local files are files that developers can edit themselves. A committed .claude/settings.json protected by branch review still sits below the local file in the stack, and a configuration-management job that resets ~/.claude/settings.json is still guarding a file the developer owns. A managed permissions.deny entry, such as one blocking Bash(curl:*), is placed in a system directory through device management, and no file a developer controls can override it. Organizations use managed CLAUDE.md for behavioral guidance. Managed settings are where tool blocking actually gets enforced. Broader least-privilege design is covered in deterministic guardrails.
| Concern | Configure in |
|---|---|
| Block specific tools, commands, or file paths | Managed settings: permissions.deny |
| Enforce sandbox isolation | Managed settings: sandbox.enabled |
| Code style and quality guidelines | Managed CLAUDE.md |
| Behavioral instructions for Claude | Managed CLAUDE.md |
Checkpoint 5 of 8· Check yourself
Your security team says no developer may be able to let Claude Code run curl, even by editing their own configuration. Which setup meets that requirement?
Developers can edit the user, project and local settings files, and .claude/settings.local.json ranks above the committed project file. A managed CLAUDE.md is only guidance that Claude reads. Only a managed permissions.deny entry cannot be overridden by any file a developer controls.
“Nothing in your own settings files or --settings overrides a managed key”Source: code.claude.com
Checkpoint 6 of 8· Exam question
A security team wants a rule denying Bash(curl:*) that no developer can weaken, including through a personal .claude/settings.local.json in their own checkout. Where should the rule be defined?
Correct answer: D — In the managed policy settings file, rolled out to developer machines by IT through device management into a system-level directory.
- A. User settings are the lowest-precedence scope. A developer's project-level settings.local.json or command-line flags still take priority over a restored user file, so the rule can be weakened.
- B. Project settings rank below local project settings and command-line arguments. Branch protection governs only the committed file, and a developer's untracked settings.local.json never goes through review.
- C. CLAUDE.md is guidance Claude reads, not an enforcement mechanism, and it does not override settings scopes. Pull request review does not turn an instruction into a block on curl.
- D. Managed policy settings have the highest precedence and cannot be overridden by user, project, or local settings files. Deploying them to a system-level path through IT makes the deny rule non-weakenable.
4.Permission modes and where to set them
A permission mode sets how much Claude may do before it stops to ask you. There are six modes, ordered here from most cautious to least. default (shown as Manual) runs only reads without asking. acceptEdits adds file edits and common filesystem commands such as mkdir and mv. plan lets Claude explore but blocks edits until you approve a plan. auto runs everything, with a classifier doing background safety checks. dontAsk denies anything that would prompt, apart from pre-approved tools. bypassPermissions runs everything and is meant only for isolated containers and VMs.
| Mode | Runs without asking | Best for |
|---|---|---|
| default | Reads only | Reviewing every action yourself, sensitive work |
| acceptEdits | Reads, file edits, and common filesystem commands | Iterating on code you're reviewing |
| plan | Reads; edits wait for an approved plan | Exploring a codebase before changing it |
| auto | Everything, with background safety checks | Long tasks, reducing prompt fatigue |
| dontAsk | Reads in working directories and pre-approved tools; the rest is denied | Locked-down CI and scripts |
| bypassPermissions | Everything | Isolated containers and VMs only |
The starting mode is resolved in a fixed order. The --permission-mode flag (or --dangerously-skip-permissions) comes first, then permissions.defaultMode from a settings file, then the built-in default. The built-in default depends on how you run Claude Code. Terminal and VS Code sessions start in auto on v2.1.283 and later, while claude -p and the Agent SDK start in default. Project files get one restriction: auto or bypassPermissions written into .claude/settings.json or .claude/settings.local.json doesn't take effect. Without that restriction, a cloned repository could switch on hands-off mode for whoever opens it. Administrators can go further. Setting permissions.disableAutoMode or permissions.disableBypassPermissionsMode to "disable" in managed settings removes the mode for everyone.
During a session, you switch modes with Shift+Tab in the CLI, or with the mode control in VS Code or Desktop. /plan enters plan mode directly and can take a task, for example /plan fix the auth bug. Some calls prompt in every mode. Tools matched by an explicit ask rule are one example, and AskUserQuestion is another. Writing allow, ask, and deny rules is covered in customizing Claude Code, and /permissions opens a dialog for viewing those rules by scope.
dontAsk is not part of the cycle. Start the session with --permission-mode dontAsk, which is typical for a locked-down CI run combined with an --allowedTools allowlist.
Checkpoint 7 of 8· Match them up
Match each permission mode to the situation it is built for.
Tap a term, then the definition that fits it.
The modes run from most cautious to least. Manual allows only reads, acceptEdits adds edits and common filesystem commands, plan blocks edits until a plan is approved, dontAsk denies whatever is not pre-approved, and bypassPermissions runs everything, so it belongs only in isolated environments.
“bypassPermissions | Everything | Isolated containers and VMs only”Source: code.claude.com
Checkpoint 8 of 8· Check yourself
A teammate commits "defaultMode": "bypassPermissions" under permissions in the repository's .claude/settings.json. You clone the repository and start Claude Code in a terminal without a --permission-mode flag. Which mode does the session start in?
Project and local settings files can't turn on bypassPermissions, so a cloned repository can't make sessions run unattended. Claude Code ignores the value and starts the session in Manual mode. An auto value in those files is also ignored, but in that case the session falls back to the built-in default.
“If you set "bypassPermissions" in those two files, it doesn’t take effect either, and the session starts in Manual mode.”Source: code.claude.com
Sources5
Sources
(5)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://code.claude.com/docs/en/memoryOfficial docs
“Personal project-specific preferences; add to .gitignore”
↩︎ Four places a CLAUDE.md can live“Imports help you organize a long file but don’t reduce its context cost”
↩︎ Four places a CLAUDE.md can live“if two instructions contradict each other, Claude may pick one arbitrarily”
↩︎ When each CLAUDE.md file enters the context“Block specific tools, commands, or file paths | Managed settings: permissions.deny”
↩︎ settings.json scopes and which value wins“Local instructions | ./CLAUDE.local.md | Personal project-specific preferences; add to .gitignore | Your sandbox URLs, preferred test data | Only you (current project)”
↩︎ Checkpoint“Consistency: if two instructions contradict each other, Claude may pick one arbitrarily.”
↩︎ Checkpoint - 2.https://code.claude.com/docs/en/commandsOfficial docs
“Edit CLAUDE.md files, enable or disable auto memory, and view auto memory entries”
↩︎ Four places a CLAUDE.md can live - 3.https://support.claude.com/en/articles/14553240-give-claude-context-claude-md-and-better-promptsOfficial docs
“loaded on demand when Claude reads files in that directory, not at session start”
↩︎ When each CLAUDE.md file enters the context“The files at and above your working directory are read at session start”
↩︎ Exam trap 2 - 4.https://code.claude.com/docs/en/settingsOfficial docs
“Claude Code applies it above your user, project, and local files and below managed settings.”
↩︎ settings.json scopes and which value wins“Claude Code saves that permission approval here as an allow rule.”
↩︎ settings.json scopes and which value wins“Nothing in your own settings files or --settings overrides a managed key”
↩︎ Key concept“Nothing in your own settings files or --settings overrides a managed key”
↩︎ Exam trap 1“Nothing in your own settings files or --settings overrides a managed key”
↩︎ Checkpoint - 5.https://code.claude.com/docs/en/permission-modesOfficial docs
“Switch permission modes with Shift+Tab in the CLI, the mode indicator in VS Code, or the mode selector in Desktop.”
↩︎ Permission modes and where to set them“dontAsk: never appears in the cycle; set it with --permission-mode dontAsk”
↩︎ Permission modes and where to set them“Claude Code blocks edits until you approve a plan”
↩︎ Permission modes and where to set them“it doesn’t take effect either, and the session starts in Manual mode”
↩︎ Exam trap 3“bypassPermissions | Everything | Isolated containers and VMs only”
↩︎ Checkpoint“If you set "bypassPermissions" in those two files, it doesn’t take effect either, and the session starts in Manual mode.”
↩︎ Checkpoint