# 설정 파일 (settings.json)

> 사용자, 프로젝트, Managed 레벨의 JSON 설정 파일로 Claude Code 동작 설정.

Claude Code는 여러 범위의 JSON 파일에서 설정을 읽습니다. 낮은 우선순위에서 높은 우선순위 순으로 병합됩니다.

## 설정 파일 위치

**전역(사용자):** `~/.claude/settings.json`
모든 프로젝트에 걸쳐 실행하는 모든 Claude Code 세션에 적용됩니다. 선호 모델, 테마, 정리 정책 같은 개인 설정을 여기에 설정합니다.

**프로젝트(공유):** `.claude/settings.json` (프로젝트 루트)
소스 컨트롤에 체크인됩니다. 프로젝트 작업자 모두에게 적용되어야 하는 설정 — 권한 규칙, 훅 설정, MCP 서버, 환경 변수.

**로컬(개인 프로젝트):** `.claude/settings.local.json` (프로젝트 루트)
소스 컨트롤에 체크인되지 않습니다(자동으로 `.gitignore`에 추가됨). 특정 프로젝트 내의 개인 재정의.

**Managed(엔터프라이즈):** 플랫폼별 시스템 경로
MDM, 레지스트리(Windows), plist(macOS), 또는 Managed 설정 파일을 통해 관리자가 설정합니다. Managed 설정은 최고 우선순위를 가지며 사용자나 프로젝트가 재정의할 수 없습니다.

## 설정 우선순위

```
플러그인 기본값 → 사용자 설정 → 프로젝트 설정 → 로컬 설정 → Managed(정책) 설정
```

Managed(정책) 설정은 항상 최종 우선순위를 가집니다.

## 설정 열기

세션 내에서 `/config`를 실행해 설정 UI를 엽니다. 각 범위의 현재 활성 설정을 찾아볼 수 있습니다. JSON 파일을 직접 편집할 수도 있습니다 — Claude Code가 파일 변경을 감지하면 자동으로 설정을 다시 로드합니다.

## 설정 레퍼런스

### `model`
**타입:** `string` | **범위:** 모든 범위

Claude Code가 사용하는 기본 모델 재정의. 설정된 공급자가 지원하는 모든 모델 ID 허용.

```json
{ "model": "claude-opus-4-5" }
```

### `permissions`
**타입:** `object` | **범위:** 모든 범위

Claude가 사용할 수 있는 도구와 모드를 제어합니다. 규칙 구문은 [권한 시스템](./06_권한시스템.md) 참조.

| 필드 | 타입 | 설명 |
|------|------|------|
| `allow` | `string[]` | Claude가 확인 없이 수행할 수 있는 작업 규칙 |
| `deny` | `string[]` | Claude가 항상 차단되는 작업 규칙 |
| `ask` | `string[]` | 항상 확인을 요청하는 작업 규칙 |
| `defaultMode` | `string` | 기본 권한 모드: `"default"`, `"acceptEdits"`, `"plan"`, `"bypassPermissions"` |
| `disableBypassPermissionsMode` | `"disable"` | 사용자가 bypass permissions 모드에 들어가는 것을 방지 |
| `additionalDirectories` | `string[]` | Claude가 접근할 수 있는 추가 디렉토리 |

### `hooks`
**타입:** `object` | **범위:** 모든 범위

도구 실행 전후에 커스텀 셸 커맨드를 실행합니다. 지원 훅 이벤트: `PreToolUse`, `PostToolUse`, `Notification`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Stop`, `SubagentStop`, `PreCompact`, `PostCompact`.

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [{ "type": "command", "command": "prettier --write $CLAUDE_FILE_PATHS" }]
      }
    ]
  }
}
```

### `cleanupPeriodDays`
**타입:** `integer` | **기본값:** `30` | **범위:** 모든 범위

채팅 트랜스크립트 보관 일수. `0`으로 설정하면 세션 영속성이 완전히 비활성화됩니다.

