AI 해결 노트 · 2026-09-17 · 실측 2026-09-17

Claude Code settings.json은 어디에 있고 어느 파일이 이기나 — 사용자·프로젝트·로컬·관리형 범위 윈도우 실측

한 줄로

Claude Code 설정 파일은 사용자·공유 프로젝트·프로젝트 로컬·관리형 네 범위에 있고, 같은 키가 겹치면 관리형 → 명령줄 → 로컬 → 공유 → 사용자 순으로 위쪽 값이 쓰입니다(공식 문서 기준). 윈도우에서 ~/.claude는 %USERPROFILE%\.claude입니다.

저희 PC에서는 순서 전체를 값으로 겨뤄 보지는 못했고, MCP 승인 키로 어느 파일이 실제로 읽히는지를 확인했습니다.

이런 분께

settings.json을 고쳤는데 반영이 안 되는 것 같거나, 팀과 같이 쓰는 저장소에서 내 설정만 따로 두고 싶은 분. settings.json과 settings.local.json 중 어디에 적어야 할지 헷갈리는 분.

실측 환경

공식 문서가 말하는 네 파일

출처: code.claude.com/docs/en/settings (2026-09-17 확인). 문서 표를 그대로 옮깁니다.

윈도우 사용자라면 같은 문서의 이 문장을 기억해 두면 됩니다.

On Windows, `~/.claude` means `%USERPROFILE%\.claude`.

로컬 파일은 직접 만들지 않아도 생깁니다. 문서에 따르면 권한 질문에서 "Yes, and don't ask again"을 고르면 Claude Code가 그 허용 규칙을 .claude/settings.local.json에 적습니다. 깃 저장소 하위 폴더에서 켜면 저장소 루트의 파일을 쓴다고 하는데, 문서는 윈도우(on Windows)를 이 규칙의 예외로 들며, 이때 로컬 파일은 .claude/settings.json과 같은 위치에 둔다고 설명합니다. 그 위치가 정확히 어디인지는 발췌만으로 단정할 수 없고, 실측하지도 않았습니다.

우선순위 — 문서 원문

같은 문서의 Settings precedence 절입니다.

When the same key appears in more than one place, Claude Code uses the value from the highest level that sets it.

1. Managed settings
2. Command line arguments
3. Project local settings (`.claude/settings.local.json`)
4. Shared project settings (`.claude/settings.json`)
5. User settings (`~/.claude/settings.json`)

덧붙은 규칙 두 가지가 실무에서 자주 걸립니다. 하나는 permissions.allow 같은 목록 키는 위쪽이 아래쪽을 덮지 않고 합쳐진다는 점(Lists merge instead of overriding)입니다. 다른 하나는 환경변수가 이 순서표의 한 층이 아니라는 점으로, 문서는 ANTHROPIC_MODEL이 어느 파일의 model보다 앞선다고 적고 있습니다.

저희 PC의 사용자 설정

사용자 settings.json을 읽어 파싱했고, 출력에는 파일 정보와 최상위 키 이름만 남겼습니다.

-rw-r--r-- 1 User 197121 18746 Sep 16 18:34 /c/Users/User/.claude/settings.json
-rw-r--r-- 1 User 197121 93011 Aug 15 09:14 /c/Users/User/.claude/settings.local.json
['agentPushNotifEnabled', 'autoMode', 'autoUpdatesChannel', 'enabledPlugins', 'env', 'extraKnownMarketplaces', 'hooks', 'model', 'permissions', 'skipWorkflowUsageWarning', 'statusLine', 'theme']

홈 폴더 .claude 안에 settings.local.json도 있었습니다. 이 파일이 언제, 어떤 동작으로 생겼는지는 확인하지 않았습니다.

어느 파일이 이기는지 확인할 명령이 있나

claude --help의 명령 목록에는 config 같은 설정 조회 명령이 없었습니다(agents, auth, auto-mode, doctor, mcp, plugin, project, update 등). claude auto-mode config는 "Print the effective auto mode config as JSON: your settings where set, defaults otherwise"라고 되어 있어 합쳐진 값을 보여 주지만, 자동 모드 키 하나만 다루고 저희 사용자 파일에 autoMode 키가 있어 실행하면 개인 설정값이 찍히므로 쓰지 않았습니다.

문서가 권하는 확인 방법은 세션 안의 /status(Setting sources 줄)인데, 대화 세션을 열어야 해서 이번에는 하지 않았습니다.

