설정

공식 문서: https://code.claude.com/docs/ko/desktop

설정 범위 계층도

설정 우선순위 계층 — 위로 올라갈수록 우선순위 높음

🏢 Managed (최고 우선순위)

MDM / plist / 레지스트리 — 조직 관리자가 강제 적용

⌨️ CLI 인수 (Args)

--permission-mode, --model 등 — 실행 시 전달하는 플래그

🔒 Local

.claude/settings.local.json — gitignore, 개인 전용 로컬 설정

📁 Project

.claude/settings.json — git 커밋, 팀 공유

👤 User (최저 우선순위)

~/.claude/settings.json — 모든 프로젝트에 적용되는 개인 설정

배열 병합 규칙: permissions.allow 같은 배열 설정은 상위·하위 범위가 덮어쓰기가 아닌 병합됩니다. 모든 범위의 값이 합쳐져 적용됩니다.

초보자를 위한 설정 가이드

설정 파일이나 JSON이 낯설게 느껴진다면 이 섹션을 먼저 읽어보세요.

처음에는 이것만 확인하세요

설정 항목이 많아 보여도 처음에는 딱 세 가지만 확인하면 충분합니다.

모델 선택: Claude Desktop 앱 설정에서 원하는 모델을 고릅니다.
- Claude Sonnet — 빠른 응답 속도가 필요할 때 (기본값, 대부분의 상황에 적합)
- Claude Opus — 복잡한 분석이나 깊은 사고가 필요할 때 (응답이 느릴 수 있음)
다크 모드: 앱 설정의 "시스템 설정 → 테마"에서 라이트/다크/시스템 중 원하는 테마를 선택합니다.
언어: 인터페이스 언어가 한국어로 설정되어 있는지 확인합니다. (한국어로 질문하면 Claude도 한국어로 답변합니다)

설정을 건드리면 문제가 생기지 않을까? (FAQ)

Q. 설정을 잘못 바꾸면 원래대로 못 돌아오나요? A. 아닙니다. 설정은 언제든지 다시 변경할 수 있습니다. 기본값으로 돌리고 싶다면 설정 파일을 삭제하거나 초기화하면 됩니다.

Q. 설정을 바꾸다가 대화 내용이나 데이터가 삭제되지 않나요? A. 설정 변경은 대화 내용이나 파일에 영향을 주지 않습니다. 데이터는 안전하게 유지됩니다.

Q. 기본 설정 그대로 사용해도 되나요? A. 네, 충분합니다. 기본값만으로도 Claude의 핵심 기능을 모두 사용할 수 있습니다. 특별한 요구사항이 생겼을 때 설정을 조정하면 됩니다.

Desktop 앱 설정 vs Claude Code 설정

Claude Desktop 앱과 Claude Code는 설정 방식이 다릅니다. 두 설정은 서로 독립적으로 관리됩니다.

항목	Claude Desktop 앱	Claude Code
변경 방법	앱 내 GUI 메뉴에서 클릭으로 변경	JSON 파일 직접 편집 또는 `claude config set` 명령어
설정 파일 위치	앱이 자동으로 관리	`~/.claude/settings.json` 등
처음 사용자 난이도	쉬움 (클릭 방식)	보통 (텍스트 편집 필요)
서로 영향	독립적 — 한쪽 설정이 다른 쪽에 영향 없음	독립적

Claude Desktop 설정

Claude Desktop의 설정은 앱 내 설정 메뉴에서 변경할 수 있습니다.

일반 설정

테마: 라이트/다크/시스템 설정 따름
언어: 인터페이스 언어 선택
시작 시 실행: 컴퓨터 시작 시 자동 실행 여부

모델 선택

사용할 Claude 모델을 선택할 수 있습니다:

모델	특징	적합한 작업
Claude Opus 4.6	가장 강력한 모델, 최고 품질	복잡한 분석, 대규모 코딩
Claude Sonnet 4.6	균형 잡힌 성능과 속도	일반적인 작업 (기본값)
Claude Haiku 4.5	가장 빠른 응답 속도	간단한 질문, 빠른 작업

MCP 서버 설정

MCP(Model Context Protocol) 서버를 연결하면 Claude가 외부 도구와 데이터에 접근할 수 있습니다.

설정 파일 위치:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "서버이름": {
      "command": "실행할 명령어",
      "args": ["인자1", "인자2"]
    }
  }
}

Claude Code 설정

Claude Code는 설정 파일, 환경 변수, CLI 플래그로 설정합니다.

설정 범위와 우선순위

공식 문서: https://code.claude.com/docs/ko/settings

Claude Code는 5가지 설정 범위(scope)를 지원하며, 위에서 아래 순서로 우선순위가 적용됩니다:

우선순위	범위	위치	용도
1 (최고)	Managed	MDM/plist/레지스트리	조직 관리자가 시스템 수준에서 강제 적용
2	CLI 인수	`--settings` 플래그 등	실행 시 직접 전달하는 설정
3	Local	`.claude/settings.local.json`	개인 프로젝트 설정 (gitignore)
4	Project	`.claude/settings.json`	프로젝트 공유 설정 (git에 커밋)
5 (최저)	User	`~/.claude/settings.json`	개인 전역 설정 (모든 프로젝트에 적용)

CLI 인수 우선순위

CLI 플래그(--settings, --permission-mode 등)로 전달하는 설정은 Managed 다음으로 높은 우선순위를 가집니다. 이는 파일 기반 설정보다 항상 우선 적용됩니다.

배열 병합 규칙

permissions.allow처럼 배열 타입인 설정은 상위 범위와 하위 범위의 값이 병합(merge) 됩니다. 상위 범위가 하위 범위를 덮어쓰지 않고, 모든 범위의 값이 합쳐집니다.

