Claude Code 설정 파일 우선순위: settings.json 네 곳 중 어디에 둘까

Claude Code 설정 문서를 읽다가 그냥 넘기기 어려운 한 줄을 만났습니다. 로컬 설정 파일은 보통 저장소 루트에서 읽히는데, Windows에서는 시작한 폴더에서 읽힌다는 예외였어요.

정말 그런지 해 봤습니다. 저장소 루트의 .claude/settings.local.json에 {"model":"haiku"}를 적어 두고, Windows에서 하위 폴더로 들어가 claude를 띄웠습니다.

Haiku가 아니라 기본 모델(Opus 5.5)로 시작하더라고요. 루트에서 띄우면 Haiku로 잘 시작했고요.

설정 우선순위 표만 외워서는 이런 일을 설명할 수 없습니다. “어느 파일이 이기나” 전에 “어느 파일이 애초에 읽히나”를 먼저 봐야 하거든요.

이 글은 그 두 가지를 차례로 정리한 것입니다. 공식 문서는 2026년 9월 23일 기준이고, 시작 폴더에 따른 동작은 Ubuntu 24.04 · Claude Code 2.1.280과 Windows 11 · PowerShell 5.1 · Claude Code 2.1.286 테스트 환경에서 직접 확인했습니다. Settings Error 대화 상자와 /status의 Setting sources 표시는 10월 13일 Windows 11 · 2.1.296에서 확인했어요.

하위 폴더에서 띄웠더니 루트의 설정이 무시됐다

확인한 방법은 간단합니다. 빈 저장소의 루트 로컬 파일에 {"model":"haiku"}만 적고, 사용자 설정에는 model을 두지 않은 채 시작 폴더만 바꿔 가며 띄웠습니다.

시작한 폴더	있는 설정 파일	시작한 모델
저장소 루트	루트 로컬 = haiku	claude-haiku-4-5-20251001
sub	루트에만 haiku	claude-opus-5-5(기본값)
sub	sub 로컬 = sonnet	claude-sonnet-5-5
sub	위에 더해 sub 공유 = opus	claude-sonnet-5-5

두 번째 줄이 문서의 그 한 줄입니다. 하위 폴더에서 시작하니 루트의 로컬 파일을 건너뛰었어요. 네 번째 줄은 같은 폴더 안에서는 로컬이 공유를 이긴다는, 우선순위 표 그대로의 결과고요.

문서의 규칙을 정확히 옮기면 이렇습니다. 로컬 파일은 원래 git 저장소의 하위 폴더에서 시작해도 저장소 루트의 파일을 읽고 씁니다(워크트리라면 주 체크아웃 루트). 그런데 다음 경우에는 공유 파일처럼 시작한 폴더에 머뭅니다.

• 저장소 밖이거나, 저장소 루트가 홈 폴더일 때
• Windows일 때
• 루트나 그 .git·.claude 중 하나라도 내 사용자 소유가 아닐 때

실제로 체감되는 건 이겁니다. Windows에서는 하위 폴더마다 승인이 따로 쌓여요.

권한 프롬프트에서 “다시 묻지 않기”를 골라 놔도, 다른 폴더에서 띄우면 또 물어봅니다. 같은 일을 겪고 있다면 버그가 아니라 문서에 적힌 동작입니다.

공유 파일은 OS와 상관없이 시작한 폴더 기준

공유 파일 .claude/settings.json은 Ubuntu에서도 시작한 폴더에서 읽혔습니다. 이걸 확인할 때 쓴 요령이 하나 있는데, 꽤 쓸 만해서 소개합니다.

파일 끝에 쉼표를 하나 남겨 일부러 깨뜨린 다음 claude doctor를 돌리는 겁니다. claude doctor는 거부된 파일만 적어 주니까, 목록에 나오면 그 파일을 읽었다는 뜻이에요.

Invalid settings
- <프로젝트 경로>/.claude/settings.json: Expected object, but received undefined

Ubuntu 24.04 · 2.1.280에서 시작 폴더만 바꿔 보니 이렇게 갈렸습니다.

