Claude Code 설정 파일과 우선순위

한 줄 요약: Claude Code 공식 문서 "Settings files and precedence". 설정 파일 네 개(user·shared project·project local·managed)가 각각 누구에게 적용되는지, 설정을 바꾸는 세 방법(/config, 파일 편집, 한 세션만 --settings·플래그·환경 변수), /status로 무엇이 로드됐는지 확인하는 법, 깨진 파일 처리, 같은 키가 여러 곳에 있을 때의 우선순위(managed > 명령줄 > project local > shared project > user)와 그 예외, 클라우드 세션에 닿는 설정을 다룬다. 키 하나하나의 목록은 이 문서가 아니라 settings reference가 맡는다.

원본 정보#

제목: Settings files and precedence
발행: Anthropic, Claude Code 공식 문서. 본문에 날짜 없음(원본 날짜 미상). 서버 Last-Modified 2026-10-20
URL: https://code.claude.com/docs/en/settings (새 창)
수집(fetch)일: 2026-10-21. 본문의 파일 경로, 설정 키, 버전 조건(v2.1.2xx)은 이 날짜 기준이다.
범위: 내 기기에서 도는 Claude Code(터미널, VS Code·JetBrains 확장, 데스크톱 앱. 모두 같은 설정 파일을 읽는다). 클라우드 세션은 일부만 읽는다(아래 5번).

핵심 주장#

설정을 어느 파일에 두느냐가 누구에게 적용되느냐를 정한다. User ~/.claude/settings.json(나, 이 기기의 모든 프로젝트), Shared project .claude/settings.json(그 폴더에서 일하는 모두, git에 커밋하면 팀원도), Project local .claude/settings.local.json(나, 이 프로젝트만), Managed managed-settings.json과 그 밖의 관리 출처(조직이 배포한 모두). 이와 별도로 Claude Code가 스스로 쓰는 ~/.claude.json(로그인 세션, MCP 서버 구성, 프로젝트별 신뢰 결정 같은 상태, /config가 쓰는 global config 키)이 있고, 원본은 이 파일을 편집할 필요가 없다고 한다. 설치만으로는 설정 파일이 생기지 않는다. → Claude Code 설정 파일
같은 키가 여러 곳에 있으면 높은 레벨이 이긴다: managed > 명령줄(--settings) > project local > shared project > user. 단 목록 키(permissions.allow 등)는 덮어쓰지 않고 합쳐지며, 모델 관련 네 키(fallbackModel, modelPicker, availableModels, modelSettings)는 자기 규칙을 따른다. 환경 변수는 이 층에 속하지 않고 키·변수 쌍마다 따로 정한다(ANTHROPIC_MODEL은 어느 파일의 model보다 우선, ANTHROPIC_DEFAULT_MODEL은 파일이 model을 정하지 않을 때만). managed model은 시작 기본값이지 잠금이 아니고, 잠금은 availableModels·deniedModels다. → Claude Code 설정 파일, managed settings
보안 성격의 몇몇 키는 우선순위를 거슬러 더 엄격한 값을 지킨다. 원본 표의 11개 키(예: disableClaudeAiConnectors는 어느 범위의 true든, permissions.blockReadsOutsideWorkingDirectories는 어느 범위의 true든 v2.1.257 이상, maxEffortLevel은 가장 낮은 상한 v2.1.267 이상)는 managed가 더 느슨한 값을 줘도 낮은 범위의 엄격한 값을 따른다. 엄격한 값을 받아 주는 범위는 키마다 다르다: autoMode.classifyAllShell은 ~/.claude/settings.json이나 --settings의 true만, remoteControlAtStartup·crossSessionInbound는 .claude/settings.json·.claude/settings.local.json의 엄격한 값만 받고, useAutoModeDuringPlan·syncClaudeAiSkills·syncClaudeAiPlugins는 false를 managed·--settings·user·local에서 받되 .claude/settings.json의 false는 무시한다. → Claude Code 설정 파일
커밋한 설정이 팀원에게 다 닿지는 않는다. 일부 키는 저장소 파일에서 아예 효과가 없고(settings reference의 Scope 열이 User, Managed, Global config 등인 키), permissions.allow·permissions.additionalDirectories·extraKnownMarketplaces·대부분의 env 값은 팀원 각자가 폴더를 신뢰한 뒤에야 적용된다. deny·ask 규칙은 바로 적용된다. permissions.defaultMode의 auto·bypassPermissions는 project·local 파일에서 효과가 없다(v2.1.257 전에는 bypassPermissions가 어느 파일에서든 효과가 있었다). → Claude Code 설정 바꾸기·확인·문제 해결, 권한 모드
클라우드 세션은 새로 클론한 저장소에서 돌아 내 기기의 설정을 대부분 읽지 않는다. 저장소 하나인 세션은 .claude/settings.json을 읽고, ~/.claude/settings.json과 .claude/settings.local.json은 읽지 않는다. 기기의 managed-settings.json·MDM 프로파일은 닿지 않고 서버 관리 설정은 닿는다(어떤 클라우드 세션이 받는지는 surface coverage 문서로 넘긴다). 자체 호스팅 환경은 러너 이미지의 managed settings 파일도 읽고, 언제 적용되는지는 managed 출처 합치기 문서로 넘긴다. Anthropic 호스팅 환경에서 저장소 여럿인 세션은 각 저장소의 enabledPlugins·extraKnownMarketplaces만 읽는다. → Claude Code 설정 파일, managed settings

