DEV Community

Cover image for I Put a Setting in My Project Config and It Did Nothing
quintetkit
quintetkit

Posted on

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

#claudecode #ai #configuration #devops

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

Top comments (0)