시작한 폴더	깨진 공유 파일 위치	doctor에 나왔나
저장소 루트	루트	나옴
하위 폴더 sub	루트	안 나옴
하위 폴더 sub	sub/.claude/	나옴

하위 폴더에서 시작하면 루트의 공유 파일은 아예 읽히지 않았습니다. 그러니 팀이 저장소 루트에 커밋해 둔 설정을 쓰려면 루트에서 claude를 띄워야 합니다.

지금 세션이 어떤 설정을 읽었는지는 /status의 Setting sources 줄로도 볼 수 있어요. 다만 이 줄은 파일 경로가 아니라 Shared project settings 같은 이름으로 읽은 범위만 보여 줘서, 키마다 어느 파일이 값을 줬는지까지는 알려 주지 않습니다. 프로젝트나 managed 설정이 모델을 정했다면 시작 화면에 그 파일 이름이 뜨긴 합니다.

사용자 설정 없이 프로젝트의 settings.json과 settings.local.json 두 파일만 읽힌 세션에서는 이 줄이 Setting sources: Shared project settings, Project local settings로 나왔습니다(Windows 11 · 2.1.296).

파일은 네 곳, 저는 “누구에게 닿아야 하나”로 고릅니다

어떤 파일이 읽히는지 알았으니 이제 어디에 둘지입니다. 저는 이 값이 누구한테까지 닿아야 하는지로 고릅니다.

바꾸려는 것	두는 자리	닿는 범위
테마·기본 모델 같은 개인 취향	~/.claude/settings.json	내 모든 프로젝트
팀이 같이 쓸 권한·훅·플러그인	.claude/settings.json(커밋)	저장소를 받은 모두
팀 설정을 나만 다르게	.claude/settings.local.json	이 프로젝트의 나만
저장하지 않고 한 번만 시험	claude --settings <파일>	그 세션 하나
조직 보안 정책	managed 설정	조직이 배포한 모두

참고로 이 파일들은 설치한다고 생기지 않습니다. /config에서 테마를 처음 바꾸면 ~/.claude/settings.json이, 권한 프롬프트에서 Yes, and don’t ask again을 처음 고르면 .claude/settings.local.json이 생겨요. 처음에 파일이 안 보인다고 당황할 필요는 없습니다.

혼자 쓰는 값이라면 전부 사용자 파일에 넣어도 됩니다. 문제는 팀입니다.

사용자 파일은 팀원에게 가지 않고, 우선순위도 가장 아래라서 저장소의 공유 파일이 같은 키를 정하면 집니다. 팀이 같아야 하는 값은 공유 파일에 커밋해 두는 게 맞아요.

이름이 비슷해서 헷갈리는 파일들

여기서 한 번씩 헷갈리는 게 이름이 비슷한 파일들입니다.

• ~/.claude는 홈 폴더 안의 .claude 폴더입니다. Windows라면 %USERPROFILE%\.claude고요. 앞에 아무것도 없이 .claude라고 하면 프로젝트 안의 폴더입니다.
• ~/.claude.json(점이 앞에 붙고 폴더 밖에 있는 파일)은 Claude Code가 스스로 쓰는 상태 파일입니다. 로그인 세션, MCP 서버 설정, 프로젝트별 신뢰 결정, /config가 대신 써 주는 global config 키가 여기 들어갑니다. 설정 색인에서 Scope가 Global config인 키는 이 파일에서만 먹히고, settings.json에 적으면 무시돼요.
• /config의 일부 항목(Show tips 등)은 사용자 파일이 아니라 로컬 파일에 저장됩니다.

홈 쪽 파일을 다른 데 두고 싶다면 CLAUDE_CONFIG_DIR를 지정하면 됩니다. 그러면 설정·세션 기록·플러그인이 모두 그 폴더로 갑니다.

편집기에서 자동 완성을 받고 싶다면 $schema 키에 공개 JSON 스키마 주소를 넣으세요. 스키마가 CLI보다 늦게 갱신되는 편이라, 최근에 생긴 키에 경고가 떠도 설정이 틀린 건 아닐 수 있습니다.

