Claude Code 설정 파일

확인 날짜 안내

공식 문서 Claude Code 설정 파일과 우선순위(원본 날짜 미상, 서버 Last-Modified 2026-10-20, 수집 2026-10-21) 기준이다. 다른 공식 문서(수집 2026-10-18)에서 온 문장은 이 문서가 같은 사실을 다시 확인하거나 원칙 문장이라 페이지 날짜를 내리지 않았다. 키 이름·경로·버전 조건은 빨리 바뀌므로 대외 자료에 쓰기 전에 공식 문서를 다시 확인한다. 키 하나하나의 타입·기본값·Scope는 settings reference 문서가 다루며, 2026-10-21에 수집해 Claude Code 설정 키 레퍼런스에 주제별 표로 정리했다.

정의#

설정(settings)은 Claude Code의 동작을 바꾸는 JSON(용어 사전) 키다. 어떤 모델로 시작할지, 묻지 않고 무엇을 실행할지, 어떤 파일을 읽지 못할지, 터미널에서 어떻게 보일지, 조직이 무엇을 강제할지를 정한다. 설정을 어느 파일에 두느냐가 그 설정이 누구에게 적용되느냐를 정한다. Claude Code 설정 파일과 우선순위

설정과 지시는 다르다. Claude Code의 시스템 프롬프트는 공개되지 않으며, Claude에게 상시 지시를 주려면 메모리(CLAUDE.md) 파일이나 --append-system-prompt 플래그를 쓴다고 원본은 안내한다. Claude Code 설정 파일과 우선순위 공식 메모리 문서는 CLAUDE.md가 행동을 이끌 뿐 강제 층이 아니고, 강제는 settings 규칙이 한다고 구분한다. Claude Code 메모리

네 파일과 적용 범위 (2026-10-21 기준)#

근거: Claude Code 설정 파일과 우선순위. ~/.claude는 홈 디렉터리의 .claude 폴더, 그냥 .claude는 프로젝트 안의 .claude 폴더다. Windows에서 ~/.claude는 %USERPROFILE%\.claude이고, CLAUDE_CONFIG_DIR을 두면 설정·세션 기록·플러그인을 그 위치에 둔다.

• 설치만으로는 설정 파일이 생기지 않는다. Managed는 조직이 배포한다. Shared project는 이미 커밋돼 있지 않으면 직접 만든다. User 파일은 /config에서 테마처럼 user 설정에 저장되는 옵션을 처음 바꿀 때, local 파일은 권한 확인 창에서 "Yes, and don't ask again" 같은 상시 승인을 처음 줄 때 Claude Code가 만든다. Show tips 같은 몇몇 /config 옵션은 user 파일이 아니라 .claude/settings.local.json에 저장되므로 이때도 local 파일이 생긴다. Claude Code 설정 파일과 우선순위
• 다섯 번째 파일 ~/.claude.json: Claude Code가 스스로 쓰는 파일이다. 로그인 세션, MCP 서버 구성, 신뢰 결정 같은 프로젝트별 상태, /config가 쓰는 global config 키를 담는다. 원본은 직접 편집할 필요가 없다고 한다. Claude Code 설정 파일과 우선순위
• managed가 오는 길: managed-settings.json 파일, MDM·OS 정책, claude.ai 콘솔(또는 자체 호스팅 Claude apps gateway)의 서버 관리 설정, 그리고 Claude Desktop 같은 임베딩 호스트가 SDK managedSettings 옵션으로 넘기는 값. 사용자 기기의 Claude Desktop에서 도는 Cowork 세션은 claude.ai 관리 콘솔의 서버 관리 설정을 가져오지 않고, 조직의 Claude Desktop 구성이 requireCoworkFullVmSandbox를 두지 않으면 기기에 배포된 정책을 읽는다. 세부는 managed settings. Claude Code 설정 파일과 우선순위, Claude Code managed settings 배포

원본 예: 세 프로젝트와 팀원, 클라우드 세션#