그래서 결과가 명령 출력에 바로 드러나는 키를 골랐습니다. 프로젝트 .mcp.json 서버의 승인 여부를 정하는 enableAllProjectMcpServers와 거부 목록 disabledMcpjsonServers입니다. 이번 실험에서 tempfs 서버는 승인 대기일 때 claude mcp list에 ⏸ Pending approval, 승인돼 연결됐을 때 ✔ Connected로 표시됐습니다. 실험 폴더에 claude mcp add --scope project로 서버 tempfs 하나를 넣어 두고(과정은 윈도우에서 Claude Code에 MCP 서버 붙이기 참고) 설정 파일과 --settings 인자만 바꿔 가며 돌렸습니다.

공유 프로젝트 설정에만 승인을 넣었을 때 .claude/settings.json 내용입니다.

{
  "enableAllProjectMcpServers": true
}

파일 없이 명령줄로만 승인할 때는 이렇게 돌렸습니다.

claude --settings '{"enableAllProjectMcpServers": true}' mcp list

결과

3번(2번의 로컬 파일이 남은 채 --settings로 승인)도 ✔ Connected였습니다. 로컬 파일 몫을 떼어 보려고 파일을 지우고 4번으로 다시 돌렸습니다.

1·2번에서 파일의 MCP 승인 설정이 적용되지 않은 것은 이 폴더를 한 번도 "신뢰"한 적이 없기 때문으로 보입니다. MCP 문서(code.claude.com/docs/en/mcp, 2026-09-17 확인)는 신뢰하지 않은 폴더에서 저장소에 올라가는 .claude/settings.json의 승인은 무시하고, settings.local.json의 승인도 "waits for the trust dialog"라고 적고 있으며, 신뢰 전에도 먹는 곳으로 사용자 ~/.claude/settings.json, 관리형, --settings 셋을 듭니다. 저희 결과는 이 설명과 어긋나지 않았습니다.

5번은 같은 문서의 "A disabledMcpjsonServers entry in any settings file still rejects the server."와 맞습니다. 명령줄(2순위)로 승인해도 공유 프로젝트 파일(4순위)의 거부가 이겼으니, 이 키 조합은 위 순서표로 설명되지 않는 별도 규칙입니다. 신뢰하지 않은 폴더에서도 공유 파일의 거부는 읽힌다는 점도 함께 드러났습니다.

설정 파일이 깨졌는지 보는 법

claude doctor 도움말에는 "Reads settings files in the current directory without a trust prompt"라고 되어 있습니다. 실험 폴더의 두 파일을 일부러 망가뜨려 돌렸습니다. settings.json에는 true 대신 문자열 "yes", settings.local.json에는 끝 쉼표를 넣었습니다.

Invalid settings
- C:\Users\User\AppData\Local\Temp\longtail_C\proj\.claude\settings.json › enableAllProjectMcpServers: Expected boolean, but received undefined
  Suggested fix: Use true or false without quotes. Example: "includeCoAuthoredBy": true
- C:\Users\User\AppData\Local\Temp\longtail_C\proj\.claude\settings.local.json: Expected object, but received undefined

두 파일 모두 잡혔고, 종료 코드는 0이었습니다. 문구가 "received undefined"로 나와 실제 넣은 값과 다르게 보이는 점은 참고하세요. 고친 뒤에도 claude doctor를 다시 돌려 이 목록이 비는지 보면 됩니다.

실패한 것

순서표 2~5단계를 "같은 키, 다른 값"으로 직접 겨뤄 보는 시험은 하지 못했습니다. 대화 세션(/status, 시작 헤더)을 열지 않는다는 조건 안에서는 값의 출처를 보여 주는 읽기 명령을 찾지 못했습니다. 신뢰하지 않은 폴더에서는 로컬·공유 파일의 승인이 모두 무시돼, 로컬이 공유를 이기는 장면도 만들 수 없었습니다.

확인하지 않은 것

• 관리형 설정: claude doctor는 Managed settings (remote): not fetched — requires an Enterprise or Team subscription이라고 표시했습니다. 이 출력만으로 다른 관리형 설정 소스가 있는지까지는 알 수 없고, 관리형 설정 실험은 하지 않았습니다.
• 신뢰한 폴더(대화 세션에서 신뢰 대화상자를 수락한 폴더)에서의 동작.
• 깃 저장소 안에서 settings.local.json이 루트에 생기는지, 전역 git excludes에 등록되는지.
• --setting-sources 옵션(도움말에는 있음)으로 층을 하나씩 끄는 방법.
• 맥·리눅스.

함께 보기

• 윈도우에서 Claude Code에 MCP 서버 붙이기
• Claude Code 윈도우 네이티브 설치 확인