주요 설정 항목

설정 키	타입	설명	예시 값
`model`	string	기본 사용 모델	`"claude-sonnet-4-6"`
`effortLevel`	string	응답 품질/속도 조절	`"low"`, `"medium"`, `"high"`, `"xhigh"`
`defaultMode`	string	기본 권한 모드	`"default"`, `"acceptEdits"`, `"plan"`, `"auto"`, `"dontAsk"`, `"bypassPermissions"`
`autoUpdatesChannel`	string	업데이트 채널	`"latest"`, `"stable"`
`permissions.allow`	array	자동 허용할 도구 목록	`["Bash(git diff *)"]`
`permissions.deny`	array	차단할 도구 목록	`["Bash(rm -rf *)"]`
`alwaysThinkingEnabled`	boolean	항상 확장 사고 활성화	`true`
`showThinkingSummaries`	boolean	사고 요약 표시 여부	`true`
`cleanupPeriodDays`	number	데이터 정리 주기 (일 단위)	`30`
`autoMemoryEnabled`	boolean	자동 메모리 기능 활성화	`true`
`claudeMdExcludes`	array	로딩에서 제외할 CLAUDE.md 경로 패턴	`["node_modules/**"]`
`disableSkillShellExecution`	boolean	스킬의 동적 컨텍스트 셸 실행 비활성화	`false`
`apiKeyHelper`	string	동적 API 키 생성 스크립트 경로	`"./scripts/get-api-key.sh"`
`attribution`	object	git 커밋/PR attribution 사용자 정의. 빈 문자열로 숨김 가능	`{"commit": "🤖 Generated with Claude Code", "pr": ""}`
`autoMode`	object	자동 모드 분류기 사용자 정의 (`environment`, `allow`, `soft_deny` 배열)	`{"soft_deny": ["$defaults", "Never run terraform apply"]}`
`availableModels`	array	`/model`, `--model` 등으로 선택 가능한 모델 제한	`["sonnet", "haiku"]`
`companyAnnouncements`	array	시작 시 사용자에게 표시할 공지사항 배열	`["Welcome to Acme Corp!"]`
`defaultShell`	string	`!` 명령의 기본 셸 (`"bash"` 또는 `"powershell"`)	`"powershell"`
`editorMode`	string	편집기 모드 설정	`"normal"`, `"vim"`
`fileSuggestion`	object	`@` 파일 자동완성 사용자 정의 명령 (stdin으로 쿼리 수신, stdout으로 경로 출력)	`{"type": "command", "command": "~/.claude/file-suggestion.sh"}`
`language`	string	Claude의 선호 응답 언어	`"japanese"`, `"korean"`
`minimumVersion`	string	자동 업데이트 하한 버전	`"2.1.100"`
`plansDirectory`	string	계획 파일 저장 위치 (기본: `~/.claude/plans`)	`"./plans"`
`prefersReducedMotion`	boolean	접근성을 위해 UI 애니메이션 감소	`true`
`prUrlTemplate`	string	PR 배지 URL 템플릿 (`{owner}`, `{repo}`, `{number}` 치환 지원)	`"https://reviews.example.com/{owner}/{repo}/pull/{number}"`
`showTurnDuration`	boolean	응답 후 턴 지속 시간 표시 (기본: `true`)	`false`
`spinnerTipsEnabled`	boolean	스피너에 팁 표시 (기본: `true`)	`false`
`spinnerTipsOverride`	object	스피너 팁 사용자 정의 (`excludeDefault`, `tips` 필드)	`{"excludeDefault": true, "tips": ["Use our internal tool X"]}`
`statusLine`	object/string	사용자 정의 상태 줄 구성	`{"type": "command", "command": "~/.claude/statusline.sh"}`
`tui`	string	터미널 UI 렌더러: `"fullscreen"` 또는 `"default"`	`"fullscreen"`
`viewMode`	string	시작 시 기본 트랜스크립트 보기 모드	`"default"`, `"verbose"`, `"focus"`
`voice`	object	음성 받아쓰기 설정: `enabled`, `mode`(`"hold"` 또는 `"tap"`), `autoSubmit`	`{"enabled": true, "mode": "tap"}`
`voiceEnabled`	boolean	`voice.enabled`에 대한 레거시 별칭	`true`
`autoScrollEnabled`	boolean	자동 스크롤 여부	`true`
`awaySummaryEnabled`	boolean	자리를 비운 후 돌아올 때 한 줄 세션 요약 표시	`true`
`allowedHttpHookUrls`	array	HTTP 훅 대상 URL 패턴 허용 목록 (`*` 와일드카드 지원)	`["https://hooks.example.com/*"]`
`httpHookAllowedEnvVars`	array	HTTP 훅 헤더에 보간 가능한 환경 변수 허용 목록	`["NODE_ENV", "PATH"]`
`allowManagedHooksOnly`	boolean	관리형/SDK 훅과 관리형 강제 플러그인 훅만 로드 (managed 전용)	`true`
`spinnerVerbs`	object	스피너 동작 동사 커스터마이징. `mode`: `"replace"` 또는 `"append"`, `verbs`: 동사 배열	`{"mode": "append", "verbs": ["Pondering", "Crafting"]}`
`showClearContextOnPlanAccept`	boolean	플랜 승인 시 "컨텍스트 초기화" 옵션 표시 (기본: `false`)	`true`
`terminalProgressBarEnabled`	boolean	지원되는 터미널에서 진행 표시줄 표시 (기본: `true`)	`false`
`fastModePerSessionOptIn`	boolean	빠른 모드를 세션별 옵트인 방식으로 요구	`true`
`respectGitignore`	boolean	`@` 파일 선택기가 `.gitignore` 패턴을 준수 (기본: `true`)	`false`
`outputStyle`	string	시스템 프롬프트 출력 스타일 조정	`"Explanatory"`
`modelOverrides`	object	Anthropic 모델 ID를 공급자별 ID로 매핑 (예: Bedrock ARN, Vertex 경로)	`{"claude-opus-4-6": "arn:aws:bedrock:..."}`
`awsAuthRefresh`	string	AWS 자격증명 갱신 스크립트 (Bedrock 연동 시)	`"aws sso login --profile myprofile"`
`awsCredentialExport`	string	AWS 자격증명 JSON 출력 스크립트	`"/bin/generate_aws_grant.sh"`
`otelHeadersHelper`	string	동적 OpenTelemetry 헤더 생성 스크립트	`"/bin/generate_otel_headers.sh"`
`disableAutoMode`	string	자동 모드 활성화 방지 — `"disable"` 설정	`"disable"`
`disableAgentView`	boolean	배경 에이전트 및 에이전트 보기(`claude agents`)를 비활성화	`true`
`disableAllHooks`	boolean	모든 hooks 및 사용자 정의 상태 줄 비활성화	`true`
`disableRemoteControl`	boolean	Remote Control 비활성화. v2.1.128 이상 필요	`true`
`syntaxHighlightingDisabled`	boolean	diff, 코드 블록, 파일 미리보기에서 구문 강조 비활성화	`true`
`env`	object	모든 세션에 적용될 환경 변수. settings.json에 정의하여 팀에 배포 가능	`{"FOO": "bar", "NODE_ENV": "production"}`
`gcpAuthRefresh`	string	GCP Application Default Credentials를 갱신하는 스크립트 (Vertex AI 연동 시)	`"gcloud auth application-default login"`
`parentSettingsBehavior`	string	(Managed 전용) embedding host 프로세스 제공 managed 설정 동작 제어: `"first-wins"` 또는 `"merge"`. v2.1.133+ 필요	`"merge"`
`policyHelper`	object	(Managed 전용) 시작 시 managed 설정을 동적으로 계산하는 실행 파일. v2.1.136+ 필요	`{"path": "/usr/local/bin/claude-policy"}`
`claudeMd`	string	(Managed 전용) 조직 관리 메모리로 주입되는 CLAUDE.md 스타일 지침. 모든 세션에 적용	`"Always run make lint before committing."`
`agent`	string	메인 스레드를 명명된 서브에이전트로 실행. 해당 서브에이전트의 시스템 프롬프트, 도구 제한, 모델이 적용됨	`"code-reviewer"`
`autoMemoryDirectory`	string	자동 메모리 저장소 사용자 정의 디렉토리 (`~/` 확장 경로 허용). 보안 이유로 프로젝트 설정에서는 허용되지 않음. User/Local/Managed 설정에서만 사용	`"~/my-memory-dir"`
`deniedMcpServers`	array	(Managed 설정에서 사용) 명시적으로 차단할 MCP 서버 거부 목록. Managed 서버 포함 모든 범위에 적용. 거부 목록이 허용 목록보다 우선	`[{"serverName": "filesystem"}]`
`disabledMcpjsonServers`	array	`.mcp.json` 파일에서 거부할 특정 MCP 서버 목록	`["filesystem"]`
`enableAllProjectMcpServers`	boolean	프로젝트 `.mcp.json`에 정의된 모든 MCP 서버를 자동 승인	`true`
`enabledMcpjsonServers`	array	`.mcp.json` 파일에서 승인할 특정 MCP 서버 목록	`["memory", "github"]`
`feedbackSurveyRate`	number	세션 품질 설문조사 표시 확률 (0–1). `0`으로 완전히 억제. Bedrock/Vertex 사용 시 유용	`0.05`
`includeGitInstructions`	boolean	Claude 시스템 프롬프트에 기본 제공 커밋/PR 워크플로우 지침 및 git 상태 스냅샷 포함 (기본: `true`). 자체 git 워크플로우 스킬을 사용할 때 `false` 설정	`false`
`pluginTrustMessage`	string	(Managed 전용) 플러그인 설치 전 신뢰 경고에 추가할 사용자 정의 메시지. 내부 마켓플레이스 검증 확인 등에 활용	`"All plugins from our marketplace are approved by IT"`
`skipWebFetchPreflight`	boolean	WebFetch 도메인 안전 검사 건너뛰기. Anthropic API로의 트래픽을 차단하는 환경(Bedrock, Vertex, Foundry 등)에서 `true` 설정	`true`
`sshConfigs`	array	Desktop 환경 드롭다운에 표시할 SSH 연결 설정. 각 항목에 `id`, `name`, `sshHost` 필수. Managed 설정에서는 읽기 전용	`[{"id": "dev-vm", "name": "Dev VM", "sshHost": "user@dev.example.com"}]`
`teammateMode`	string	에이전트 팀 표시 방식: `"auto"` (tmux/iTerm2에서 분할 창, 그 외에는 in-process), `"in-process"`, `"tmux"`	`"in-process"`
`useAutoModeDuringPlan`	boolean	자동 모드 사용 가능 시 계획 모드에서도 자동 모드 의미론 사용 여부 (기본: `true`). 공유 프로젝트 설정에서는 읽지 않음	`false`

