173 lines
6.7 KiB
Markdown
173 lines
6.7 KiB
Markdown
# 설정 파일 (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"
|
|
}
|
|
```
|