把配置写进项目 settings.json 却毫无效果：Claude Code 设置的作用域陷阱

I put autoMode in .claude/settings.json, committed it, and it had no effect. The JSON was valid. Startup printed no warning. --debug said nothing. I spent a while assuming I had the semantics wrong before I found the actual reason: that key does not apply from that file. Settings have a scope, and the scope is not in the file Claude Code's settings reference has a column I had never read carefully. Every key names the scopes it applies from. Counting it: Any file 152 keys Managed 39 keys only from managed settings User or managed 23 keys ~/.claude/settings.json, or managed User, local, or managed 3 keys settings.local.json but not settings.json Global config 6 keys ~/.claude.json only ------------------------------------ 223 keys, of which 71 are scoped Enter fullscreen mode Exit fullscreen mode 71 of 223. Put one of those in a project's .claude/settings.json and it is not an error, produces no warning, and does nothing. The ones I would expect people to hit: autoMode user or managed autoMode.classifyAllShell user or managed skipAutoPermissionPrompt user or managed useAutoModeDuringPlan user, local, or managed spellcheck user or managed sandbox.network.strictAllowlist user or managed sandbox.filesystem.disabled user or managed diffTool ~/.claude.json only autoConnectIde ~/.claude.json only Enter fullscreen mode Exit fullscreen mode If you run several agents at once you get more approval prompts, so loosening autoMode is the obvious move — and the obvious place to put it is the project config you already have open. That is the one place it does not work. The row that will cost you a debugging session User, local, or managed 3 keys Enter fullscreen mode Exit fullscreen mode settings.local.json is a different scope from settings.json. Three keys apply from the local one and not from the shared one: useAutoModeDuringPlan syncClaudeAiSkills skipDangerousModePermissionPrompt So: you put one in settings.local.json, it works. Later you move it into the shared file so the team gets it, and it silently stops. Nothing changed except which file it lives in. This is a manufactured "works on my machine" — with the unusual property that the person who wrote it is the one for whom it works. Nested keys are scoped by their full dotted name The documentation names them the way you would write a path, not the way you would write JSON: sandbox.network.strictAllowlist ← this is what is scoped sandbox ← this is not Enter fullscreen mode Exit fullscreen mode Which matters if you go looking. I wrote a checker for this and inspected only the top level of the settings object, so this: { "sandbox": { "network": { "strictAllowlist": true } } } Enter fullscreen mode Exit fullscreen mode produced nothing at all. 20 dotted keys were invisible to it, 12 of them sandbox.*. How I found out how wrong I was I had been maintaining this list by hand, copied out of the documentation, with a comment I wrote myself: /** そのファイルからは効かないスコープのキー（一部。確実なものだけ） */ Enter fullscreen mode Exit fullscreen mode "Some. Only the certain ones." I knew it was partial. I did not know how partial. actual I had Managed 39 14 User or managed 23 0 ← the whole row Global config 6 6 Enter fullscreen mode Exit fullscreen mode The user or managed row was missing entirely — 23 keys, including autoMode, the one that started this. I had read the table by grouping it: Managed is for organisations deploying policy, which is not my situation, so I skipped past it — and past the row sitting next to it, which turned out to mean "applies from your own ~/.claude/settings.json" and was the row I most needed. Reading it row by row would have worked. Reading it by category is what failed. So it is generated now, straight from the scope column, and the count comes out of the same place the checker reads. Checking yours npx @quintetkit/ccheck Enter fullscreen mode Exit fullscreen mode warn .claude/settings.json:63 `autoMode` applies from user or managed settings only. It has no effect from this file. why: https://code.claude.com/docs/en/settings-reference Enter fullscreen mode Exit fullscreen mode One thing that took a second pass to get right: ~/.claude/settings.json is the user scope. Deciding "this key doesn't apply here" from the path alone would report a correctly placed autoMode on the machine of anyone who runs it against their home directory — including mine, which has autoMode in it. So the scope is decided by whether the directory being scanned is your home, not by what the path looks like. The full list of 71, and the same list as JSON if you would rather check the claim than trust it: https://quintetkit.github.io/en/reference/claude-code-settings-scope.html I publish the configuration for splitting Claude Code into separate personas — Architect, Coder, Reviewer, Conflict Resolver — under MIT. Copy it, run ./setup.sh, and it works. It does not depend on your tech stack. https://github.com/quintetkit/quartet I built one real tool using nothing but this workflow. Every Issue, PR, review and merge is still there. The parts that went wrong were not deleted. https://github.com/quintetkit/mdlinkcheck The version that adds a UI Designer persona, review criteria, a per-Issue parallel execution script and a 11-chapter guide is on the product page. The full kit — five personas, the scripts and the complete guide — is available here. https://quintetkit.gumroad.com/l/quintet