$schema로 자동완성 활성화

settings.json 파일 첫 줄에 $schema 필드를 추가하면 VS Code, Cursor 등의 편집기에서 설정 키 자동완성과 인라인 검증이 활성화됩니다:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json"
}

Plan Mode 설정

defaultMode: "plan" 으로 설정하면 Claude가 작업 전 항상 계획을 세우고 사용자 승인을 받습니다. 인터랙티브 모드에서는 Shift+Tab으로 토글할 수 있습니다.

설정 파일 예시

User 설정 (~/.claude/settings.json):

{
  "model": "claude-sonnet-4-6",
  "effortLevel": "high",
  "autoUpdatesChannel": "stable",
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(npm test *)",
      "Bash(npx prettier *)"
    ]
  }
}

Project 설정 (.claude/settings.json):

{
  "permissions": {
    "allow": [
      "Bash(npm run build *)",
      "Bash(npm run lint *)",
      "Bash(npx vitest *)"
    ],
    "deny": [
      "Bash(rm -rf *)"
    ]
  }
}

권한 규칙 (Permission Rules)

권한 규칙은 glob 패턴을 사용하여 특정 명령어나 도구의 자동 허용/차단을 설정합니다:

{
  "permissions": {
    "allow": [
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(npm test *)",
      "Bash(npx prettier --write *)",
      "Bash(npx eslint --fix *)",
      "Read(*)",
      "Write(src/**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)",
      "Write(node_modules/**)"
    ]
  }
}