.claude 폴더에 그 밖에 무엇이 쌓이는지는 .claude 디렉터리에 무엇이 언제 읽히나에 정리해 뒀습니다.

같은 키는 위가 이기지만, 목록 키는 합쳐진다

우선순위 자체는 단순합니다. managed 설정 → 명령줄(--settings) → .claude/settings.local.json → .claude/settings.json → ~/.claude/settings.json 순으로 위가 이깁니다. 팀 파일이 "model": "claude-sonnet-5"인데 내 .claude/settings.local.json에 다른 모델을 적으면, 내 세션만 그 모델로 시작하는 식이에요.

그림처럼 이기는 순서와 닿는 범위는 따로 놉니다. 명령줄은 두 번째로 세지만 세션 하나에만 닿고, 사용자 파일은 가장 약하지만 모든 프로젝트에 닿아요. 단계별로 알아 두면 좋은 것들이 있습니다.

• managed 설정은 managed-settings.json 파일, MDM 정책, claude.ai 콘솔의 server-managed 설정으로 배포됩니다. --settings로 넘긴 같은 키도 이기지 못하고, --model도 조직이 허용한 모델 안에서만 고를 수 있어요. 다만 managed model은 시작 모델일 뿐이라 /model로 바꿀 수 있습니다. 모델을 정말로 잠그는 키는 availableModels예요.
• --settings에 적은 키는 아래 파일들의 같은 키를 이기고, 적지 않은 키는 아래 값이 그대로 남습니다.
• 몇몇 보안 키는 거꾸로, 아래 단계의 더 엄격한 값이 managed보다 우선합니다. 예를 들어 disableClaudeAiConnectors는 managed가 false여도 어느 범위든 true가 있으면 그걸 따릅니다. 느슨한 쪽으로는 안 통해요.

우선순위 표만 보고 있으면 놓치는 게 목록 키입니다. permissions.allow 같은 목록 키는 하나를 고르는 게 아니라 모든 파일의 항목을 합칩니다. 그래서 조직의 allow 규칙이 내 규칙과 나란히 남아요.

이 병합을 막는 allowManagedPermissionRulesOnly는 managed 설정에만 있습니다. 그런데 모델 관련 목록 키 넷은 또 예외라서 합쳐지지 않습니다.

키	어떻게 정해지나
fallbackModel	가장 위 파일의 목록을 통째로
modelPicker	managed·--settings·사용자 중 가장 위(프로젝트·로컬 무시, v2.1.242+)
availableModels	managed가 정하면 그 목록만, 아니면 합침
modelSettings	effortLevel과 함께 모델마다 따로

환경 변수도 헷갈리기 좋습니다. 환경 변수는 이 계단의 한 칸이 아니라, 변수와 키 짝마다 누가 이기는지가 따로 정해져 있어요. 예를 들어 셸의 ANTHROPIC_MODEL은 어느 파일의 model보다도 앞섭니다.

반대로 설정 파일 안의 env 블록은 평범한 키라서 위 순서를 따르고, 셸과 겹치면 env 값이 이깁니다. Claude Code가 env 항목을 프로세스 환경에 직접 써 넣기 때문이에요.

이걸 이용하면 셸 프로파일에 걸린 변수를 이 프로젝트에서만 끌 수 있습니다. env에서 빈 문자열로 덮으면 됩니다.

단 NO_COLOR·FORCE_COLOR처럼 따로 취급되는 변수도 있으니, 안 덮이면 설정 레퍼런스의 env 항목에서 예외 목록을 확인해 보세요.

설정 파일을 고치면 대부분 재시작 없이 바로 반영됩니다. permissions·hooks, apiKeyHelper 같은 자격 증명 헬퍼도 그래요. 시작할 때 한 번만 읽는 키도 있어서, 세션 중에 자주 바꾸게 되는 model은 /model로, effortLevel·modelSettings는 /effort로 바꾸는 게 편합니다.

적었는데 안 먹을 때 먼저 볼 것

순서대로 잘 적었는데도 안 먹는 경우가 있습니다. 대부분은 그 키가 그 파일에서는 설정될 수 없는 경우였어요.

