클로드 코드 설정 파일 — 위치와 우선순위 정리
클로드 코드 설정 파일은 세 군데에 있습니다. 모든 프로젝트에 적용되는 ~/.claude/settings.json, 팀과 공유하는 .claude/settings.json, 나만 쓰는 .claude/settings.local.json입니다. 같은 값이 여러 곳에 있으면 local > project > user 순으로 이기고, 회사에서 배포한 관리자 설정이 있으면 그게 전부를 누릅니다. 다만 배열 값은 덮어쓰지 않고 합쳐진다는 예외가 있어 여기서 자주 헷갈립니다. 아래에 위치·우선순위·안 먹힐 때 확인 순서를 정리했습니다. (Claude Code 2.1.x 기준 · 2026년 8월 5일 공식 문서 확인)
1. 설정 파일이 어디에 있나
| 범위 | 위치 | 누구에게 적용 | 팀 공유 |
|---|---|---|---|
| 사용자 | ~/.claude/settings.json |
나, 모든 프로젝트에서 | 아니오 |
| 프로젝트 | .claude/settings.json |
이 저장소의 모든 협업자 | 예 (git에 커밋) |
| 로컬 | .claude/settings.local.json |
나, 이 저장소에서만 | 아니오 (자동 git 제외) |
| 관리자 | MDM·레지스트리·managed-settings.json |
조직 구성원 전체 | 예 (IT가 배포) |
윈도우에서는 ~/.claude가 %USERPROFILE%\.claude로 풀립니다.
~/.claude.json은 설정 파일이 아닙니다. 이름이 비슷해서 헷갈리는데, 이 파일에는 OAuth 세션·사용자 범위 MCP 서버 설정·프로젝트별 상태(허용한 도구, 신뢰 여부)·각종 캐시가 들어갑니다. 손으로 고칠 파일은 ~/.claude/settings.json 쪽입니다.어떤 것을 어디에 둘지는 이렇게 가르면 됩니다.
- 사용자 — 어디서나 쓰고 싶은 개인 취향(테마, 에디터), 모든 프로젝트에서 쓰는 도구·플러그인
- 프로젝트 — 팀이 같이 써야 하는 권한·훅·MCP 서버 설정
- 로컬 — 이 저장소에서만 쓰는 개인 재정의, 팀에 공유하기 전 실험
로컬 파일에는 특징이 하나 더 있습니다. 클로드 코드가 이 파일에 설정을 저장할 때 git 전역 제외 목록에 **/.claude/settings.local.json을 자동으로 추가합니다. 단 내가 직접 만든 경우에는 안 해 주므로 gitignore에 직접 넣어야 합니다.
2. 우선순위 — 위에서부터 이긴다
같은 키가 여러 곳에 있으면 이 순서로 정리됩니다.
| 순위 | 출처 | 비고 |
|---|---|---|
| 1 | 관리자 설정 | CLI 인자로도 못 덮는다 |
| 2 | 명령줄 인자 | --settings로 준 값. 그 세션만 |
| 3 | .claude/settings.local.json |
내 프로젝트 개인 설정 |
| 4 | .claude/settings.json |
팀 공유 설정 |
| 5 | ~/.claude/settings.json |
아무도 안 정했을 때 적용 |
예를 들어 사용자 설정에서 permissions.defaultMode를 acceptEdits로 뒀는데 프로젝트 공유 설정이 default라면, 프로젝트 값이 적용됩니다. 권한 모드가 무엇무엇인지는 클로드 코드 권한 설정 글에 여섯 가지로 정리해 두었습니다.
3. 배열 설정은 덮어쓰지 않고 합쳐진다
여기가 제일 자주 헷갈리는 지점입니다. 스칼라 값은 위 순위대로 덮어쓰지만, 배열 값은 합쳐집니다. 공식 문서 표현대로 이어 붙인 뒤 중복을 제거합니다.
즉 permissions.allow를 프로젝트 설정에 적어 두고 사용자 설정에도 적어 뒀다면, 둘 다 살아 있습니다. 낮은 순위라고 무시되지 않습니다.
# 관리자 설정
"sandbox": { "filesystem": { "allowWrite": ["/opt/company-tools"] } }
# 내 사용자 설정
"sandbox": { "filesystem": { "allowWrite": ["~/.kube"] } }
# 실제 적용
["/opt/company-tools", "~/.kube"] ← 둘 다 들어간다deny에 넣는 편이 확실합니다.배열인데 합쳐지지 않는 예외가 둘 있습니다. fallbackModel은 순서 자체가 의미를 갖는 체인이라 가장 높은 순위 파일의 값이 통째로 쓰이고, availableModels는 최상위 관리자 설정이 정의하면 그 목록이 그대로 고정돼 아래에서 늘릴 수 없습니다.
4. 고쳤는데 안 먹을 때
순서대로 확인하면 대부분 잡힙니다.
① /status로 로드됐는지 본다. Status 탭의 Setting sources 줄에 이번 세션이 읽은 출처가 나열됩니다. 키가 하나라도 실린 파일만 목록에 뜨기 때문에, JSON이 깨진 파일은 아예 안 보입니다. 내가 고친 파일이 목록에 없다면 그게 답입니다.
② 재시작이 필요한 키인지 본다. 클로드 코드는 설정 파일을 감시하다가 바뀌면 다시 읽어들이므로 permissions·hooks·apiKeyHelper 같은 대부분의 키는 세션을 켜 둔 채로 반영됩니다. 예외가 둘입니다.
| 키 | 언제 반영되나 |
|---|---|
model |
다음 실행부터. 지금 바꾸려면 /model |
outputStyle |
시스템 프롬프트 일부라 /clear나 재시작 후 |
③ JSON이 깨졌는지 본다. 사용자·프로젝트·로컬 설정에 잘못된 JSON이나 검증에 걸리는 값이 있으면 시작할 때 Settings Error 대화상자가 뜹니다. 그냥 넘어갔다면 claude doctor로 파일별 오류를 볼 수 있습니다.
# JSON 문법만 빠르게 확인 (mac / Linux)
python3 -m json.tool ~/.claude/settings.json
# 클로드 코드가 보는 오류 전체
claude doctor편집기에서 미리 잡고 싶다면 파일 맨 위에 스키마를 걸어 두면 됩니다. VS Code 등에서 자동완성과 검증이 붙습니다.
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": ["Bash(npm run lint)", "Bash(npm run test *)"],
"deny": ["Bash(curl *)", "Read(./.env)", "Read(./secrets/**)"]
},
"env": {
"CLAUDE_CODE_ENABLE_TELEMETRY": "1"
}
}다만 스키마는 주기적으로만 갱신되므로, 최근에 추가된 설정에 경고가 떠도 잘못된 설정이라는 뜻은 아닙니다.
5. 자주 쓰는 키
| 키 | 하는 일 |
|---|---|
permissions |
도구 허용·차단 규칙과 기본 권한 모드 |
hooks |
생명주기 이벤트에 붙일 명령 |
env |
모든 세션과 하위 프로세스에 적용할 환경변수 |
model |
기본 모델 지정 (--model·ANTHROPIC_MODEL이 한 세션 한정으로 덮는다) |
statusLine |
상태줄 커스터마이즈 |
cleanupPeriodDays |
세션 파일 보관 일수 (기본 30일, 최소 1) |
spinnerTipsEnabled |
작업 중 스피너 팁 표시 (기본 true) |
hooks를 실제로 어떻게 쓰는지는 클로드 코드 훅 설정 글에서 위험 명령 차단부터 저장 후 자동 검사까지 예제로 다뤘습니다.
autoMemoryEnabled·autoMemoryDirectory도 같은 파일에 넣는 키인데, 이건 클로드 코드 메모리 글에서 저장 위치와 끄는 법까지 따로 정리했습니다.
자주 묻는 질문 (FAQ)
Q. 설정을 초기화하려면 어떻게 하나요?
해당 settings.json을 지우거나 {}로 비우면 그 범위의 설정이 사라집니다. 다만 지우기 전에 파일을 먼저 열어 보세요. 팀 공유 설정이나 직접 넣은 권한 규칙이 함께 날아갑니다. 문서에 따르면 클로드 코드가 설정 파일의 타임스탬프 백업을 최근 5개까지 보관하지만, 그것에 기대지 말고 직접 복사해 두는 편이 안전합니다.
Q. 프로젝트 설정을 팀과 공유하려면요?.claude/settings.json에 넣고 git에 커밋하면 됩니다. .claude/settings.local.json은 공유용이 아닙니다. 다만 저장소가 settings.local.json을 커밋해 배포하면 워크스페이스 신뢰 절차가 그대로 적용됩니다.
Q. 어느 파일이 이 값을 넣었는지 알 수 있나요?/status의 Setting sources는 읽어들인 출처 목록만 보여 주고, 개별 키가 어디서 왔는지는 표시하지 않습니다. 같은 대화상자의 Config 탭도 테마·verbose 같은 몇 가지 토글 편집기일 뿐 settings.json 내용을 보여 주지 않습니다.
Q. 관리자 설정에 오타가 있으면 전부 무효가 되나요?
아닙니다. 관리자 설정은 관대하게 파싱해서 문제가 된 항목만 걷어내고 나머지 정책은 그대로 적용합니다. 무엇이 걷어내졌는지는 /doctor로 파일과 필드까지 확인할 수 있습니다.
마무리
정리하면 위치는 사용자(~/.claude/) · 프로젝트(.claude/) · 로컬(settings.local.json) 셋이고, 순서는 관리자 > CLI 인자 > local > project > user입니다. 그리고 배열은 덮어쓰지 않고 합쳐진다는 것만 기억하면 대부분의 혼란이 사라집니다. 고쳤는데 안 먹으면 /status로 그 파일이 로드됐는지부터 보세요.
📚 참고 출처 (2026년 8월 5일 확인)
· Claude Code Docs — Settings
· Claude Code Docs — Slash commands
· Claude Code settings JSON schema
COMMENTS