원본은 내 기기에 website/, api/, acme-app/이 있고 팀원도 acme-app/을 클론했으며 acme-app/에서 클라우드 세션을 연 상황으로 범위를 비교한다. Claude Code 설정 파일과 우선순위

local 파일의 특별한 점 (2026-10-21 기준)#

• Claude Code도 쓴다. Bash 명령 확인 창에서 "Yes, and don't ask again"을 고르면 그 승인을 이 파일에 allow 규칙으로 저장한다. CLI는 local 파일에만 쓰고, VS Code 확장의 승인 카드는 저장할 파일을 고르게 해 프로젝트 공유 파일을 고르면 모두의 규칙이 바뀐다. Claude Code 설정 파일과 우선순위
• 커밋에서 빠지는 방식: Claude Code가 이 파일을 git 저장소에 처음 쓸 때(이미 무시되고 있지 않으면) 전역 git excludes 파일에 **/.claude/settings.local.json을 더한다. 그 파일은 전역 git 설정의 core.excludesFile(절대 경로나 ~ 경로일 때), 아니면 $XDG_CONFIG_HOME/git/ignore, XDG_CONFIG_HOME이 없으면 ~/.config/git/ignore다. 손으로 만들고 Claude Code가 아직 쓰지 않았다면 직접 .gitignore에 넣는다. Claude Code 설정 파일과 우선순위 공식 훅 가이드의 표는 이것을 "Claude Code가 설정을 저장할 때 gitignore된다"로 짧게 적는다. Claude Code 훅 가이드
• 신뢰 단계: 파일이 git에 추적되지 않는 동안은 이 파일의 allow 규칙이 작업 공간 신뢰 단계 없이 적용된다(저장소가 아니라 내 파일이므로). git이 추적하면 신뢰 단계가 똑같이 적용된다. Claude Code 설정 파일과 우선순위 공식 권한 문서(2026-10-21)의 세부: .claude가 심볼릭 링크여도 저장소가 준 것으로 본다. 추적 여부를 가리는 git은 폴더(또는 신뢰가 이어지는 상위 디렉터리)를 신뢰했거나 -p·SDK 세션일 때만 돌리고, 그 전에는 설정 홈(홈 디렉터리나 CLAUDE_CONFIG_DIR)에서 시작한 경우가 아니면 규칙을 프로젝트 설정처럼 보류한다. Claude Code 권한 설정 → 작업 공간 신뢰
• 위치: git 저장소의 하위 디렉터리에서 시작해도 저장소 루트의 local 파일을 읽고 쓰고, 승인을 저장소 전체에 적용한다. worktree에서는 메인 체크아웃 루트의 파일을 쓴다. 예외로 .claude/settings.json 옆에 남는 경우: git 저장소 밖, 저장소 루트가 홈 디렉터리일 때, Windows, 저장소 루트나 그 .git·.claude가 내 사용자 소유가 아닐 때. 파일 안에서 /로 시작하는 권한 규칙이나 상대 샌드박스 경로는 저장소 루트가 아니라 세션의 주 작업 디렉터리를 기준으로 한다. v2.1.211 전에는 시작 디렉터리에 두었고, 그 파일도 루트 파일과 함께 읽는다(같은 키는 루트 값, 권한 규칙은 둘 다 적용). Agent SDK의 resolveSettings()는 항상 시작 디렉터리의 파일을 읽는다. Claude Code 설정 파일과 우선순위
• 공유 .claude/settings.json은 세션의 주 작업 디렉터리에서 읽는다. 저장소 루트에 커밋한 파일을 쓰려면 루트에서 시작한다. /cd로 세션을 옮기면 두 프로젝트 파일을 새 디렉터리에서 읽는다(v2.1.246 이상). Claude Code 설정 파일과 우선순위 처음 가는 디렉터리면 먼저 작업 공간 신뢰를 묻고, 거절하면 세션은 원래 디렉터리에 남는다. Claude Code 권한 설정 → 작업 공간 신뢰

우선순위: 같은 키가 여러 곳에 있을 때 (2026-10-21 기준)#

가장 높은 레벨에서 정한 값을 쓴다. 높은 것부터: Claude Code 설정 파일과 우선순위