• permissions.defaultMode의 auto·bypassPermissions는 프로젝트·로컬 파일에서 적용되지 않습니다. 사용자·managed 설정에 두거나 --permission-mode로 넘겨야 해요. v2.1.257 전에는 bypassPermissions가 어느 파일에서든 됐기 때문에, 예전에 되던 설정이 어느 날부터 안 먹을 수 있습니다.
• 공유 파일의 일부 값은 각자 폴더를 신뢰한 뒤에야 적용됩니다. allow 규칙, permissions.additionalDirectories, extraKnownMarketplaces, 대부분의 env 값이 그렇습니다. deny·ask는 바로 적용되고요.
• --settings로는 Scope가 Managed·Global config인 키를 넘길 수 없습니다. 사용자 파일에 넣을 수 있는 키는 다 됩니다. 키 전용 플래그(model의 --model)나 짝이 되는 환경 변수와 누가 이기는지는 키마다 다르니, 설정 레퍼런스의 해당 키 항목을 보세요.

커밋한 키가 팀원에게 안 먹을 때도 이유는 둘 중 하나입니다. 그 키가 저장소 파일에서는 읽히지 않는 키이거나(설정 색인의 Scope가 User, local, or managed · User or managed · Managed · Global config), 위에서 말한 신뢰 대기 키예요.

설정 색인에서 그 키의 Scope 줄부터 확인하는 게 제일 빠릅니다. 저장소 파일로 켜지는 못해도 끄는 건 되는 키도 몇 개 있는데, 그런 키는 Scope 줄에 그렇게 적혀 있습니다.

로컬 파일은 두 가지만 더 기억해 두면 됩니다. v2.1.211 전에는 로컬 파일이 시작한 폴더에 만들어졌고, 그때 남은 파일도 지금 루트 파일과 함께 읽힙니다(같은 키는 루트 값, 권한 규칙은 양쪽 모두 적용).

그리고 Claude Code가 이 파일을 처음 만들 때는 전역 git excludes에 **/.claude/settings.local.json을 넣어 커밋되지 않게 해 주지만, 손으로 먼저 만든 파일은 직접 .gitignore에 넣어야 합니다. 파일이 git에 추적되면 그 안의 allow 규칙도 폴더 신뢰 단계를 거치게 돼요.

클라우드 세션에서는 읽는 파일이 줄어든다

브라우저에서 도는 클라우드 세션은 저장소를 새로 클론한 곳에서 돌기 때문에, 로컬에서 쓰던 설정이 그대로 따라오지 않습니다.

파일	클라우드 세션에서
공유 .claude/settings.json	저장소 하나면 읽음. 여럿이면 플러그인 키 둘만
사용자 파일, 로컬 파일	읽지 않음
managed 설정	server-managed만 닿음

저장소가 여럿인 세션은 각 저장소에서 enabledPlugins·extraKnownMarketplaces만 읽고, 그 플러그인도 로드하지 않습니다. claude.ai/code에서 /config를 열면 값을 바꾸는 대신 claude.ai 설정의 Claude Code 절로 넘어가요. 클라우드 세션의 설정은 그 환경의 환경 변수나, 저장소가 하나라면 커밋한 .claude/settings.json으로 바꿉니다.

막혔던 오류들

Error: Invalid JSON provided to --settings

한 세션만 다른 모델로 시험해 보려고 Windows PowerShell 5.1에서 JSON 문자열을 그대로 넘겼다가 만난 오류입니다. 실행도 못 해 보고 종료 코드 1로 끝났어요.

claude -p "Reply with the single word ok" --settings '{"model":"haiku"}'

PowerShell 5.1은 외부 프로그램에 넘기는 인자에서 안쪽 큰따옴표를 지워 버립니다. 같은 JSON을 haiku.json 파일로 저장해서 --settings .\haiku.json으로 넘기니 Haiku로 잘 시작했습니다. PowerShell에서는 JSON 문자열 말고 파일 경로로 넘기세요.

Settings Error

