핵심 요약
- 네 파일, 하나의 계층: managed-settings.json이 명령줄을 이기고, 명령줄은 .claude/settings.local.json을, 이것은 .claude/settings.json을, 마지막으로 ~/.claude/settings.json을 이깁니다. allow 목록은 덮어쓰지 않고 파일 간에 병합됩니다.
- settings.json은 엄격한 JSON입니다: 주석도, 마지막 쉼표도 안 됩니다. "$schema": "https://json.schemastore.org/claude-code-settings.json" 한 줄을 추가하면 에디터가 모든 키를 자동 완성해 줍니다.
- deny 규칙이 언제나 이깁니다. 어떤 수준의 deny 규칙이든 모든 allow 규칙을 눌럅니다 — Read(./.env)와 Bash(git push:*)부터 시작하면 두 줄로 시크릿과 원격 저장소를 보호한 셈입니다.
- settings.local.json은 이 머신 전용 샌드박스입니다: 공유 프로젝트 설정보다 우선하고 자동으로 gitignore되므로, 개인 경로와 실험이 저장소로 새어 나가지 않습니다.
Claude Code Configuration EP1: The Global Files Decoded (settings.json, CLAUDE.md, skills)
채널: Terminode AI2:31
Learning In Public: Cleaning Up Claude Code Settings
채널: Ben Nadel5:26
Settings — official documentation
공식 문서: code.claude.com/docs
Settings reference — the full key table
공식 문서: code.claude.com/docs
Environment variables — official reference
공식 문서: code.claude.com/docs
이 페이지의 사실 관계는 공식 설정 문서와 대조해 검증했습니다. 위의 두 영상이 시각 자료이자 감사 워크플로의 영감입니다.
스크린샷의 권리는 각 제작자에게 있으며, 해당 타임스탬프로 바로 연결됩니다. 얼굴이 나온 장면은 사용하지 않았습니다.
Claude Code settings.json, 단계별 설정하기
파트 1 — 설정 지형 파악하기
- 1
네 가지 설정 파일 알기
Claude Code는 네 범위에서 설정을 읽습니다: ~/.claude/settings.json(나, 모든 프로젝트), .claude/settings.json(팀 공유, 커밋 대상), .claude/settings.local.json(나, 이 프로젝트만), managed-settings.json(조직). ~/.claude 안의 모든 것 — CLAUDE.md, projects, skills, agents, plugins — 이 같은 지형의 일부입니다.
전역 레이어 한눈에 보기: 세션이 시작되면 Claude Code가 ~/.claude에서 읽는 모든 파일.2:28부터 시청 - 2
~/.claude/settings.json 열기 또는 만들기
macOS와 Linux에서는 ~/.claude/settings.json, Windows에서는 %USERPROFILE%\.claude\settings.json에 있습니다. 없으면 새로 만드세요 — 다음 세션에서 Claude Code가 읽어 들입니다. 설정 폴더 전체를 다른 곳에 두고 싶으면 CLAUDE_CONFIG_DIR을 설정하세요.
settings.json은 머신의 모든 프로젝트에 걸쳐 테마, 모델 선택, 플러그인, 환경 변수, 권한을 제어합니다.0:20부터 시청 - 3
모델과 effort 레벨 고정하기
"model"에 특정 모델이나 "opusplan"(Opus가 계획, Sonnet이 실행)을 지정하면 모든 새 세션의 기본값이 됩니다 — /model로 대화형으로 고르는 것과 같은 선택입니다. 여기에 "effortLevel"을 더해 기본 사고량에 상한을 두고, 모델별 재정의는 modelSettings로 합니다.
- 4
신뢰하는 명령은 allow에 추가하기
permissions 블록의 "allow"에는 승인 프롬프트를 건너뛰는 도구 규칙을 나열합니다: "Bash(npm run lint)", "Bash(npm run test *)", "Read(~/.zshrc)". 규칙은 도구별 스코프 패턴입니다 — * 와일드카드 앞에는 공백이 필요하고("Bash(git push:*)"), 없으면 더 긴 명령 이름까지 삼켜버립니다.
실제 settings.local.json의 allow 목록: 여기 한 줄 한 줄이 앞으로 다시는 뜨지 않을 승인 프롬프트의 흔적입니다.0:50부터 시청
파트 2 — 권한, env, 덮어쓰기
- 5
deny 규칙으로 시크릿 보호하기
deny 규칙이 가장 먼저 평가되며 어떤 수준의 설정도 이를 뒤집을 수 없습니다. "Read(./.env)"와 "Read(./.env.*)"로 API 키가 컨텍스트에 들어오지 않게 하고, "Bash(git push:*)"로 원격 게시를 사람의 결정으로 남겨 두세요. 회색 지대는 ask 규칙에 맡깁니다.
- 6
머신 로컬 재정의는 settings.local.json에
Claude Code가 당신을 위해 권한을 기록하면 .claude/settings.local.json에 저장되고, 이 파일을 자동으로 gitignore 합니다. 개인 경로, 실험용 플래그, 팀원에게 강요하고 싶지 않은 것은 이 파일에. 공유할 의도적인 규칙은 .claude/settings.json으로.
- 7
시크릿과 토글은 env 블록에
"env" 객체는 모든 세션에 환경 변수를 적용합니다: "ANTHROPIC_API_KEY", "DISABLE_TELEMETRY": "1", "DISABLE_NON_ESSENTIAL_MODEL_CALLS": "1", CLAUDE_CODE_MAX_OUTPUT_TOKENS 등. 문서에서 온 유용한 경험칙: settings.json의 ALL_CAPS 키는 거의 항상 env에 속합니다.
- 8
~/.claude.json을 설정과 혼동하지 않기
~/.claude.json은 설정이 아니라 상태입니다: OAuth 토큰, MCP 서버 등록, 프로젝트별 신뢰 결정, 전역 토글이 여기 살아 있습니다. 의도는 settings.json에 적고 .claude.json은 Claude Code가 관리하게 두세요 — 그리고 둘 다 백업하세요. cleanupPeriodDays가 대화 기록 보관 기간도 결정하기 때문입니다.
~/.claude 내부: 기능 플래그, 플러그인, 셸 스냅샷, 그리고 설정 파일로 착각하기 쉬운 .claude.json 상태 파일.2:00부터 시청
파트 3 — 시간이 지나도 깔끔하게 유지하기
- 9
~/.claude에 있는 다른 것들도 알아두기
CLAUDE.md는 전역 지시 파일로 매 세션 시작 때 읽힙니다. projects/는 저장소별 대화 기록과 자동 메모리를 저장하고, skills/는 온디맨드 SKILL.md 워크플로, agents/는 서브에이전트 정의, plugins/는 설치된 플러그인, statsig/는 기능 플래그를 캐싱합니다. settings.json이 이 모든 것을 지휘합니다.
CLAUDE.md는 설정으로 착각하기 쉬운 이웃 파일입니다: 설정 키가 아니라 선호와 규칙을 담는 파일이죠.0:45부터 시청 - 10
allow 목록 감사를 Claude에게 맡기기
allow 목록은 승인 한 번에 한 줄씩 자라다 보면 어느새 아무도 내용을 기억하지 못합니다. Claude Code를 열고 .claude/settings.local.json에서 중복·불필요·위험한 항목을 점검해 달라고 요청하세요 — Claude는 자체 내장 도구가 무엇인지, 어떤 규칙이 겹치는지 압니다.
감사 프롬프트: allow 목록을 검토해 중복, 내장 도구와 겹치는 항목, 명백히 위험한 항목을 표시하게 하기.1:40부터 시청 - 11
심사 결과를 리뷰어처럼 읽기
이 페이지가 스크린샷을 찍은 실제 감사에서 Claude는 41개 항목을 분류했습니다: ls, grep, find, echo, cd는 내장 도구와 중복. 와일드카드 항목은 이미 명시적 명령을 커버. 로컬 절대 경로는 Claude가 작업 디렉터리를 알므로 불필요. curl만이 진짜로 권한이 너무 넓다고 지적되었습니다.
심사 결과: 41개 항목을 불필요·중복·위험으로 분류 — 각 줄의 대체안 포함.3:05부터 시청 - 12
정리를 적용하고 매월 점검하기
제안된 편집을 승인하면 파일이 41개 항목에서 15개로 줄어듭니다. 습관으로 만드세요: 읽을 수 없는 allow 목록은 보이지 않는 공격 표면입니다. 큰 프로젝트 후에는 감사를 다시 실행하고, 포괄 승인보다 Bash(git diff:*) 같은 스코프가 좁은 규칙을 선호하세요.
적용된 정리: curl, 명시적 홈 경로, 일회용 셸 스크립트가 allow 목록에서 제거되었습니다.4:50부터 시청
settings.json vs CLAUDE.md vs ~/.claude.json vs /config
"Claude Code 설정"처럼 보이는 창구가 넷입니다 — 서로 바꿔 쓸 수 없습니다. 무엇이 어느 파일의 소관인지:
- 1settings.json(모든 스코프) — 선언적 설정: model, effort, permissions, env, hooks, statusLine, plugins. 엄격한 JSON, 스키마 검증, 커밋 안전(.local 제외).
- 2CLAUDE.md — 자연어 지시와 관례. 동작을 다듬을 뿐 설정이 아니고, 키-값 계약도 없으며 매 세션 읽힙니다.
- 3~/.claude.json — 머신 상태: OAuth/세션 데이터, MCP 등록, 프로젝트별 신뢰, 온보딩 플래그. Claude Code가 기록하는 파일이므로 손으로 편집하지 마세요.
- 4/config — 대화형 패널. 같은 키를 다루는 UI입니다: 대부분의 토글은 ~/.claude/settings.json에 기록되고, 일부(Show tips 등)는 settings.local.json으로, 전역 옵션은 ~/.claude.json에 기록됩니다.
- 5managed-settings.json — 조직 계층. 전부를 이깁니다(더 엄격한 값이 이기는 보안 예외는 소수) — 그래서 회사 머신에서는 로컬 모델 선택이 조용히 무시될 수 있습니다.
경험칙: 동작은 CLAUDE.md, 설정은 settings.json. 그리고 값이 무시되는 것 같으면 ~/.claude.json이나 관리 파일이 이미 결정하지 않았는지 확인하세요.
설정이 안 먹히나요? 응급 처치
settings.json 문제는 대부분 다섯 가지 원인으로 수렴합니다. 순서대로 확인하세요:
- 1JSON 문법 오류. settings.json은 엄격한 JSON — 마지막 쉼표 하나, // 주석 한 줄이면 파일 전체가 거부됩니다. 밸리데이터에 붙여 넣거나 $schema 줄을 추가해 입력하는 동안 에디터가 잡아내게 하세요.
- 2위쪽에 더 엄격한 규칙. 관리 설정과 보안 관련 키(disableClaudeAiConnectors, useAutoModeDuringPlan 등)는 무엇보다 우선합니다. 회사 머신이 덮어쓰고 있지 않은지 확인하세요.
- 3잘못된 파일, 잘못된 스코프. .claude/settings.json의 규칙은 그 프로젝트 안에서만 적용됩니다. defaultMode의 auto와 bypassPermissions는 설계상 프로젝트 수준 파일에서는 무시됩니다.
- 4env 값의 자리가 틀림. ALL_CAPS 키는 최상위가 아니라 env 블록으로. ANTHROPIC_API_KEY나 DISABLE_TELEMETRY가 무시되는 것 같다면 한 단계 위에 놓여 있을 확률이 높습니다.
- 5조용히 거부된 항목. claude doctor를 실행하면 검증에 실패한 설정 항목이 나열되고, 세션 안의 /status로 실제 로드된 파일을 볼 수 있습니다.
여전히 안 되나요? 마지막 편집을 지우고, /status로 파일이 로드되는지 확인한 뒤 키를 하나씩 다시 적용하세요 — 노려보는 것보다 이분 탐색입니다.