설정 층(Settings layers)
가 을 합치는 순서. 무엇인지, 어떻게 돌아가고 어떻게 쓰는지, 조심할 점까지 그림과 예로 풀어 봅니다.
무엇인가요
는 같은 설정을 여러 곳에서 찾을 수 있어서, 어느 값을 쓸지 정하는 고정된 순서가 필요합니다. 높은 것부터 관리 설정 → --settings 플래그 → .claude/settings.local.json → .claude/settings.json → ~/.claude/settings.json 입니다. 이름처럼 값이 하나인 키를 두 층이 같이 정하면 위층이 이깁니다. permissions.allow 처럼 목록인 키는 층끼리 합쳐서, 각 파일이 다른 파일의 항목을 지우지 않고 더할 수 있습니다. 그래서 조직·팀·개인이 한 파일을 두고 다투지 않고 저마다 정할 수 있습니다.
어떻게 돌아가나요
-
모든 을 읽음
-
값 하나짜리는 위층이 이김
-
목록은 모든 층을 합침
-
/status 로 읽은 파일 확인
이렇게 씁니다
-
~/.claude/settings.json모든 프로젝트에 쓰는 내 기본값입니다. 가장 아래층입니다.
-
.claude/settings.json에 하는 팀 파일입니다. 그 프로젝트에서는 내 사용자 파일보다 앞섭니다.
-
.claude/settings.local.json한 프로젝트에서만 쓰는 내 덮어쓰기 파일입니다. 팀 파일보다 앞서고, 커밋에 들어가지 않습니다.
-
claude --settings '{"spinnerTipsEnabled": true}'이번 세션에만 키를 정합니다. 관리 설정을 뺀 모든 파일보다 앞섭니다.
주의할 점
환경 변수는 이 층에 들어가지 않습니다. 예를 들어 의 ANTHROPIC_MODEL 은 어느 파일의 model 키보다 앞섭니다. 몇몇 키는 관리 설정과 달라도 아래층의 더 엄격한 값을 따르고, fallbackModel 같은 몇몇 목록 키는 합치지 않고 통째로 하나를 고릅니다.
함께 보면 좋은 용어
원문과 공식 문서
이 페이지는 용어를 쉬운 말로 풀어 쓴 것입니다. 기준은 원문이니, 다르면 원문을 따르세요.
- 원문에서 이 용어 보기Claude Code Docs — Glossary Anthropic · 2026-10-19 확인
- Anthropic — Claude Code docs: Settings files and precedence — Settings precedence(새 창에서 열림)
- Anthropic — Claude Code docs: Settings files and precedence — Lists merge instead of overriding(새 창에서 열림)
- Anthropic — Claude Code docs: Settings files and precedence — Settings files and who they affect(새 창에서 열림)
- Anthropic — Settings — Where settings live(새 창에서 열림)