1. 1

   우선순위 1. Managed settings

   파일·MDM·서버 관리

2. 2

   우선순위 2. 명령줄 --settings

   그 세션만

3. 3

   우선순위 3. Project local

   .claude/settings.local.json

4. 4

   우선순위 4. Shared project

   .claude/settings.json

5. 5

   우선순위 5. User

   ~/.claude/settings.json

1. Managed: 내 설정 파일과 --settings 어느 것도 managed 키를 덮어쓰지 못하고, --model 같은 플래그도 조직이 허용한 모델 안에서만 고른다. managed model은 시작 기본값이지 잠금이 아니고, 잠금은 availableModels와 deniedModels다. 관리 출처가 여럿이면 managed 계층 안의 규칙을 따른다(managed settings).
2. 명령줄: claude를 시작할 때 --settings <파일 또는 JSON>으로 준 값. 그 세션에만 적용되고, 준 키만 project·user 값을 덮고 나머지는 파일 값을 유지한다. --model 같은 다른 플래그는 이 층에 속하지 않고 한 가지만 그 세션에 정한다.
3. Project local, 4. Shared project, 5. User 순.

이 층에 속하지 않는 것과 예외: Claude Code 설정 파일과 우선순위

• 환경 변수는 층이 아니다. 셸 변수와 설정 키가 둘 다 있는 동작은 쌍마다 따로 정한다. 셸의 ANTHROPIC_MODEL은 어느 파일의 model보다 우선하고, ANTHROPIC_DEFAULT_MODEL은 어느 파일도 model을 정하지 않을 때만 적용된다. 설정 파일 안의 env 블록은 보통 키라 위 층을 따른다.
• 목록은 덮어쓰지 않고 합친다. permissions.allow 같은 목록 키를 여러 파일에 두면 목록을 합쳐, 각 파일이 다른 파일의 항목을 지우지 않고 더한다. 모델 관련 네 키는 따로다: fallbackModel은 순서가 의미를 가지므로 가장 높은 파일의 값을 통째로 쓴다. modelPicker는 managed·--settings·user 중 가장 높은 값을 통째로 쓰고 project·local의 값은 무시한다(v2.1.242 이상). managed가 availableModels를 정하면 그 목록을 그대로 쓰고 user·project·local 항목을 무시한다(Claude Code를 품은 앱이 자기 모델 목록을 주는 경우 제외). managed가 아닌 범위끼리는 평소처럼 배열을 합친다. modelSettings는 effortLevel과 함께 모델 하나씩 정한다.
• 보안 민감 키의 예외: 아래 표.

managed보다 엄격한 낮은 값이 이기는 키 (2026-10-21 기준)#

세션을 제한하는 값을 가진 몇몇 키는, 보통은 managed를 덮지 못하는 범위의 제한 값을 따른다. 원본 표를 옮긴다. Claude Code 설정 파일과 우선순위

또 하나의 예외: Claude Code를 자기 안에서 띄우고 CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST를 설정한 앱은, 모든 managed 출처의 model·fallbackModel·modelPicker·modelOverrides와 managed env의 모델 선택 변수(ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_*_MODEL)보다 자기 모델 구성을 앞세운다. managed availableModels 허용 목록은 그 앱이 자기 목록을 주지 않는 한 유지된다. Claude Code 설정 파일과 우선순위

편집자 해석: 이 표는 "managed가 항상 이긴다"가 아니라 "제한 쪽으로는 낮은 범위도 더할 수 있다"로 읽을 수 있다. 근거는 원본의 "For a few keys whose values restrict a session, Claude Code honors a restrictive value from a scope that otherwise couldn't override managed settings" 문장이다. 다만 원본은 이 규칙을 표의 키에만 적용하고 일반 원칙으로 말하지 않는다.

원본의 우선순위 예 (2026-10-21 기준)#

~/.claude/settings.json에 spinnerTipsEnabled: false(스피너 아래 팁 끄기)를 둔 상황에서 팁이 다시 켜지는 경우: Claude Code 설정 파일과 우선순위