대화형 세션을 시작할 때 대화 상자가 뜨면서, Claude의 도움을 받아 파일을 고칠지 · 나갈지 · 그 설정 없이 계속할지 묻습니다. 설정 파일은 엄격한 JSON이라 // 주석 한 줄, 마지막 쉼표 하나도 오류가 됩니다. 스키마가 거부하는 값이 있어도 마찬가지예요.

Windows 11 · Claude Code 2.1.296에서 permissions.allow 끝에 쉼표 하나를 남긴 프로젝트 설정으로 시작해 본 화면입니다.

눈여겨볼 줄은 Files with errors are skipped entirely, not just the invalid settings.입니다. 쉼표 하나 때문에 그 파일의 다른 권한 규칙과 훅까지 모두 빠진다는 뜻이에요.

일단 계속한 다음 /status로 영향받은 파일을, claude doctor로 오류 내용을 보면 됩니다. -p로 실행할 때는 대화 상자 없이 깨진 파일이나 값을 건너뛰고 그냥 진행하니(managed 설정을 해석하지 못한 경우는 예외), 설정이 무시되는 것 같으면 claude doctor부터 돌려 보세요.

Settings Warning

파일 전체가 아니라 항목 몇 개만 실패했다는 뜻입니다. 형식이 틀린 권한 규칙이나 모르는 훅 이벤트 이름 같은 경우예요.

그 항목만 건너뛰고 나머지는 적용되니 거부된 항목만 고치면 됩니다. managed 설정에서 이런 일이 생기면 나머지는 계속 강제되고, 고치기 전까지 일부 키는 더 엄격한 값으로 동작합니다.

다른 사람들이 겪은 “값이 무시된다”

세 건 모두 “파일은 제자리에 있는데 값이 안 먹는다”는 보고인데, 원인은 서로 다릅니다.

• jimmyjayp(2026-09-01, #91296): macOS · 2.1.257에서 .claude/settings.local.json의 defaultMode: "bypassPermissions"가 조용히 무시되고 Shift+Tab 순환에도 안 나왔는데, 같은 값을 플래그로 주면 됐다고 합니다. 위에서 말한 2.1.257 변경 그대로의 동작이에요. 순환에 안 나온 부분은 문서에 따로 나오지 않습니다.
• Bjarke223(2026-09-20, #95634): 같은 .claude/settings.json의 Edit·Read allow 규칙이 데스크톱 앱 Code 탭(WSL2)의 Manual 모드에서는 안 먹고, 터미널 CLI 2.1.278에서는 먹었다고 합니다. 원인은 확정되지 않았습니다.
• subhashb(2026-09-22, #96113): macOS · 2.1.267에서 사용자 설정의 includeCoAuthoredBy: false가 약 90분짜리 세션 중 한 턴만 어긋났다가 돌아왔고, 재현 절차는 없다고 합니다. 원인은 확정되지 않았습니다.

첫 번째는 문서를 다시 보면 풀리고, 나머지 둘은 수정을 기다려야 하는 경우입니다. 그래서 저는 값이 무시되면 우선순위를 따지기 전에 그 키가 그 파일에서 설정될 수 있는 키인지, 그리고 지금 어느 화면에서 돌리고 있는지부터 봅니다. 증상부터 하나씩 좁혀 가는 순서는 설정이 적용되지 않을 때 /status와 claude doctor로 확인하는 순서에 따로 정리했어요.

마치며

설정 우선순위는 표 하나로 외울 수 있지만, 실제로 발목을 잡는 건 순서보다 “그 파일이 읽혔느냐”였습니다. 특히 Windows에서 하위 폴더로 띄우는 습관이 있다면, 루트에 적어 둔 로컬 설정이 조용히 빠진다는 걸 꼭 기억해 두세요.

설정이 이상하다 싶으면 팀 저장소의 루트에서 claude를 띄우고, /status의 Setting sources에 공유 파일(.claude/settings.json)을 뜻하는 Shared project settings가 보이는지부터 확인해 보세요. 그 파일에 무엇을 적을지는 allow·deny 규칙 문법과 자주 새는 패턴에서 이어집니다.