원본의 절차·명령 (2026-10-21 기준)#

바꾸는 법 세 가지: /config 메뉴(Config 탭, 대부분 ~/.claude/settings.json에, Show tips 같은 몇 가지는 .claude/settings.local.json에, global config 옵션은 ~/.claude.json에 저장. /config verbose=true처럼 key=value도 된다), 설정 파일 직접 편집(엄격한 JSON, $schema 줄로 편집기 자동완성), 한 세션만(--settings JSON·파일, --model·--effort 같은 키 전용 플래그, ANTHROPIC_MODEL 같은 환경 변수). /config는 터미널 인터페이스 기능이라 VS Code 채팅 패널과 데스크톱 앱은 열지 않는다.
적용 시점: 설정 파일을 감시해 바뀌면 다시 읽는다. permissions, hooks, apiKeyHelper 같은 자격 증명 헬퍼 편집은 재시작 없이 실행 중 세션에 적용된다. 설정 파일 변경마다 ConfigChange 훅이 돈다(MDM·claude.ai 콘솔로 오는 managed settings는 제외). model, effortLevel, modelSettings 같은 일부 키는 세션 시작 때 한 번만 읽는다.
확인: /status의 Setting sources 줄이 이번 세션에 로드한 파일을 나열한다(어느 파일이 어느 키를 줬는지는 보여 주지 않는다). 거부된 항목은 claude doctor.
깨진 파일: Settings Error(파일 전체가 잘못된 JSON이거나 스키마 거부 값, 대화형 시작 때 고치기·종료·계속 선택), Settings Warning(항목만 실패, 그 항목만 건너뜀), managed(나머지는 계속 강제), Configuration error(~/.claude.json 파싱 실패, ~/.claude/backups/에 사본과 최근 백업 5개). -p 실행은 대화상자 없이 깨진 부분을 건너뛰고 계속한다.
로컬 파일 위치: git 저장소의 하위 디렉터리에서 시작해도 .claude/settings.local.json은 저장소 루트의 것을 읽고 쓴다(v2.1.211 이전에는 시작 디렉터리). worktree에서는 메인 체크아웃 루트. 공유 .claude/settings.json은 세션의 주 작업 디렉터리에서 읽는다.

원본이 링크한 관련 문서#

Configure permissions(→ Claude Code 권한 설정), Example settings files, Environment variables, Debug your configuration, Claude directory reference, Server-managed settings, Admin setup, Cloud environments. Settings reference는 Claude Code 설정 키 전체 레퍼런스로 수집했다. 키 하나의 전체 동작(기본값, 각 키의 Scope, 플래그·변수 우선)은 그 문서에서 확인한다.