2026-09-10  ·  configuration · devops · ai · claudecode

I Put a Setting in My Project Config and It Did Nothing

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

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

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

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

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 } } }

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:

/** そのファイルからは効かないスコープのキー（一部。確実なものだけ） */

"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

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

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

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