권한 규칙 패턴 문법

*는 모든 인자와 매칭됩니다
Bash(git diff *) - git diff로 시작하는 모든 명령어 허용
Write(src/**) - src 하위 모든 경로의 파일 쓰기 허용
Read(*) - 모든 파일 읽기 허용

permissions 객체에서 세 가지 규칙 배열과 추가 옵션을 지원합니다:

키	설명
`allow`	도구 사용을 자동 허용하는 규칙 배열
`ask`	도구 사용 시 확인 요청 규칙 배열
`deny`	도구 사용을 거부하는 규칙 배열
`additionalDirectories`	Claude가 액세스할 수 있는 추가 작업 디렉토리
`defaultMode`	기본 권한 모드: `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions`
`disableBypassPermissionsMode`	`"disable"` 설정으로 `bypassPermissions` 모드 활성화 방지
`skipDangerousModePermissionPrompt`	`bypassPermissions` 진입 전 확인 프롬프트 건너뜀

규칙 평가 순서: 거부(deny) → 요청(ask) → 허용(allow) — 첫 번째 일치 규칙이 적용됩니다.

샌드박스 설정

파일시스템과 네트워크 접근을 제한하여 보안을 강화할 수 있습니다:

{
  "sandbox": {
    "filesystem": {
      "allowWrite": ["src/**", "tests/**", "docs/**"],
      "denyRead": ["secrets/**", ".env*"]
    },
    "network": {
      "allowedDomains": [
        "api.github.com",
        "registry.npmjs.org"
      ]
    }
  }
}

샌드박싱 지원 환경

파일시스템 샌드박싱은 macOS와 Linux(WSL 2 포함)에서만 지원됩니다. Windows 네이티브(Git Bash)에서는 사용할 수 없습니다.

Sandbox 주요 설정 키:

키	설명
`sandbox.enabled`	bash 샌드박싱 활성화 (기본: `false`)
`sandbox.failIfUnavailable`	샌드박스 시작 불가 시 오류 종료
`sandbox.filesystem.allowWrite`	샌드박싱된 명령이 쓸 수 있는 추가 경로
`sandbox.filesystem.denyWrite`	쓰기 차단 경로
`sandbox.filesystem.denyRead`	읽기 차단 경로
`sandbox.network.allowedDomains`	아웃바운드 허용 도메인 배열
`sandbox.network.deniedDomains`	아웃바운드 차단 도메인 배열
`sandbox.network.allowLocalBinding`	localhost 포트 바인딩 허용 (macOS만, 기본: `false`)

플러그인 설정

플러그인 활성화/비활성화 및 마켓플레이스 등록을 설정합니다:

{
  "enabledPlugins": {
    "formatter@acme-tools": true,
    "deployer@acme-tools": true,
    "analyzer@security-plugins": false
  },
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": "github",
      "repo": "acme-corp/claude-plugins"
    }
  }
}

enabledPlugins 형식: "plugin-name@marketplace-name": true/false
extraKnownMarketplaces: 조직 내부 플러그인 마켓플레이스 등록

managed-settings.d 드롭인 디렉토리

여러 팀이 독립적으로 정책 조각을 배포할 수 있도록 managed-settings.d/ 디렉토리를 지원합니다:

macOS: /Library/Application Support/ClaudeCode/managed-settings.d/
Linux: /etc/claude-code/managed-settings.d/
managed-settings.json 먼저 병합 → 드롭인 파일은 알파벳순으로 병합
숫자 접두사로 병합 순서 제어: 10-telemetry.json, 20-security.json
설정 파일은 타임스탬프 백업 자동 생성 (최근 5개 유지)

~/.claude.json 글로벌 사용자 설정

~/.claude.json 파일은 모든 프로젝트에 걸쳐 적용되는 개인 전역 설정으로, IDE 연동 및 외부 편집기 관련 항목을 포함합니다:

{
  "autoConnectIde": true,
  "autoInstallIdeExtension": true,
  "externalEditorContext": "vscode"
}

설정 키	타입	설명
`autoConnectIde`	boolean	IDE 자동 연결 여부
`autoInstallIdeExtension`	boolean	IDE 확장 자동 설치 여부
`externalEditorContext`	string	외부 편집기 컨텍스트 (`"vscode"`, `"cursor"` 등)

~/.claude.json vs ~/.claude/settings.json

~/.claude.json은 IDE 연동처럼 시스템 수준의 개인 설정을 저장하고, ~/.claude/settings.json은 Claude Code의 동작(모델, 권한, 도구 등)을 제어하는 설정입니다. 두 파일은 독립적으로 관리됩니다.

워크트리(Worktree) 설정

worktree 설정으로 git 워크트리 생성 시 동작을 조정할 수 있습니다:

{
  "worktree": {
    "symlinkDirectories": ["node_modules", ".venv", "dist"],
    "sparsePaths": ["src/**", "tests/**", "package.json"]
  }
}

설정 키	타입	설명
`worktree.symlinkDirectories`	array	워크트리 생성 시 심볼릭 링크로 공유할 디렉터리 목록 (빌드 캐시, 의존성 등)
`worktree.sparsePaths`	array	스파스 체크아웃(sparse checkout) 시 포함할 경로 패턴 목록

워크트리 최적화

node_modules, .venv 같은 무거운 의존성 디렉터리를 symlinkDirectories에 추가하면 워크트리 생성 속도가 크게 향상됩니다.

CLAUDE.md 파일

프로젝트 루트에 CLAUDE.md 파일을 만들어 프로젝트별 지침을 설정할 수 있습니다:

# 프로젝트 가이드

- TypeScript를 사용합니다
- 테스트는 Jest로 작성합니다
- 커밋 메시지는 한국어로 작성합니다

주요 환경 변수

기본 설정 변수

변수	설명	예시
`ANTHROPIC_API_KEY`	API 인증 키	`sk-ant-...`
`CLAUDE_MODEL`	사용할 모델	`claude-sonnet-4-6`
`CLAUDE_MAX_TOKENS`	최대 출력 토큰	`16000`
`DISABLE_AUTOUPDATER`	자동 업데이트 비활성화	`1`
`HTTPS_PROXY`	프록시 서버	`http://proxy:8080`
`CLAUDE_CODE_DISABLE_CRON`	크론 기능 비활성화	`1`

확장 사고 관련 변수

변수	설명	예시
`MAX_THINKING_TOKENS`	최대 사고 토큰 수	`10000`
`CLAUDE_CODE_EFFORT_LEVEL`	기본 노력 수준	`low`, `medium`, `high`, `xhigh`
`CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`	적응형 사고 비활성화	`1`

인터랙티브 모드 변수

변수	설명	예시
`CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION`	프롬프트 제안 활성화	`1`
`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`	백그라운드 태스크 비활성화	`1`

서브 에이전트 및 태스크 변수

변수	설명	예시
`CLAUDE_CODE_SUBAGENT_MODEL`	서브 에이전트에 사용할 모델	`claude-haiku-4-5`
`CLAUDE_CODE_TASK_LIST_ID`	특정 태스크 목록 ID 지정	`task-list-123`
`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`	세션 종료 훅 타임아웃 (밀리초)	`5000`
`CLAUDE_CODE_FORK_SUBAGENT`	`1`로 설정하면 `/fork` 서브에이전트 기능 활성화	`1`
`CLAUDE_CODE_NEW_INIT`	`1`로 설정하면 `/init` 실행 시 대화형 초기화 플로우 사용	`1`
`CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX`	원격 제어 세션 이름 접두사	`"myteam-"`

# API 키 설정
export ANTHROPIC_API_KEY="your-key"

# 모델 선택
export CLAUDE_MODEL="claude-sonnet-4-6"

# 최대 토큰 수
export CLAUDE_MAX_TOKENS=16000

# 확장 사고 최대 토큰
export MAX_THINKING_TOKENS=10000

# 기본 노력 수준
export CLAUDE_CODE_EFFORT_LEVEL=high

# 서브 에이전트에 빠른 모델 사용
export CLAUDE_CODE_SUBAGENT_MODEL=claude-haiku-4-5

권한 모드

Claude Code의 파일 접근 권한을 설정합니다:

ask: 모든 파일 변경 시 확인 요청 (기본값)
auto: 안전한 변경은 자동 승인

claude --permission-mode auto

실전 예제: 프로젝트별 설정 구성하기

웹 프로젝트를 팀에서 사용하는 경우의 전체 설정 예시입니다.

1단계: 팀 공유 설정 (`.claude/settings.json`)

이 파일은 git에 커밋하여 팀 전체가 공유합니다:

{
  "model": "claude-sonnet-4-6",
  "effortLevel": "high",
  "permissions": {
    "allow": [
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git status)",
      "Bash(npm run build *)",
      "Bash(npm run lint *)",
      "Bash(npm test *)",
      "Bash(npx prettier --write *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)",
      "Bash(git reset --hard *)"
    ]
  }
}

2단계: 개인 로컬 설정 (`.claude/settings.local.json`)

이 파일은 .gitignore에 추가하여 개인만 사용합니다:

{
  "defaultMode": "auto",
  "permissions": {
    "allow": [
      "Bash(docker compose *)",
      "Bash(psql *)"
    ]
  }
}

3단계: 프로젝트 지침 (`CLAUDE.md`)

# 프로젝트 가이드

## 기술 스택
- Next.js 14 (App Router) + TypeScript
- Prisma + PostgreSQL
- Tailwind CSS

## 규칙
- 컴포넌트는 함수형으로 작성
- 한국어로 주석 작성
- Conventional Commits 사용

## 명령어
- 빌드: `npm run build`
- 테스트: `npm test`
- 린트: `npm run lint`

4단계: `.gitignore` 설정

# Claude Code 로컬 설정
.claude/settings.local.json

연계 기능

설정을 구성한 후 함께 활용하면 더 강력해지는 기능들입니다.

📋

규칙 (Rules)

rules.md — 설정 파일의 permissions.allow / permissions.deny와 함께 경로별·조건별 세밀한 규칙을 정의하여 프로젝트 일관성을 유지합니다.

🔌

MCP 서버

mcp.md — claude_desktop_config.json의 mcpServers 섹션에 외부 도구(DB, API, 파일시스템)를 연결하여 Claude의 능력을 확장합니다.

🛡️

보안

security.md — 샌드박스 설정, 파일시스템 접근 제한, 민감 정보 보호 등 설정 파일의 sandbox 옵션을 활용한 보안 강화 방법을 다룹니다.

장점, 단점과 한계점

장점

5단계 세밀한 범위 제어: Managed, CLI 인수, Local, Project, User 다섯 가지 범위로 설정을 계층적으로 관리하여 조직부터 개인까지 유연하게 대응합니다.
팀 일관성 보장: Project 설정(.claude/settings.json)을 git에 커밋하면 팀 전체가 동일한 규칙과 권한으로 작업할 수 있습니다.
샌드박스 보안: 파일시스템과 네트워크 접근을 세밀하게 제한하여, 민감한 파일이나 외부 요청을 차단할 수 있습니다.
권한 규칙 유연성: glob 패턴으로 특정 명령어나 파일 경로를 자동 허용/차단하여 반복적인 승인 요청을 줄이면서도 안전하게 사용합니다.

단점과 한계점

설정 우선순위 복잡: 5단계 범위(Managed, CLI 인수, Local, Project, User)의 우선순위와 배열 병합 규칙을 이해하지 못하면 의도한 대로 설정이 적용되지 않을 수 있습니다.
JSON 수동 편집 필요: GUI 기반의 설정 화면이 없어 JSON 파일을 직접 편집해야 하며, 문법 오류 시 디버깅이 번거롭습니다.
매니지드 설정은 관리자만 가능: 최상위 우선순위인 Managed 설정은 MDM/plist/레지스트리를 통해서만 설정 가능하여, 일반 사용자가 제어할 수 없습니다.
설정 간 충돌 디버깅 어려움: 여러 범위에 걸쳐 설정이 분산되어 있으면 실제 적용된 값을 파악하기 어려울 수 있습니다.

활용 팁

설정이 예상대로 작동하지 않으면 claude doctor로 현재 적용된 설정을 확인하세요. 팀 프로젝트에서는 .claude/settings.json에 공통 규칙을 넣고, 개인 취향은 .claude/settings.local.json에 분리하는 것이 가장 깔끔합니다.

다음 단계

Chat 모드 개요 - Chat 모드 활용법
Code 모드 개요 - Claude Code 활용법

플랫폼별 설정 파일 경로

각 OS에서 Claude 설정 파일의 정확한 위치:

macOS

# 사용자 설정 (현재 사용자)
~/.claude/settings.json

# 확인 명령어
ls -la ~/.claude/

# 전체 경로
/Users/[사용자명]/.claude/settings.json

Windows

# 사용자 설정 (현재 사용자)
%APPDATA%\.claude\settings.json

# 실제 경로
C:\Users\[사용자명]\AppData\Roaming\.claude\settings.json

# PowerShell에서 확인
Get-Item $env:APPDATA\.claude\settings.json

Linux

# 사용자 설정
~/.claude/settings.json

# XDG 표준 (권장)
$XDG_CONFIG_HOME/.claude/settings.json
# 기본값: ~/.config/claude/settings.json

# 확인 명령어
cat ~/.claude/settings.json

훅(Hooks) 설정

훅은 Claude Code가 도구를 실행하기 전·후에 커스텀 스크립트를 자동으로 실행하는 기능입니다. 자동 포매팅, 보안 검증, 로깅 등에 활용합니다.

훅 종류

훅	실행 시점	용도
`PreToolUse`	도구 실행 전	보안 검증, 로깅, 차단
`PostToolUse`	도구 실행 후	자동 포매팅, 알림

설정 예시

settings.json에서 훅을 정의합니다:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "echo 'bash 실행 전: '\"$TOOL_INPUT\""
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [{
          "type": "command",
          "command": "npx prettier --write \"$TOOL_INPUT\""
        }]
      }
    ]
  }
}

주요 사용 사례

자동 포매팅: 파일 수정 후 Prettier/ESLint 자동 실행
보안 검증: 특정 명령어 실행 전 확인 로직
감사 로그: 모든 도구 사용 기록 파일에 저장
알림: 특정 작업 완료 시 Slack 메시지 발송

엔터프라이즈 관리형 설정 (Managed Settings)

조직 관리자는 MDM(Mobile Device Management) 또는 시스템 정책을 통해 Claude Code 설정을 중앙에서 관리할 수 있습니다. 관리형 설정은 최고 우선순위를 가지며 사용자가 변경할 수 없습니다.

파일 위치

OS	경로
macOS	`/Library/Application Support/ClaudeCode/managed-settings.json`
Windows (시스템)	`HKLM\SOFTWARE\Policies\ClaudeCode` 레지스트리 + JSON `Settings` 값
Windows (사용자)	`HKCU\SOFTWARE\Policies\ClaudeCode`
Linux/WSL	`/etc/claude-code/managed-settings.json`
Windows (파일)	`C:\Program Files\ClaudeCode\managed-settings.json`

엔터프라이즈 전용 관리형 설정 키

설정 키	설명
`forceLoginMethod`	로그인 방식 제한: `"claudeai"` 또는 `"console"`
`forceLoginOrgUUID`	특정 조직 UUID에 속한 계정만 로그인 허용 (문자열 또는 배열)
`disableDeepLinkRegistration`	`claude-cli://` 프로토콜 등록 방지 — `"disable"` 설정
`forceRemoteSettingsRefresh`	원격 설정 수신 전까지 CLI 시작 차단
`wslInheritsWindowsSettings`	WSL에서 Windows 관리형 설정 체인을 읽도록 허용
`allowedChannelPlugins`	허용할 채널 플러그인 목록: `[{"marketplace": "...", "plugin": "..."}]`
`blockedMarketplaces`	차단할 마켓플레이스 소스: `[{"source": "github", "repo": "untrusted/plugins"}]`
`channelsEnabled`	팀/엔터프라이즈 사용자에게 채널 기능 허용
`allowManagedMcpServersOnly`	`allowedMcpServers` 관리형 설정만 적용
`allowManagedPermissionRulesOnly`	사용자/프로젝트 권한 규칙 정의 방지
`strictKnownMarketplaces`	플러그인 설치 허용 마켓플레이스 소스 화이트리스트

Windows 레거시 경로 지원 중단

C:\ProgramData\ClaudeCode\managed-settings.json 경로는 v2.1.75부터 더 이상 지원되지 않습니다. 해당 위치에 설정을 배포한 관리자는 파일을 C:\Program Files\ClaudeCode\managed-settings.json으로 마이그레이션해야 합니다.

드롭인 디렉토리 (`managed-settings.d/`)

파일 기반 managed 설정은 동일한 시스템 디렉토리에 managed-settings.d/ 드롭인 디렉토리도 지원합니다. 이를 통해 별도의 팀이 단일 파일 편집을 조율하지 않고 독립적인 정책 조각을 배포할 수 있습니다.

managed-settings.json이 먼저 기본으로 병합되고, managed-settings.d/ 디렉토리의 모든 *.json 파일이 알파벳순으로 정렬되어 그 위에 병합됩니다.
스칼라 값의 경우 나중 파일이 이전 파일을 재정의합니다. 배열은 연결·중복 제거됩니다. 객체는 깊게 병합됩니다.
.으로 시작하는 숨겨진 파일은 무시됩니다.
병합 순서를 제어하려면 숫자 접두사를 사용합니다 (예: 10-telemetry.json, 20-security.json).

예시 (macOS MDM plist)

{
  "locked": {
    "allowedTools": ["Read", "Write", "Bash(git *)"],
    "disallowedTools": ["computer", "Bash(sudo *)"]
  },
  "defaults": {
    "model": "claude-sonnet-4-6",
    "effortLevel": "high"
  }
}

locked: 사용자가 변경 불가능한 설정
defaults: 사용자가 덮어쓸 수 있는 기본값

배열 설정 병합 규칙

permissions.allow, blockedCommands 등 배열 설정의 병합 방식:

병합 우선순위 (높음 → 낮음)

Managed (MDM/엔터프라이즈)         ← 최고 우선순위
    ↓
Local (.claude/settings.local.json)
    ↓
Project (.claude/settings.json)
    ↓
User (~/.claude/settings.json)     ← 최저 우선순위

병합 규칙

설정 타입	병합 방식	예시
배열	합집합 (중복 제거)	두 수준의 permissions.allow 모두 포함
객체	덮어쓰기	하위 수준이 상위 수준 완전 대체
문자열	덮어쓰기	가장 구체적인 수준만 사용

예시

// User 설정
{
  "permissions": { "allow": ["bash", "git"] }
}

// Project 설정
{
  "permissions": { "allow": ["node", "npm"] }
}

// 결과: ["bash", "git", "node", "npm"] (중복 제거)

중복 제거 규칙:

배열에서 같은 항목이 여러 수준에 있으면 한 번만 포함
패턴 매칭은 정확히 일치하는 경우만 중복으로 간주

Sandbox 설정

sandbox 키 아래에서 bash 명령을 파일 시스템 및 네트워크로부터 격리하는 샌드박싱 동작을 구성합니다.

설정 키	설명	예시 값
`sandbox.enabled`	bash 샌드박싱 활성화 (macOS, Linux, WSL2). 기본값: `false`	`true`
`sandbox.failIfUnavailable`	샌드박스를 시작할 수 없는 경우 시작 시 오류로 종료 (기본: `false`). 샌드박싱을 필수 요구사항으로 적용할 때 사용	`true`
`sandbox.autoAllowBashIfSandboxed`	샌드박싱 시 bash 명령 자동 승인 (기본: `true`)	`true`
`sandbox.excludedCommands`	샌드박스 외부에서 실행해야 하는 명령 목록	`["docker *"]`
`sandbox.allowUnsandboxedCommands`	`dangerouslyDisableSandbox` 매개변수로 샌드박스 외부 명령 실행 허용. `false`이면 이스케이프 해치 완전 비활성화 (기본: `true`)	`false`
`sandbox.filesystem.allowWrite`	샌드박싱된 명령이 쓸 수 있는 추가 경로. 모든 설정 범위에서 병합	`["/tmp/build", "~/.kube"]`
`sandbox.filesystem.denyWrite`	샌드박싱된 명령이 쓸 수 없는 경로. 모든 설정 범위에서 병합	`["/etc", "/usr/local/bin"]`
`sandbox.filesystem.denyRead`	샌드박싱된 명령이 읽을 수 없는 경로. 모든 설정 범위에서 병합	`["~/.aws/credentials"]`
`sandbox.filesystem.allowRead`	`denyRead` 영역 내에서 읽기를 다시 허용할 경로. `denyRead`보다 우선	`["."]`
`sandbox.filesystem.allowManagedReadPathsOnly`	(Managed 전용) Managed 설정의 `allowRead` 경로만 적용 (기본: `false`)	`true`
`sandbox.network.allowedDomains`	아웃바운드 트래픽 허용 도메인 배열. 와일드카드 지원 (예: `*.example.com`)	`["github.com", "*.npmjs.org"]`
`sandbox.network.deniedDomains`	아웃바운드 트래픽 차단 도메인. `allowedDomains`보다 우선	`["sensitive.cloud.example.com"]`
`sandbox.network.allowUnixSockets`	(macOS만) Unix 소켓 경로 허용	`["~/.ssh/agent-socket"]`
`sandbox.network.allowAllUnixSockets`	샌드박스에서 모든 Unix 소켓 연결 허용 (Linux/WSL2에서 유일한 방법) (기본: `false`)	`true`
`sandbox.network.allowLocalBinding`	localhost 포트 바인딩 허용 (macOS만, 기본: `false`)	`true`
`sandbox.network.httpProxyPort`	사용자 정의 HTTP 프록시 포트. 미지정 시 Claude가 자체 프록시 실행	`8080`
`sandbox.network.socksProxyPort`	사용자 정의 SOCKS5 프록시 포트	`8081`
`sandbox.enableWeakerNestedSandbox`	비권한 Docker 환경에서 더 약한 샌드박스 활성화 (Linux/WSL2만). 보안 감소 (기본: `false`)	`true`
`sandbox.enableWeakerNetworkIsolation`	(macOS만) 샌드박스에서 시스템 TLS 신뢰 서비스 접근 허용. MITM 프록시 사용 시 필요. 보안 감소 (기본: `false`)	`true`

Sandbox 설정 예시

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker *"],
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"],
      "allowLocalBinding": true
    }
  }
}

Sandbox 경로 접두사

filesystem.allowWrite, filesystem.denyWrite, filesystem.denyRead, filesystem.allowRead 경로는 다음 접두사를 지원합니다:

접두사	의미	예시
`/`	파일 시스템 루트의 절대 경로	`/tmp/build`
`~/`	홈 디렉토리에 상대적	`~/.kube` → `$HOME/.kube`
`./` 또는 접두사 없음	프로젝트 설정 시 프로젝트 루트 기준, 사용자 설정 시 `~/.claude` 기준	`./output` → `<project-root>/output`

Worktree 설정

--worktree가 git worktrees를 생성·관리하는 방식을 구성합니다. 대규모 모노레포에서 디스크 사용량과 시작 시간을 줄이는 데 유용합니다.

설정 키	설명	예시 값
`worktree.symlinkDirectories`	각 worktree에서 중복을 피하기 위해 메인 저장소에서 심볼릭 링크할 디렉토리	`["node_modules", ".cache"]`
`worktree.sparsePaths`	git sparse-checkout(cone mode)을 통해 각 worktree에서 체크아웃할 디렉토리. 나열된 경로만 디스크에 기록되어 대규모 모노레포에서 빠름	`["packages/my-app", "shared/utils"]`

.worktreeinclude 파일 활용

worktree에 .env와 같은 gitignored 파일을 복사하려면 설정 대신 프로젝트 루트의 .worktreeinclude 파일을 사용하세요.

전역 구성 설정 (`~/.claude.json`)

아래 설정은 settings.json이 아닌 ~/.claude.json에 저장됩니다. settings.json에 추가하면 스키마 검증 오류가 발생합니다.

버전 참고

v2.1.119 이전 버전은 autoScrollEnabled, editorMode, showTurnDuration, teammateMode, terminalProgressBarEnabled를 settings.json 대신 ~/.claude.json에 저장합니다.

설정 키	설명	예시 값
`autoConnectIde`	외부 터미널에서 시작 시 실행 중인 IDE에 자동 연결 (기본: `false`)	`true`
`autoInstallIdeExtension`	VS Code 터미널에서 실행 시 Claude Code IDE 확장 자동 설치 (기본: `true`)	`false`
`externalEditorContext`	`Ctrl+G`로 외부 편집기를 열 때 Claude의 이전 응답을 `#` 주석 처리된 컨텍스트로 앞에 붙임 (기본: `false`). `/config`에 외부 편집기에 마지막 응답 표시로 표시됨	`true`

/status 명령 활용

/status 명령을 실행하면 현재 Claude Code 상태 정보를 확인할 수 있습니다. 설정 소스, 활성 모드, 메모리 경로 등 디버깅에 유용한 정보를 제공합니다.

설정 범위 계층도​

초보자를 위한 설정 가이드​

처음에는 이것만 확인하세요​

설정을 건드리면 문제가 생기지 않을까? (FAQ)​

Desktop 앱 설정 vs Claude Code 설정​

Claude Desktop 설정​

일반 설정​

모델 선택​

MCP 서버 설정​

Claude Code 설정​

설정 범위와 우선순위​

주요 설정 항목​

설정 파일 예시​

권한 규칙 (Permission Rules)​

샌드박스 설정​

플러그인 설정​

~/.claude.json 글로벌 사용자 설정​

워크트리(Worktree) 설정​

CLAUDE.md 파일​

주요 환경 변수​

기본 설정 변수​

확장 사고 관련 변수​

인터랙티브 모드 변수​

서브 에이전트 및 태스크 변수​

권한 모드​

실전 예제: 프로젝트별 설정 구성하기​

1단계: 팀 공유 설정 (.claude/settings.json)​

2단계: 개인 로컬 설정 (.claude/settings.local.json)​

3단계: 프로젝트 지침 (CLAUDE.md)​

4단계: .gitignore 설정​

연계 기능​

장점, 단점과 한계점​

장점​

단점과 한계점​

다음 단계​

플랫폼별 설정 파일 경로​

macOS​

Windows​

Linux​

훅(Hooks) 설정​

훅 종류​

설정 예시​

주요 사용 사례​

엔터프라이즈 관리형 설정 (Managed Settings)​

파일 위치​

엔터프라이즈 전용 관리형 설정 키​

드롭인 디렉토리 (managed-settings.d/)​

예시 (macOS MDM plist)​

배열 설정 병합 규칙​

병합 우선순위 (높음 → 낮음)​

병합 규칙​

예시​

Sandbox 설정​

Sandbox 설정 예시​

Sandbox 경로 접두사​

Worktree 설정​

전역 구성 설정 (~/.claude.json)​