### `env`
**타입:** `object` | **범위:** 모든 범위

모든 Claude Code 세션에 주입할 환경 변수. 값은 문자열로 변환됩니다.

```json
{
  "env": {
    "NODE_ENV": "development",
    "MY_API_URL": "https://api.example.com"
  }
}
```

### `availableModels`
**타입:** `string[]` | **범위:** Managed만

사용자가 선택 가능한 모델의 엔터프라이즈 허용 목록. 패밀리 별칭(`"opus"`는 모든 Opus 버전 허용), 버전 프리픽스, 또는 전체 모델 ID 허용.

### `worktree`
**타입:** `object` | **범위:** 모든 범위

`--worktree` 플래그 동작 설정.

| 필드 | 타입 | 설명 |
|------|------|------|
| `symlinkDirectories` | `string[]` | worktree에 메인 저장소에서 심링크할 디렉토리 (예: `"node_modules"`) |
| `sparsePaths` | `string[]` | 대규모 모노레포에서 빠른 worktree를 위한 sparse 체크아웃 경로 |

### `attribution`
**타입:** `object` | **범위:** 모든 범위

Claude가 커밋과 PR 설명에 추가하는 어트리뷰션 텍스트를 커스터마이징합니다.

```json
{
  "attribution": {
    "commit": "Co-Authored-By: Claude <noreply@anthropic.com>",
    "pr": ""
  }
}
```

### `language`
Claude 응답과 음성 받아쓰기에 선호되는 언어. `{ "language": "korean" }`

### `alwaysThinkingEnabled`
**기본값:** `true` — `false`로 설정해 확장 thinking 비활성화.

### `effortLevel`
`"low"` | `"medium"` | `"high"` — thinking 예산을 지원하는 모델의 effort 레벨.

### `autoMemoryEnabled`
**범위:** 사용자, 로컬 — 이 프로젝트의 자동 메모리 활성화 또는 비활성화.

### `respectGitignore`
**기본값:** `true` — 파일 피커가 `.gitignore` 파일을 존중할지 여부.

### `defaultShell`
`"bash"` | `"powershell"` — 입력 박스의 `!` 커맨드용 기본 셸.

### `apiKeyHelper`
**범위:** 사용자, Managed — API 키를 동적으로 검색하는 스크립트 경로. 스크립트는 stdout에 API 키만 출력하고 코드 0으로 종료해야 합니다.

## Managed 설정 (엔터프라이즈)

관리자는 플랫폼 네이티브 메커니즘을 통해 모든 사용자에게 설정을 배포할 수 있습니다.

**macOS:** `/Library/Preferences/`에 plist 파일 배포 또는 MDM을 통해 `com.anthropic.claudecode` 타겟

**Windows:** `HKLM\Software\Anthropic\Claude Code` 레지스트리 키에 설정 작성

**파일 기반:** Managed 설정 파일을 플랫폼별 managed 경로에 배치. 드롭인 설정 조각에는 `managed-settings.d/` 디렉토리 사용(알파벳 순으로 정렬 및 병합됨).

### Managed 전용 잠금 설정

| 설정 | 설명 |
|------|------|
| `allowManagedHooksOnly` | `true`로 설정 시 Managed 설정의 훅만 실행 |
| `allowManagedPermissionRulesOnly` | `true`로 설정 시 Managed 설정의 권한 규칙만 존중 |
| `allowManagedMcpServersOnly` | `true`로 설정 시 허용 MCP 서버 목록을 Managed 설정에서만 읽음 |
| `strictPluginOnlyCustomization` | 특정 커스터마이징 표면을 플러그인 전용 소스로 잠금 |

## JSON 스키마

에디터 자동완성 및 유효성 검사를 위해 설정 파일에 `$schema` 추가:

```json
{
  "$schema": "https://schemas.anthropic.com/claude-code/settings.json"
}
```