저장소 파일이 할 수 없는 것 (2026-10-21 기준)#

커밋한 .claude/settings.json이 팀원에게 그대로 닿지 않는 두 경우와, project·local 파일이 정할 수 없는 값. 보안 설명에 쓸 때 이 조건을 같이 말한다. Claude Code 설정 파일과 우선순위

• 저장소 파일에서 효과 없는 키: settings reference의 Scope 열이 User, local, or managed, User or managed, User, Managed, Global config인 키는 공유 파일에서 적용되지 않는다. 몇몇은 저장소 파일이 끄는 것만 허용하며 각 항목의 Scope 줄이 그렇게 밝힌다. Global config 키는 ~/.claude.json에서만 적용된다. env 안의 텔레메트리 내보내기 변수도 몇몇 끄는 값을 빼면 공유 파일에서 적용되지 않는다. 키별 Scope와 "저장소가 켤 수만 있다" 같은 항목별 제한은 Claude Code 설정 키 레퍼런스에 모았다(settings reference, 2026-10-21). Claude Code 설정 키 전체 레퍼런스
• 신뢰를 기다리는 키: permissions.allow 규칙, permissions.additionalDirectories, extraKnownMarketplaces, 대부분의 env 값은 팀원 각자가 폴더를 신뢰한 뒤에만 적용된다. 그 전에는 확인 창이 계속 뜨고, 파일이 선언한 마켓플레이스의 플러그인도 받지 않는다. deny·ask 규칙은 바로 적용된다.
  • 같은 날 수집한 다른 두 문서는 env의 예외를 더 적는다. settings reference: project·local env 값은 작업 공간을 신뢰한 뒤, 또는 신뢰 대화상자가 뜨지 않는 -p 모드에서는 시작 때 적용되고, Claude Code가 안전하다고 분류한 변수(모델 선택·시간 제한·기능 토글 등)는 모든 설정 파일에서 시작 때 적용된다. Claude Code 설정 키 전체 레퍼런스 권한 문서: 상위 폴더만 신뢰했거나 -p·SDK로 돌릴 때 저장소의 env 블록이 쓰인다. Claude Code 권한 설정
  • 편집자 해석: settings reference 문장("or at startup in -p mode")으로 보면 위 "신뢰한 뒤"는 대화형 세션 기준이고 -p·SDK는 예외로 읽을 수 있다. 상위 폴더만 신뢰한 경우는 이 상황을 직접 다루는 권한 문서 표를 기준으로 정했다: 상위 폴더만 신뢰한 대화형 세션에서도 저장소의 env 블록은 쓰인다(중첩 저장소 안은 예외). Claude Code 권한 설정 자세한 비교는 작업 공간 신뢰의 "env는 언제 신뢰를 기다리나" 절.

원본끼리 달랐던 점(정리됨)상위 폴더만 신뢰한 대화형 세션의 저장소 env

• Claude Code 설정 파일과 우선순위 (Settings 문서, 수집 2026-10-21): "most env values apply only after each teammate trusts the folder"
• Claude Code 권한 설정 (Permissions 문서, 수집 2026-10-21): "What runs before you trust a folder" 표의 "You trusted only a parent folder" 열에서 env 블록은 "Used"
• 갈리는 경우: 상위 폴더만 신뢰하고 이 폴더 자체는 신뢰하지 않은 대화형 세션에서 저장소의 env가 적용되는가. 권한 문서는 이 표의 두 열을 "you haven't trusted the folder itself"인 경우라고 밝히고, Settings 문서와 settings reference는 상위 폴더 신뢰를 따로 말하지 않는다.

권한 문서 기준으로 해소로 닫는다. 이 상황을 직접 다루는 원본은 권한 문서 표뿐이다. 표는 두 열을 "the two situations in which you haven't trusted the folder itself: you trusted only a parent folder, or you ran claude -p or the SDK there"라고 정의하고, settings 파일 훅·env 블록·헬퍼 명령 행의 "You trusted only a parent folder" 열에 "Used"라고 적는다. 그래서 상위 폴더만 신뢰한 대화형 세션에서도 저장소의 env 블록은 쓰인다고 설명한다. 같은 원본의 예외도 함께 쓴다: "The parent-folder column doesn't apply inside a nested repository"(대화형 세션은 그 저장소의 신뢰 대화상자를 띄운다). 위 원본 주장과 출처는 그대로 둔다. Claude Code 권한 설정

