Claude Code settings.json 완벽 가이드와 5계층 설정 전략
- 공유 링크 만들기
- X
- 이메일
- 기타 앱
⚙️ Claude Code settings.json 완벽 가이드
📅 2026년 5월 10일 · Claude 4.x (Opus 4.7 / Sonnet 4.6 / Haiku 4.5) 기준 최신판
config.json이 아니라 settings.json이며, 사용자·프로젝트·로컬·CLI·Managed의 5계층으로 병합되어 "안전과 속도", "개인과 조직"을 분리 보관할 수 있게 해주는 정책 파일이다.
📌 1. 결론 먼저 — 정확한 파일명은 settings.json이다
많은 가이드와 블로그가 Claude Code의 전역 설정 파일을 ~/.claude/config.json으로 안내하지만, 이는 사실과 부합하지 않는다. Anthropic 공식 문서(Claude Code settings)는 다음 3개 파일을 1차 설정 채널로 명시한다.
▶ ~/.claude/settings.json — 사용자 전역 설정
▶ <repo>/.claude/settings.json — 프로젝트 공용 (git 커밋 권장)
▶ <repo>/.claude/settings.local.json — 개인용 로컬 오버라이드 (gitignore 권장)
config.json 또는 .config.json은 Claude Code 내부 상태(로그인 토큰, 사용량 캐시 등)를 보관하는 별도 파일이며, 일반 사용자가 직접 편집하라고 만든 개인화 채널이 아니다.
⚠️ 흔한 오해 정정
• 모델 ID: claude-3-7-sonnet-latest, claude-3-5-sonnet-20241022는 모두 구버전. 2026-05 기준 최신은 Claude 4.x (Opus 4.7 / Sonnet 4.6 / Haiku 4.5).
• CLAUDE.md는 컨텍스트 주입 채널이지 설정이 아니다. settings.json과 역할이 다르므로 혼동 금지.
🏗️ 2. 5계층 설정 구조 — 누가 우선하는가
Claude Code는 다음 5개 레이어를 우선순위에 따라 병합한다. 아래로 갈수록 우선순위가 높다.
| 우선순위 | 계층 | 경로 | 용도 |
|---|---|---|---|
| 1 (최저) | User | ~/.claude/settings.json |
모든 프로젝트 공통 개인 설정 |
| 2 | Project | <repo>/.claude/settings.json |
팀 공유 표준 (git 커밋) |
| 3 | Local | <repo>/.claude/settings.local.json |
개인 오버라이드 (gitignore) |
| 4 | CLI Flags | claude --model … |
일회성 세션 제어 |
| 5 (최고) | Managed | /Library/Application Support/ClaudeCode/managed-settings.json |
조직 IT/보안 정책 강제 |
📊 계층별 영향력 — 시각화
이 구조의 설계 의도는 명확하다 — "공용 표준은 git에, 개인 취향은 로컬에, 보안 정책은 조직이". 팀이 Bash(git push:*)를 자동 허용하더라도, 개인은 settings.local.json에서 더 보수적으로 잠그거나, 반대로 자기 머신에서만 실험적인 권한을 풀어볼 수 있다.
🔑 3. 주요 설정 키 카테고리별 정리
3.1 🤖 모델 / 응답 동작
▶ model — 세션 기본 모델. "claude-opus-4-7", "claude-sonnet-4-6" 등.
▶ outputStyle — default / Explanatory / Learning.
▶ env — 세션에 주입할 환경 변수 맵. {"DEBUG": "1"}로 도구 동작 튜닝.
3.2 🔐 권한 · 보안
권한은 allow / ask / deny 3-tier로 구분된다. 도구 호출 패턴별로 정책을 박제한다.
"permissions": {
"allow": ["Read(**)", "Bash(git status:*)", "Bash(npm test:*)"],
"ask": ["Bash(git push:*)"],
"deny": ["Read(.env*)", "Bash(rm -rf:*)", "Bash(curl:*)"]
}
▶ additionalDirectories: 워크스페이스 외부 화이트리스트
▶ disableBypassPermissionsMode: --dangerously-skip-permissions 플래그 자체 차단
3.3 🎨 UI / 인터랙션
▶ statusLine — 터미널 하단 상태줄을 사용자 스크립트로 커스텀. 토큰 사용량·Git 브랜치·비용 추정치 실시간 표시.
▶ theme — dark / light / dark-daltonized.
▶ cleanupPeriodDays — 비활성 세션·임시 파일 자동 정리 주기 (기본 30일).
3.4 🔧 자동화 / 인증
▶ apiKeyHelper — API 키를 동적으로 가져오는 외부 스크립트 경로. 1Password CLI / Keychain 연동의 핵심 수단으로, 키를 평문으로 박지 않게 해준다.
▶ awsAuthRefresh / awsCredentialExport — AWS Bedrock 자격증명 자동 갱신.
▶ forceLoginMethod — claudeai / console 강제 로그인 채널.
▶ includeCoAuthoredBy — Git 커밋 메시지에 Co-authored-by: Claude 자동 부착.
3.5 ⚡ Hooks — 자동 동작 박제 (settings.json 전용)
hooks에서 구현해야 한다. 메모리는 모델이 잊거나 무시할 수 있지만, hooks는 하니스(harness)가 직접 실행하므로 100% 발동된다.
hooks 키는 이벤트 트리거 → 셸 명령 실행을 연결한다. 주요 이벤트:
▶ PreToolUse · PostToolUse — 도구 호출 전·후
▶ UserPromptSubmit — 사용자 메시지 전송 시
▶ SessionStart — 세션 시작 시 (컨텍스트 주입)
▶ Stop — 응답 완료 시
"hooks": {
"PostToolUse": [
{ "matcher": "Edit|Write",
"hooks": [{ "type": "command",
"command": "npm run lint --silent || true" }] }
]
}
3.6 🔌 MCP · 서브에이전트 · 스킬
▶ mcpServers — GitHub, Notion, Playwright 등 외부 도구 연결. (대개 별도 .mcp.json 또는 ~/.claude.json에 보관, settings.json에서는 enable/disable 제어)
▶ enabledPlugins / enabledSkills — 조직 배포 plugin·skill 활성화 토글.
🚀 4. 왜 유용한가 — 개인화의 다섯 가지 기회
📐 데이터 흐름 — 마찰 최소화 vs 안전 강화
🟢 4.1 마찰(friction) 최소화
Read, git status, npm test 같은 무해한 명령을 allow에 등록하면 매 호출마다 묻는 프롬프트가 사라진다. 반대로 git push, rm, curl은 ask/deny로 묶어 사고를 차단한다 — "안전과 속도의 분리 보관함"이 가능해진다.
💰 4.2 비용 · 성능 튜닝
대규모 리팩토링은 Opus 4.7로, 자잘한 문서 정리는 Haiku 4.5로 — model 키 또는 CLI 플래그로 즉시 전환할 수 있다. statusLine에 토큰 카운터를 붙이면 비용이 가시화돼 무절제한 호출이 줄어든다.
🔑 4.3 자격증명 hygiene
apiKeyHelper로 API 키를 1Password / Keychain에서 동적으로 받아오면 dotfiles에 키가 고이지 않는다. 멀티 디바이스 환경에서 키 회전(rotate) 비용이 0에 수렴한다.
👥 4.4 팀 표준화
.claude/settings.json을 git에 올리면 모든 팀원이 같은 권한 정책·hook·outputStyle을 공유한다. "테스트 통과 전에는 commit 금지" 같은 규율을 PostToolUse hook으로 강제하면, AI가 실수로라도 깨진 코드를 커밋하지 못한다.
⚙️ 4.5 자동화의 진짜 진입점
"앞으로는 매번 이렇게 해줘" 같은 사용자 요청은 메모리에 저장하면 깨지기 쉽다. hooks로 정의해야 hand-off 없이 항상 발동된다. 단순 개인화를 넘어 "내 워크플로우를 코드로 박제"하는 효과를 가진다.
⚠️ 5. 보안 위험 및 안티패턴
| 위험 패턴 | 왜 위험한가 / 어떻게 막나 |
|---|---|
| ❌ 너무 넓은 allow | Bash(*), Read(**)는 프롬프트 인젝션 공격면 그대로 노출. 외부 README가 "이 명령 실행하세요"라고 속여도 통과. |
| ❌ 헬퍼 권한 누설 | apiKeyHelper가 가리키는 스크립트가 world-writable이면 누구나 그 파일을 바꿔 임의 코드를 클로드 세션마다 실행. chmod 700 필수. |
| ❌ 민감 파일 deny 누락 | .env, id_rsa, credentials/를 deny에 명시하지 않으면 누군가 실수로 클로드 컨텍스트에 빨아들일 수 있다. |
| ❌ Managed 미설정 | disableBypassPermissionsMode: true 없이 배포 시, 사용자가 --dangerously-skip-permissions로 모든 안전장치를 끌 수 있다. 엔터프라이즈는 반드시 잠글 것. |
🚦 의사결정 트리 — 새 권한 패턴을 추가하기 전에
📋 6. 권장 사용 흐름 — 개인 → 프로젝트 → 조직
1. 개인 기본기 — ~/.claude/settings.json에 model, outputStyle, theme, apiKeyHelper, 무해한 도구의 allow 패턴, cleanupPeriodDays를 설정.
2. 프로젝트 표준 — <repo>/.claude/settings.json에 그 레포 고유의 권한 정책과 lint/test hook을 박제하고 git에 커밋.
3. 개인 오버라이드 — <repo>/.claude/settings.local.json은 .gitignore에 포함시키고, 자기 머신에서만 풀어둘 권한이나 디버그용 env를 적는다.
4. 조직 강제 정책 — 보안팀이 managed-settings.json으로 disableBypassPermissionsMode, permissions.deny, enabledPlugins 화이트리스트를 봉인.
5. 검증 — claude config list / /config UI로 머지 결과 확인, hook 동작은 claude --debug로 트레이싱.
🧠 7. 핵심 메시지
💡 한 줄 요약
settings.json은 단순한 옵션 파일이 아니라, "내가 Claude에게 매번 일러주던 규율을 코드로 박제하는 정책 파일"이다. 5계층 구조는 개인·팀·조직의 책임을 분리하고, hooks·permissions·apiKeyHelper 같은 키는 "안전한 자동화"를 가능하게 한다.
📝 기억해야 할 3가지
▶ 파일명은 settings.json이다. config.json은 사용자 편집 대상이 아니다.
▶ 모델 ID는 항상 현재 사용 가능한 최신(Claude 4.x 계열)인지 점검하라. 구버전 ID가 박혀 있으면 silently downgrade될 수 있다.
▶ "매번 X해줘"는 메모리가 아닌 hooks로 박제하라. 메모리는 잊혀지고, hooks는 강제된다.
📚 References
▶ Anthropic Docs — Claude Code settings
▶ Anthropic Docs — Claude Code hooks
본 가이드는 2026년 5월 기준 최신 문서를 반영하여 작성되었습니다. Claude Code의 빠른 업데이트 주기를 감안하여, 실제 적용 전 공식 문서로 최종 확인하시길 권장합니다.
📄 Raw Data
# Claude Code 설정 파일(`settings.json`) 종합 가이드
## 1. 결론 먼저 — 정확한 파일명은 `settings.json`이다
질문에서 언급한 파일명을 먼저 정정한다. **Anthropic 공식 문서 기준 Claude Code의 설정 파일은 `settings.json`이며, `config.json`이 아니다.** Round 1 자료가 `~/.claude/config.json`을 전역 설정 파일로 기술하고 Round 3 역시 `config.json`을 1차 출처라고 인용했지만, 이는 사실과 부합하지 않는다. Anthropic Docs("Claude Code settings")는 사용자 전역 설정을 `~/.claude/settings.json`, 프로젝트 공용 설정을 `.claude/settings.json`, 개인용 로컬 오버라이드를 `.claude/settings.local.json`으로 명시한다 (출처: https://docs.anthropic.com/en/docs/claude-code/settings). `config.json` 또는 `.config.json`은 Claude Code 내부 상태(로그인 토큰, 사용량 캐시 등)를 보관하는 별도 파일이며, 일반 사용자가 직접 편집해야 하는 개인화 채널이 아니다.
> **자료 간 모순 명시**
> - Round 1·Round 3: `~/.claude/config.json`을 설정 파일로 제시.
> - Round 2 및 Anthropic 공식 문서: `~/.claude/settings.json` + `.claude/settings.json` + `.claude/settings.local.json`의 3-파일 + Managed/CLI 플래그 포함 5계층 구조.
> - 본 보고서는 1차 출처인 공식 Docs를 채택한다.
또한 Round 1의 추천 모델 `claude-3-7-sonnet-latest` 및 Round 2의 `claude-3-5-sonnet-20241022` 표기 역시 2026-05 기준에서는 구버전이다. 현재 최신 계열은 **Claude 4.x — Opus 4.7, Sonnet 4.6, Haiku 4.5** 이며, `model` 키 값은 사용 환경(직접 API/Bedrock/Vertex)에 따라 지정해야 한다.
---
## 2. 설정 파일의 5계층 구조
Claude Code는 다음 우선순위로 설정을 병합한다(아래로 갈수록 우선순위 높음).
| 순위 | 종류 | 경로 | 용도 |
|------|------|------|------|
| 1 (가장 낮음) | User | `~/.claude/settings.json` | 모든 프로젝트 공통 개인 설정 |
| 2 | Project | `<repo>/.claude/settings.json` | 팀이 공유하는 프로젝트 표준 (git 커밋 권장) |
| 3 | Local | `<repo>/.claude/settings.local.json` | 개인용 프로젝트 오버라이드 (gitignore 권장) |
| 4 | CLI Flags | `claude --model …` | 일회성 세션 제어 |
| 5 (가장 높음) | Managed | macOS: `/Library/Application Support/ClaudeCode/managed-settings.json`, Linux: `/etc/claude-code/managed-settings.json` | 조직 IT/보안팀이 강제 적용하는 정책 |
이 계층 구조의 의도는 **"공용 표준은 git에, 개인 취향은 로컬에, 보안 정책은 조직이"** 라는 분리 원칙이다. 팀이 `Bash(git push:*)`를 자동 허용하더라도, 개인이 `settings.local.json`에서 더 보수적으로 잠그거나, 반대로 자기 머신에서만 실험적인 권한을 풀어볼 수 있다.
---
## 3. `settings.json`에서 설정 가능한 주요 키
공식 문서가 정의하는 주요 키를 카테고리로 정리한다.
### 3.1 모델 / 응답 동작
- **`model`** — 세션 기본 모델. 예: `"claude-opus-4-7"`, `"claude-sonnet-4-6"`. (1M 컨텍스트 변형 등은 별도 ID로 호출)
- **`outputStyle`** — `default`, `Explanatory`(아키텍처 결정 인사이트 추가), `Learning`(주니어 친화 설명) 등 응답 페르소나 변경.
- **`env`** — 세션에 주입할 환경 변수 맵. `{"DEBUG": "1", "BASH_DEFAULT_TIMEOUT_MS": "120000"}` 등으로 도구 동작 튜닝.
### 3.2 권한·보안
- **`permissions.allow / ask / deny`** — 도구 호출 패턴별 정책. 예:
```json
"permissions": {
"allow": ["Read(**)", "Bash(git status:*)", "Bash(npm test:*)"],
"ask": ["Bash(git push:*)"],
"deny": ["Read(.env*)", "Bash(rm -rf:*)", "Bash(curl:*)"]
}
```
- **`additionalDirectories`** — 워크스페이스 외부에서 접근을 허용할 디렉터리 화이트리스트.
- **`disableBypassPermissionsMode`** — `--dangerously-skip-permissions` 플래그 사용 자체를 차단(엔터프라이즈용).
### 3.3 UI / 인터랙션
- **`statusLine`** — 터미널 하단 상태줄을 사용자 스크립트로 커스텀. 토큰 사용량, Git 브랜치, 비용 추정치 등을 실시간 표시.
- **`theme`** — `dark`, `light`, `dark-daltonized` 등(개별 옵션은 `/config` UI에서도 조정 가능).
- **`cleanupPeriodDays`** — 비활성 세션·임시 파일 자동 정리 주기(기본 30일).
### 3.4 자동화 / 인증
- **`apiKeyHelper`** — API 키를 동적으로 가져오는 외부 스크립트 경로 (1Password CLI, Keychain 등 연동). 키를 평문으로 박지 않는 핵심 수단.
- **`awsAuthRefresh`** / **`awsCredentialExport`** — AWS Bedrock 사용 시 만료된 자격증명을 자동 갱신.
- **`forceLoginMethod`** — `claudeai`, `console` 중 강제 로그인 채널 지정.
- **`includeCoAuthoredBy`** — Git 커밋 메시지에 `Co-authored-by: Claude` 자동 부착 여부.
### 3.5 자동 동작 — Hooks (settings.json에서만 가능)
`hooks` 키는 **이벤트 트리거 → 셸 명령 실행**을 박제한다. 예: `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `Stop`. "매번 X를 해라"는 자동 행동은 메모리/CLAUDE.md가 아니라 반드시 hooks에서 구현해야 한다(Anthropic 공식 가이드 — `Hooks` 페이지).
```json
"hooks": {
"PostToolUse": [
{ "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "npm run lint --silent || true" }] }
]
}
```
### 3.6 MCP / 서브에이전트 / 스킬
- **`mcpServers`** *(주: 일반적으로는 별도 `.mcp.json` 또는 `~/.claude.json`에 보관되며, settings.json에서는 enable/disable과 path 제어가 가능)* — GitHub, Notion, Playwright 등 외부 도구 연결.
- **`enabledPlugins` / `enabledSkills`** — 조직 배포된 plugin/skill 활성화 토글.
> CLAUDE.md(프로젝트 메모리)는 **컨텍스트**를 주입하는 채널이지 설정이 아니다. settings.json과 역할이 다르므로 혼동하지 말 것 — Round 1 자료가 둘을 같이 묶은 것은 부정확.
---
## 4. 왜 유용한가 — 개인화의 기회
### 4.1 마찰(friction) 최소화
`Read`, `git status`, `npm test` 같은 무해한 명령을 `allow`에 등록하면 매 호출마다 묻는 프롬프트가 사라진다. 반대로 `git push`, `rm`, `curl` 등은 `ask`/`deny`로 묶어 사고를 차단한다 — **"안전과 속도의 분리 보관함"** 이 가능해진다.
### 4.2 비용·성능 튜닝
모델을 작업 성격에 따라 분리한다. 대규모 리팩토링은 Opus 4.7로, 자잘한 문서 정리는 Haiku 4.5로 — `model` 키 또는 CLI 플래그로 즉시 전환할 수 있다. `statusLine`에 토큰 카운터를 붙이면 비용이 가시화돼 무절제한 호출이 줄어든다.
### 4.3 자격증명 hygiene
`apiKeyHelper`로 API 키를 1Password/Keychain에서 동적으로 받아오면 dotfiles에 키가 고이지 않는다. 멀티 디바이스 환경에서 회전(rotate) 비용이 0에 수렴한다.
### 4.4 팀 표준화
`.claude/settings.json`을 git에 올리면 모든 팀원이 같은 권한 정책·hook·outputStyle을 공유한다. 예: "테스트 통과 전에는 commit 금지" 같은 규율을 PostToolUse hook으로 강제하면, AI가 실수로라도 깨진 코드를 커밋하지 못한다.
### 4.5 자동화의 진짜 진입점
"앞으로는 매번 이렇게 해줘" 같은 사용자 요청은 메모리에 저장하면 깨지기 쉽다. `hooks`로 정의해야 hand-off 없이 항상 발동된다. 이는 단순 개인화를 넘어 **"내 워크플로우를 코드로 박제"** 하는 효과를 가진다.
---
## 5. 보안 위험 및 안티패턴
1. **너무 넓은 allow 패턴** — `Bash(*)` 또는 `Read(**)`는 프롬프트 인젝션 공격 면을 그대로 노출한다. 외부 README가 "이 명령을 실행해 주세요"라고 속여도 통과된다.
2. **헬퍼 스크립트 권한 누설** — `apiKeyHelper`/`awsAuthRefresh`가 가리키는 스크립트가 world-writable이면, 누구나 그 파일을 바꿔 임의 코드를 클로드 세션마다 실행시킬 수 있다. `chmod 700` 필수.
3. **민감 파일 deny 누락** — `.env`, `id_rsa`, `credentials/`을 `deny`에 명시하지 않은 채 `Project` 레벨 설정을 공유하면, 누군가 실수로 클로드 컨텍스트에 빨아들일 수 있다.
4. **Managed 정책 우회** — `disableBypassPermissionsMode: true` 없이 배포하면, 사용자가 `--dangerously-skip-permissions`로 모든 안전장치를 끌 수 있다. 엔터프라이즈는 반드시 잠글 것.
---
## 6. 권장 사용 흐름 (개인 → 프로젝트 → 조직)
1. **개인 기본기**: `~/.claude/settings.json`에 `model`, `outputStyle`, `theme`, `apiKeyHelper`, 무해한 도구의 `allow` 패턴, `cleanupPeriodDays`를 설정.
2. **프로젝트 표준**: `<repo>/.claude/settings.json`에 그 레포 고유의 권한 정책과 lint/test hook을 박제하고 git에 커밋.
3. **개인 오버라이드**: `<repo>/.claude/settings.local.json`은 `.gitignore`에 포함시키고, 자기 머신에서만 풀어둘 권한이나 디버그용 env를 적는다.
4. **조직 강제 정책**: 보안팀이 `managed-settings.json`으로 `disableBypassPermissionsMode`, `permissions.deny`, `enabledPlugins` 화이트리스트를 봉인.
5. **검증**: `claude config list` / `/config` UI로 머지 결과 확인, hook 동작은 `claude --debug`로 트레이싱.
---
## 7. 핵심 메시지
`settings.json`은 단순한 옵션 파일이 아니라, **"내가 Claude에게 매번 일러주던 규율을 코드로 박제하는 정책 파일"** 이다. 5계층 구조는 개인·팀·조직의 책임을 분리하고, hooks·permissions·apiKeyHelper 같은 키는 "안전한 자동화"를 가능하게 한다. Round 1·3에서 거론된 `config.json`은 사용자 편집 대상이 아니므로 혼동하지 말 것이며, 모델 ID는 항상 현재 사용 가능한 최신(Claude 4.x 계열)인지 점검해야 한다.
## 라운드 간 모순
- Round 1은 설정 파일을 ~/.claude/config.json 으로 기술했으나 Anthropic 공식 문서 기준 실제 파일명은 settings.json (~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json)이며 config.json은 별도 내부 상태 파일임 — 1차 출처 확인 필요
- Round 1이 추천 모델로 'claude-3-7-sonnet-latest'를 제시했으나 2026-05 기준 최신 계열은 Claude 4.x (Opus 4.7, Sonnet 4.6, Haiku 4.5)로 모델명 정정 필요
- Round 1은 설정 파일을 ~/.claude/config.json 및 .claudecode/로 기술했으나 Round 2는 ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json 5계층으로 정정함
- Round 1의 기본 모델은 claude-3-7-sonnet-latest, Round 2는 claude-3-5-sonnet-20241022로 상이
---
## References
- [Anthropic Docs - Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings)
- [Anthropic Docs - Claude Code hooks](https://docs.anthropic.com/en/docs/claude-code/hooks)
- [Anthropic Docs - Claude Code IAM & permissions](https://docs.anthropic.com/en/docs/claude-code/iam)
- [Anthropic Docs - Claude Code overview](https://docs.anthropic.com/en/docs/claude-code/overview)
- 공유 링크 만들기
- X
- 이메일
- 기타 앱
댓글
댓글 쓰기