Debug your configuration changeddebug-your-config
Nearest release: v2.1.299, published an hour before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 14 Oct 2026 01:27 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 20 Oct 2026 18:37 UTC.
Upstream edited
Recorded here
Lines+39added
Lines−45removed
From line
29
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits22to this page, all time
The whole hunk
from line 29, old and new numbered
/
from line 29
2929
3030Adherence drops when an instruction is vague enough to interpret multiple ways, when two files give conflicting direction, or when the file has grown long enough that individual rules get less attention. [Write effective instructions](/docs/en/memory#write-effective-instructions) covers the specificity, size, and structure patterns that keep adherence high.
3131
32<Note>
33 CLAUDE.md and permissions solve different problems. CLAUDE.md tells Claude how your project works so it makes good decisions. [Permissions](/docs/en/permissions) and [hooks](/docs/en/hooks) enforce limits regardless of what Claude decides. Use CLAUDE.md for "we do it this way here." Use permissions or hooks for security boundaries and anything that must never happen, where you need a guarantee instead of guidance.
34</Note>
32> [!NOTE]
33>
34> CLAUDE.md and permissions solve different problems. CLAUDE.md tells Claude how your project works so it makes good decisions. [Permissions](/docs/en/permissions) and [hooks](/docs/en/hooks) enforce limits regardless of what Claude decides. Use CLAUDE.md for "we do it this way here." Use permissions or hooks for security boundaries and anything that must never happen, where you need a guarantee instead of guidance.
3535
3636## Check resolved settings
3737
from line 86
8686
8787If the problem persists in safe mode, or your settings themselves are suspect, start a session with none of your own configuration and check whether the problem follows.
8888
89<Steps>
90 <Step title="Create an empty directory and change into it">
91 In your shell, with no Claude Code session running, create the directory and move into it:
89**1. Create an empty directory and change into it**
9290
93 <Tabs>
94 <Tab title="Bash or Zsh">
95 ```bash theme={null}
96 mkdir -p ~/claude-clean/empty && cd ~/claude-clean/empty
97 ```
98 </Tab>
91In your shell, with no Claude Code session running, create the directory and move into it:
9992
100 <Tab title="PowerShell">
101 ```powershell theme={null}
102 New-Item -ItemType Directory -Force "$HOME/claude-clean/empty" | Out-Null
103 Set-Location "$HOME/claude-clean/empty"
104 ```
105 </Tab>
106 </Tabs>
107 </Step>
93**Bash or Zsh**
10894
109 <Step title="Start Claude Code with a clean configuration directory">
110 From the same shell, set [`CLAUDE_CONFIG_DIR`](/docs/en/env-vars) to a fresh directory in place of `~/.claude`, and pass [`--setting-sources user`](/docs/en/cli-reference#cli-flags) to turn off project configuration such as `.claude/settings.json`, `CLAUDE.md`, and `.mcp.json`:
95```bash theme={null}
96mkdir -p ~/claude-clean/empty && cd ~/claude-clean/empty
97```
11198
112 <Tabs>
113 <Tab title="Bash or Zsh">
114 The variable applies to this one launch.
99**PowerShell**
115100
116 ```bash theme={null}
117 CLAUDE_CONFIG_DIR=~/claude-clean/config claude --setting-sources user
118 ```
119 </Tab>
101```powershell theme={null}
102New-Item -ItemType Directory -Force "$HOME/claude-clean/empty" | Out-Null
103Set-Location "$HOME/claude-clean/empty"
104```
120105
121 <Tab title="PowerShell">
122 The variable stays set for the rest of this PowerShell session, so later `claude` launches in the same window keep using the clean directory. To return to your usual directory, run `Remove-Item Env:CLAUDE_CONFIG_DIR` before the next launch.
106**2. Start Claude Code with a clean configuration directory**
123107
124 ```powershell theme={null}
125 $env:CLAUDE_CONFIG_DIR = "$HOME/claude-clean/config"
126 claude --setting-sources user
127 ```
128 </Tab>
129 </Tabs>
108From the same shell, set [`CLAUDE_CONFIG_DIR`](/docs/en/env-vars) to a fresh directory in place of `~/.claude`, and pass [`--setting-sources user`](/docs/en/cli-reference#cli-flags) to turn off project configuration such as `.claude/settings.json`, `CLAUDE.md`, and `.mcp.json`:
130109
131 On the first launch, you go through the first-run setup screens again, a sign that the clean configuration directory is in effect. Managed settings still apply, and [connectors](/docs/en/mcp#use-mcp-servers-from-claude-ai) still load if you log in with a claude.ai account.
132 </Step>
110**Bash or Zsh**
133111
134 <Step title="Reproduce the problem">
135 Repeat what triggered the problem in the clean session:
112The variable applies to this one launch.
136113
137 * **Problem gone**: the cause is in your user or project configuration. Copy `~/.claude.json` and the files in `~/.claude` into `~/claude-clean/config` one at a time. If none brings the problem back, go to your project directory in the same shell and start Claude Code without `--setting-sources user`. In Bash or Zsh, run `CLAUDE_CONFIG_DIR=~/claude-clean/config claude`. In PowerShell, the variable is still set, so run `claude`.
138 * **Problem persists**: the cause is outside your user and project configuration. Run `/status` in the session to check for managed settings, check your shell for [environment variables](/docs/en/env-vars), then see [Troubleshooting](/docs/en/troubleshooting).
139 </Step>
140</Steps>
114```bash theme={null}
115CLAUDE_CONFIG_DIR=~/claude-clean/config claude --setting-sources user
116```
117
118**PowerShell**
119
120The variable stays set for the rest of this PowerShell session, so later `claude` launches in the same window keep using the clean directory. To return to your usual directory, run `Remove-Item Env:CLAUDE_CONFIG_DIR` before the next launch.
121
122```powershell theme={null}
123$env:CLAUDE_CONFIG_DIR = "$HOME/claude-clean/config"
124claude --setting-sources user
125```
126
127On the first launch, you go through the first-run setup screens again, a sign that the clean configuration directory is in effect. Managed settings still apply, and [connectors](/docs/en/mcp#use-mcp-servers-from-claude-ai) still load if you log in with a claude.ai account.
128
129**3. Reproduce the problem**
130
131Repeat what triggered the problem in the clean session:
132
133* **Problem gone**: the cause is in your user or project configuration. Copy `~/.claude.json` and the files in `~/.claude` into `~/claude-clean/config` one at a time. If none brings the problem back, go to your project directory in the same shell and start Claude Code without `--setting-sources user`. In Bash or Zsh, run `CLAUDE_CONFIG_DIR=~/claude-clean/config claude`. In PowerShell, the variable is still set, so run `claude`.
134* **Problem persists**: the cause is outside your user and project configuration. Run `/status` in the session to check for managed settings, check your shell for [environment variables](/docs/en/env-vars), then see [Troubleshooting](/docs/en/troubleshooting).
141135
142136## Check common causes
143137
No line in this hunk matches that.