• project·local에서 읽지 않는 자동 모드 규칙 (2026-10-21 기준): 자동 모드 분류기는 autoMode 블록을 ~/.claude/settings.json, managed settings, --settings·Agent SDK 인라인에서만 읽고 .claude/settings.json·.claude/settings.local.json에서는 읽지 않는다. 원본 이유: 두 파일 모두 저장소 디렉터리에 있어 체크인된 저장소나 빌드 단계가 자기 allow 규칙을 주입할 수 있기 때문이다. local 파일에 둔 autoMode는 ~/.claude/settings.json으로 옮긴다. Claude Code 자동 모드 설정 → Claude Code 자동 모드 설정하기
• project·local이 켤 수 없는 샌드박스 설정 (2026-10-21 기준): 파일 격리를 끄는 sandbox.filesystem.disabled, Apple Events를 여는 allowAppleEvents, 자격 증명 mask·network.tlsTerminate, network.strictAllowlist는 .claude/settings.json·.claude/settings.local.json에서 효과가 없고 user·managed·--settings에서만 받는다. 샌드박스가 관리자 필수일 때는(v2.1.285 이상) 저장소 파일의 excludedCommands·allowedDomains·allowWrite 같은 느슨한 설정도 무시된다. 샌드박스 파일 시스템 배열은 범위끼리 합치고, --setting-sources(CLI)나 settingSources(Agent SDK)로 출처를 빼면 그 출처의 sandbox.filesystem 항목·Edit 권한 규칙·Read deny 규칙을 샌드박스 구성에서 무시한다(v2.1.246 이상). Claude Code 샌드박스 → 샌드박스
• project·local이 정할 수 없는 시작 모드: permissions.defaultMode의 auto·bypassPermissions는 project·local 파일에서 효과가 없다. user나 managed에 두거나 한 세션만 --permission-mode를 쓴다. v2.1.257 전에는 bypassPermissions가 어느 파일에서든 효과가 있었다. → 권한 모드

권한 규칙이 예상과 다르게 합쳐질 때 (2026-10-21 기준)#

저장소 파일의 한계와는 별개로, 원본이 문제 해결 항목으로 따로 드는 경우다. Claude Code 설정 파일과 우선순위

• 권한 규칙이 합쳐지는 방식: local 파일의 allow 규칙은 project나 managed 파일의 ask 규칙보다 앞서지 않는다. 그래서 "Yes, and don't ask again"을 골라도 같은 도구에 계속 물을 수 있다. 조직의 permissions.allow는 조직이 allowManagedPermissionRulesOnly를 켜지 않는 한 내 규칙과 합쳐져 함께 적용된다. → Claude Code 관리자 권한 통제

클라우드 세션의 설정 (2026-10-21 기준)#

클라우드 세션은 내 기기가 아니라 저장소를 새로 클론한 클라우드 환경에서 돈다. 그래서 닿는 설정이 다르다. Claude Code 설정 파일과 우선순위

관련#

• 바꾸는 법, 적용 시점, 확인, 깨진 파일, 안 먹을 때 점검: Claude Code 설정 바꾸기·확인·문제 해결
• 키별 타입·기본값·Scope·버전 표: Claude Code 설정 키 레퍼런스
• 조직이 배포하는 최상위 레벨: managed settings, 배포 절차는 Claude Code managed settings 배포·점검
• 권한 규칙과 시작 모드: 권한 모드, Claude Code 관리자 권한 통제
• 기능별로 레벨이 겹칠 때(스킬·서브에이전트·MCP·훅): Claude Code 확장 기능 고르기
• 설정과 다른 상시 지시: 메모리(CLAUDE.md)