Claude Code 설정

전역 및 프로젝트 수준 설정과 환경 변수를 사용하여 Claude Code를 구성합니다.

Claude Code는 사용자의 필요에 맞게 동작을 구성할 수 있는 다양한 설정을 제공합니다. 대화형 REPL에서 /config 명령을 실행하면 탭 형태의 Settings 인터페이스가 열리며, 여기서 상태 정보를 확인하고 구성 옵션을 수정할 수 있습니다.

구성 범위

Claude Code는 범위 시스템을 사용하여 구성이 적용되는 위치와 공유 대상을 결정합니다. 범위를 이해하면 개인 사용, 팀 협업 또는 기업 배포에 맞게 Claude Code를 구성하는 데 도움이 됩니다.

사용 가능한 범위

범위	위치	영향을 받는 대상	팀과 공유 여부
Managed	서버 관리 설정, plist / 레지스트리, 또는 시스템 수준 managed-settings.json	해당 머신의 모든 사용자	예 (IT 부서에서 배포)
User	~/.claude/ 디렉토리	모든 프로젝트에서 본인만	아니오
Project	저장소 내 .claude/	이 저장소의 모든 협업자	예 (git에 커밋됨)
Local	.claude/*.local.* 파일	이 저장소에서 본인만	아니오 (gitignore 처리됨)

각 범위를 사용해야 하는 경우

Managed 범위는 다음과 같은 용도에 적합합니다:

• 조직 전체에 반드시 적용해야 하는 보안 정책
• 재정의할 수 없는 컴플라이언스 요구사항
• IT/DevOps에서 배포하는 표준화된 구성

User 범위는 다음과 같은 용도에 적합합니다:

• 모든 곳에서 사용할 개인 선호 설정 (테마, 에디터 설정)
• 모든 프로젝트에서 사용하는 도구 및 플러그인
• API 키 및 인증 정보 (안전하게 저장)

Project 범위는 다음과 같은 용도에 적합합니다:

• 팀 공유 설정 (권한, 훅, MCP 서버)
• 팀 전체가 사용해야 하는 플러그인
• 협업자 간 도구 표준화

Local 범위는 다음과 같은 용도에 적합합니다:

• 특정 프로젝트에 대한 개인 재정의
• 팀과 공유하기 전 구성 테스트
• 다른 사람에게는 적용되지 않는 머신별 설정

범위 간 상호 작용

동일한 설정이 여러 범위에서 구성된 경우, 더 구체적인 범위가 우선합니다:

1. Managed (최상위) - 어떤 것으로도 재정의할 수 없음
2. 명령줄 인수 - 임시 세션 재정의
3. Local - 프로젝트 및 사용자 설정을 재정의
4. Project - 사용자 설정을 재정의
5. User (최하위) - 다른 곳에서 설정하지 않은 경우 적용

예를 들어, 사용자 설정에서 권한이 허용되었지만 프로젝트 설정에서 거부된 경우, 프로젝트 설정이 우선하여 해당 권한이 차단됩니다.

범위를 사용하는 기능

범위는 많은 Claude Code 기능에 적용됩니다:

기능	User 위치	Project 위치	Local 위치
Settings	~/.claude/settings.json	.claude/settings.json	.claude/settings.local.json
Subagents	~/.claude/agents/	.claude/agents/	—
MCP servers	~/.claude.json	.mcp.json	~/.claude.json (프로젝트별)
Plugins	~/.claude/settings.json	.claude/settings.json	.claude/settings.local.json
CLAUDE.md	~/.claude/CLAUDE.md	CLAUDE.md or .claude/CLAUDE.md	CLAUDE.local.md

---

설정 파일

settings.json 파일은 계층적 설정을 통해 Claude Code를 구성하는 공식 메커니즘입니다:

• 사용자 설정은 ~/.claude/settings.json에 정의되며 모든 프로젝트에 적용됩니다.

• 프로젝트 설정은 프로젝트 디렉토리에 저장됩니다:

  • .claude/settings.json은 소스 컨트롤에 체크인되어 팀과 공유되는 설정입니다
  • .claude/settings.local.json은 체크인되지 않는 설정으로, 개인 선호 설정과 실험에 유용합니다. Claude Code는 .claude/settings.local.json이 생성될 때 git이 이 파일을 무시하도록 설정합니다.

• 관리 설정: 중앙 집중식 제어가 필요한 조직을 위해 Claude Code는 관리 설정을 위한 여러 전달 메커니즘을 지원합니다. 모두 동일한 JSON 형식을 사용하며 사용자 또는 프로젝트 설정으로 재정의할 수 없습니다:

  • 서버 관리 설정: Claude.ai 관리 콘솔을 통해 Anthropic 서버에서 전달됩니다. 서버 관리 설정을 참조하세요.
  • MDM/OS 수준 정책: macOS 및 Windows에서 네이티브 장치 관리를 통해 전달됩니다:
    • macOS: com.anthropic.claudecode 관리 환경설정 도메인 (Jamf, Kandji 또는 기타 MDM 도구의 구성 프로파일을 통해 배포)
    • Windows: HKLM\SOFTWARE\Policies\ClaudeCode 레지스트리 키에 JSON을 포함하는 Settings 값 (REG_SZ 또는 REG_EXPAND_SZ) (그룹 정책 또는 Intune을 통해 배포)
    • Windows (사용자 수준): HKCU\SOFTWARE\Policies\ClaudeCode (가장 낮은 정책 우선순위, 관리자 수준 소스가 없을 때만 사용)
  • 파일 기반: managed-settings.json 및 managed-mcp.json이 시스템 디렉토리에 배포됩니다:
    • macOS: /Library/Application Support/ClaudeCode/
    • Linux 및 WSL: /etc/claude-code/
    • Windows: C:\Program Files\ClaudeCode\

  자세한 내용은 관리 설정 및 관리 MCP 구성을 참조하세요.

  참고: 관리 배포에서는 strictKnownMarketplaces를 사용하여 플러그인 마켓플레이스 추가를 제한할 수도 있습니다. 자세한 내용은 관리 마켓플레이스 제한을 참조하세요.

• 기타 구성은 ~/.claude.json에 저장됩니다. 이 파일에는 선호 설정(테마, 알림 설정, 에디터 모드), OAuth 세션, 사용자 및 로컬 범위의 MCP 서버 구성, 프로젝트별 상태(허용된 도구, 신뢰 설정), 그리고 다양한 캐시가 포함됩니다. 프로젝트 범위의 MCP 서버는 .mcp.json에 별도로 저장됩니다.

참고: Claude Code는 구성 파일의 타임스탬프가 포함된 백업을 자동으로 생성하며, 데이터 손실을 방지하기 위해 가장 최근 5개의 백업을 유지합니다.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  },
  "companyAnnouncements": [
    "Welcome to Acme Corp! Review our code guidelines at docs.acme.com",
    "Reminder: Code reviews required for all PRs",
    "New security policy in effect"
  ]
}

위 예시의 $schema 줄은 Claude Code 설정을 위한 공식 JSON 스키마를 가리킵니다. settings.json에 추가하면 VS Code, Cursor 및 JSON 스키마 유효성 검사를 지원하는 다른 에디터에서 자동완성과 인라인 유효성 검사가 활성화됩니다.

사용 가능한 설정

settings.json은 다양한 옵션을 지원합니다:

키	설명	예시
apiKeyHelper	인증 값을 생성하기 위해 /bin/sh에서 실행되는 커스텀 스크립트. 이 값은 모델 요청 시 X-Api-Key 및 Authorization: Bearer 헤더로 전송됩니다	/bin/generate_temp_api_key.sh
cleanupPeriodDays	이 기간보다 오래 비활성 상태인 세션은 시작 시 삭제됩니다. 0으로 설정하면 모든 세션이 즉시 삭제됩니다. (기본값: 30일)	20
companyAnnouncements	시작 시 사용자에게 표시할 공지사항. 여러 공지사항을 제공하면 무작위로 순환 표시됩니다.	["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]
env	모든 세션에 적용될 환경 변수	{"FOO": "bar"}
attribution	git 커밋 및 풀 리퀘스트에 대한 어트리뷰션을 커스터마이즈합니다. 어트리뷰션 설정 참조	{"commit": "🤖 Generated with Claude Code", "pr": ""}
includeCoAuthoredBy	사용 중단됨: 대신 attribution을 사용하세요. git 커밋 및 풀 리퀘스트에 co-authored-by Claude 바이라인 포함 여부 (기본값: true)	false
includeGitInstructions	Claude의 시스템 프롬프트에 내장된 커밋 및 PR 워크플로우 지침을 포함합니다 (기본값: true). false로 설정하면 이 지침이 제거됩니다. 예를 들어 자체 git 워크플로우 스킬을 사용할 때 유용합니다. CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS 환경 변수가 설정된 경우 이 설정보다 우선합니다	false
permissions	권한 구조는 아래 표를 참조하세요.
hooks	라이프사이클 이벤트에서 실행할 커스텀 명령을 구성합니다. 형식은 훅 문서 참조	훅 참조
disableAllHooks	모든 훅과 커스텀 상태 표시줄을 비활성화합니다	true
allowManagedHooksOnly	(관리 설정 전용) 사용자, 프로젝트 및 플러그인 훅의 로딩을 방지합니다. 관리 훅과 SDK 훅만 허용합니다. 훅 구성 참조	true
allowedHttpHookUrls	HTTP 훅이 대상으로 할 수 있는 URL 패턴의 허용 목록. 와일드카드로 *를 지원합니다. 설정 시 일치하지 않는 URL의 훅이 차단됩니다. 미정의 = 제한 없음, 빈 배열 = 모든 HTTP 훅 차단. 배열은 설정 소스 간에 병합됩니다. 훅 구성 참조	["https://hooks.example.com/*"]
httpHookAllowedEnvVars	HTTP 훅이 헤더에 삽입할 수 있는 환경 변수 이름의 허용 목록. 설정 시 각 훅의 유효 allowedEnvVars는 이 목록과의 교집합입니다. 미정의 = 제한 없음. 배열은 설정 소스 간에 병합됩니다. 훅 구성 참조	["MY_TOKEN", "HOOK_SECRET"]
allowManagedPermissionRulesOnly	(관리 설정 전용) 사용자 및 프로젝트 설정에서 allow, ask 또는 deny 권한 규칙을 정의하는 것을 방지합니다. 관리 설정의 규칙만 적용됩니다. 관리 전용 설정 참조	true
allowManagedMcpServersOnly	(관리 설정 전용) 관리 설정의 allowedMcpServers만 적용됩니다. deniedMcpServers는 여전히 모든 소스에서 병합됩니다. 사용자는 여전히 MCP 서버를 추가할 수 있지만, 관리자가 정의한 허용 목록만 적용됩니다. 관리 MCP 구성 참조	true
model	Claude Code에 사용할 기본 모델을 재정의합니다	"claude-sonnet-4-6"
availableModels	사용자가 /model, --model, Config 도구 또는 ANTHROPIC_MODEL을 통해 선택할 수 있는 모델을 제한합니다. Default 옵션에는 영향을 미치지 않습니다. 모델 선택 제한 참조	["sonnet", "haiku"]
otelHeadersHelper	동적 OpenTelemetry 헤더를 생성하는 스크립트. 시작 시 및 주기적으로 실행됩니다 (동적 헤더 참조)	/bin/generate_otel_headers.sh
statusLine	컨텍스트를 표시할 커스텀 상태 표시줄을 구성합니다. statusLine 문서 참조	{"type": "command", "command": "~/.claude/statusline.sh"}
fileSuggestion	@ 파일 자동완성을 위한 커스텀 스크립트를 구성합니다. 파일 제안 설정 참조	{"type": "command", "command": "~/.claude/file-suggestion.sh"}
respectGitignore	@ 파일 선택기가 .gitignore 패턴을 준수할지 여부를 제어합니다. true(기본값)인 경우 .gitignore 패턴과 일치하는 파일은 제안에서 제외됩니다	false
outputStyle	시스템 프롬프트를 조정하기 위한 출력 스타일을 구성합니다. 출력 스타일 문서 참조	"Explanatory"
forceLoginMethod	claudeai로 설정하면 Claude.ai 계정으로 로그인을 제한하고, console로 설정하면 Claude Console (API 사용 결제) 계정으로 로그인을 제한합니다	claudeai
forceLoginOrgUUID	로그인 시 자동으로 선택할 조직의 UUID를 지정하여 조직 선택 단계를 건너뜁니다. forceLoginMethod가 설정되어 있어야 합니다	"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
enableAllProjectMcpServers	프로젝트 .mcp.json 파일에 정의된 모든 MCP 서버를 자동으로 승인합니다	true
enabledMcpjsonServers	.mcp.json 파일에서 승인할 특정 MCP 서버 목록	["memory", "github"]
disabledMcpjsonServers	.mcp.json 파일에서 거부할 특정 MCP 서버 목록	["filesystem"]
allowedMcpServers	managed-settings.json에 설정 시, 사용자가 구성할 수 있는 MCP 서버의 허용 목록. 미정의 = 제한 없음, 빈 배열 = 잠금. 모든 범위에 적용됩니다. 거부 목록이 우선합니다. 관리 MCP 구성 참조	[{ "serverName": "github" }]
deniedMcpServers	managed-settings.json에 설정 시, 명시적으로 차단되는 MCP 서버의 거부 목록. 관리 서버를 포함한 모든 범위에 적용됩니다. 거부 목록이 허용 목록보다 우선합니다. 관리 MCP 구성 참조	[{ "serverName": "filesystem" }]
strictKnownMarketplaces	managed-settings.json에 설정 시, 사용자가 추가할 수 있는 플러그인 마켓플레이스의 허용 목록. 미정의 = 제한 없음, 빈 배열 = 잠금. 마켓플레이스 추가에만 적용됩니다. 관리 마켓플레이스 제한 참조	[{ "source": "github", "repo": "acme-corp/plugins" }]
blockedMarketplaces	(관리 설정 전용) 마켓플레이스 소스의 차단 목록. 차단된 소스는 다운로드 전에 확인되므로 파일 시스템에 접근하지 않습니다. 관리 마켓플레이스 제한 참조	[{ "source": "github", "repo": "untrusted/plugins" }]
pluginTrustMessage	(관리 설정 전용) 설치 전 표시되는 플러그인 신뢰 경고에 추가되는 커스텀 메시지. 조직별 컨텍스트를 추가하는 데 사용합니다. 예를 들어 내부 마켓플레이스의 플러그인이 검증되었음을 확인할 때 사용합니다.	"All plugins from our marketplace are approved by IT"
awsAuthRefresh	.aws 디렉토리를 수정하는 커스텀 스크립트 (고급 자격 증명 구성 참조)	aws sso login --profile myprofile
awsCredentialExport	AWS 자격 증명이 포함된 JSON을 출력하는 커스텀 스크립트 (고급 자격 증명 구성 참조)	/bin/generate_aws_grant.sh
alwaysThinkingEnabled	모든 세션에서 기본적으로 확장 사고를 활성화합니다. 일반적으로 직접 편집하기보다 /config 명령을 통해 구성합니다	true
plansDirectory	계획 파일이 저장되는 위치를 커스터마이즈합니다. 경로는 프로젝트 루트를 기준으로 상대적입니다. 기본값: ~/.claude/plans	"./plans"
showTurnDuration	응답 후 턴 지속 시간 메시지를 표시합니다 (예: "Cooked for 1m 6s"). false로 설정하면 이 메시지가 숨겨집니다	true
spinnerVerbs	스피너 및 턴 지속 시간 메시지에 표시되는 동작 동사를 커스터마이즈합니다. mode를 "replace"로 설정하면 사용자 동사만 사용하고, "append"로 설정하면 기본값에 추가합니다	{"mode": "append", "verbs": ["Pondering", "Crafting"]}
language	Claude의 기본 응답 언어를 구성합니다 (예: "japanese", "spanish", "french"). Claude가 기본적으로 이 언어로 응답합니다	"japanese"
autoUpdatesChannel	업데이트를 위해 따르는 릴리스 채널. "stable"은 일반적으로 약 1주일 전 버전으로 주요 회귀가 있는 버전을 건너뛰며, "latest"(기본값)는 가장 최근 릴리스입니다	"stable"
spinnerTipsEnabled	Claude가 작업 중일 때 스피너에 팁을 표시합니다. false로 설정하면 팁이 비활성화됩니다 (기본값: true)	false
spinnerTipsOverride	스피너 팁을 커스텀 문자열로 재정의합니다. tips: 팁 문자열 배열. excludeDefault: true이면 커스텀 팁만 표시하고, false이거나 없으면 내장 팁과 병합됩니다	{ "excludeDefault": true, "tips": ["Use our internal tool X"] }
terminalProgressBarEnabled	Windows Terminal 및 iTerm2 같은 지원되는 터미널에서 진행 상태 표시줄을 활성화합니다 (기본값: true)	false
prefersReducedMotion	접근성을 위해 UI 애니메이션(스피너, 시머, 플래시 효과)을 줄이거나 비활성화합니다	true
fastModePerSessionOptIn	true인 경우, 빠른 모드는 세션 간에 유지되지 않습니다. 각 세션은 빠른 모드가 꺼진 상태로 시작되며, 사용자가 /fast로 활성화해야 합니다. 사용자의 빠른 모드 선호 설정은 여전히 저장됩니다. 세션별 옵트인 요구 참조	true
teammateMode	에이전트 팀 팀원이 표시되는 방식: auto (tmux 또는 iTerm2에서는 분할 창, 그 외에는 in-process 선택), in-process, 또는 tmux. 에이전트 팀 설정 참조	"in-process"

권한 설정

키	설명	예시
allow	도구 사용을 허용하는 권한 규칙 배열. 패턴 매칭에 대한 자세한 내용은 아래의 권한 규칙 문법 참조	[ "Bash(git diff *)" ]
ask	도구 사용 시 확인을 요청하는 권한 규칙 배열. 아래의 권한 규칙 문법 참조	[ "Bash(git push *)" ]
deny	도구 사용을 거부하는 권한 규칙 배열. Claude Code의 접근에서 민감한 파일을 제외하는 데 사용합니다. 권한 규칙 문법 및 Bash 권한 제한사항 참조	[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]
additionalDirectories	Claude가 접근할 수 있는 추가 작업 디렉토리	[ "../docs/" ]
defaultMode	Claude Code를 열 때의 기본 권한 모드	"acceptEdits"
disableBypassPermissionsMode	"disable"로 설정하면 bypassPermissions 모드가 활성화되는 것을 방지합니다. 이는 --dangerously-skip-permissions 명령줄 플래그를 비활성화합니다. 관리 설정 참조	"disable"

권한 규칙 문법

권한 규칙은 Tool 또는 Tool(specifier) 형식을 따릅니다. 규칙은 순서대로 평가됩니다: deny 규칙이 먼저, 그 다음 ask, 그 다음 allow. 첫 번째로 일치하는 규칙이 적용됩니다.

간단한 예시:

규칙	효과
Bash	모든 Bash 명령에 일치
Bash(npm run *)	npm run으로 시작하는 명령에 일치
Read(./.env)	.env 파일 읽기에 일치
WebFetch(domain:example.com)	example.com에 대한 fetch 요청에 일치

와일드카드 동작, Read, Edit, WebFetch, MCP 및 Agent 규칙에 대한 도구별 패턴, Bash 패턴의 보안 제한사항을 포함한 전체 규칙 문법 참조는 권한 규칙 문법을 참조하세요.

샌드박스 설정

고급 샌드박싱 동작을 구성합니다. 샌드박싱은 bash 명령을 파일 시스템 및 네트워크로부터 격리합니다. 자세한 내용은 샌드박싱을 참조하세요.

키	설명	예시
enabled	bash 샌드박싱을 활성화합니다 (macOS, Linux 및 WSL2). 기본값: false	true
autoAllowBashIfSandboxed	샌드박스 내에서 bash 명령을 자동 승인합니다. 기본값: true	true
excludedCommands	샌드박스 외부에서 실행해야 하는 명령	["git", "docker"]
allowUnsandboxedCommands	dangerouslyDisableSandbox 매개변수를 통해 명령이 샌드박스 외부에서 실행되도록 허용합니다. false로 설정하면 dangerouslyDisableSandbox 이스케이프 해치가 완전히 비활성화되고 모든 명령이 샌드박스 내에서 실행되어야 합니다 (excludedCommands에 있는 경우 제외). 엄격한 샌드박싱이 필요한 기업 정책에 유용합니다. 기본값: true	false
filesystem.allowWrite	샌드박스 명령이 쓸 수 있는 추가 경로. 배열은 모든 설정 범위에서 병합됩니다: 사용자, 프로젝트 및 관리 경로가 대체되지 않고 결합됩니다. Edit(...) allow 권한 규칙의 경로와도 병합됩니다. 아래 경로 접두사 참조.	["//tmp/build", "~/.kube"]
filesystem.denyWrite	샌드박스 명령이 쓸 수 없는 경로. 배열은 모든 설정 범위에서 병합됩니다. Edit(...) deny 권한 규칙의 경로와도 병합됩니다.	["//etc", "//usr/local/bin"]
filesystem.denyRead	샌드박스 명령이 읽을 수 없는 경로. 배열은 모든 설정 범위에서 병합됩니다. Read(...) deny 권한 규칙의 경로와도 병합됩니다.	["~/.aws/credentials"]
network.allowUnixSockets	샌드박스에서 접근 가능한 Unix 소켓 경로 (SSH 에이전트 등)	["~/.ssh/agent-socket"]
network.allowAllUnixSockets	샌드박스에서 모든 Unix 소켓 연결을 허용합니다. 기본값: false	true
network.allowLocalBinding	localhost 포트 바인딩을 허용합니다 (macOS 전용). 기본값: false	true
network.allowedDomains	아웃바운드 네트워크 트래픽에 허용할 도메인 배열. 와일드카드를 지원합니다 (예: *.example.com).	["github.com", "*.npmjs.org"]
network.allowManagedDomainsOnly	(관리 설정 전용) 관리 설정의 allowedDomains 및 WebFetch(domain:...) allow 규칙만 적용됩니다. 사용자, 프로젝트 및 로컬 설정의 도메인은 무시됩니다. 허용되지 않은 도메인은 사용자에게 프롬프트 없이 자동으로 차단됩니다. 거부된 도메인은 여전히 모든 소스에서 적용됩니다. 기본값: false	true
network.httpProxyPort	자체 프록시를 사용하려는 경우의 HTTP 프록시 포트. 지정하지 않으면 Claude가 자체 프록시를 실행합니다.	8080
network.socksProxyPort	자체 프록시를 사용하려는 경우의 SOCKS5 프록시 포트. 지정하지 않으면 Claude가 자체 프록시를 실행합니다.	8081
enableWeakerNestedSandbox	권한 없는 Docker 환경을 위한 약화된 샌드박스를 활성화합니다 (Linux 및 WSL2 전용). 보안이 약화됩니다. 기본값: false	true
enableWeakerNetworkIsolation	(macOS 전용) 샌드박스에서 시스템 TLS 신뢰 서비스(com.apple.trustd.agent)에 대한 접근을 허용합니다. httpProxyPort에서 MITM 프록시와 커스텀 CA를 사용할 때 gh, gcloud, terraform 같은 Go 기반 도구가 TLS 인증서를 검증하는 데 필요합니다. 잠재적 데이터 유출 경로를 열어 보안이 약화됩니다. 기본값: false	true

샌드박스 경로 접두사

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

접두사	의미	예시
//	파일 시스템 루트부터의 절대 경로	//tmp/build는 /tmp/build가 됨
~/	홈 디렉토리 기준 상대 경로	~/.kube는 $HOME/.kube가 됨
/	설정 파일의 디렉토리 기준 상대 경로	/build는 $SETTINGS_DIR/build가 됨
./ 또는 접두사 없음	상대 경로 (샌드박스 런타임에서 해석)	./output

구성 예시:

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

파일 시스템 및 네트워크 제한은 함께 병합되는 두 가지 방법으로 구성할 수 있습니다:

• sandbox.filesystem 설정 (위에 표시): OS 수준 샌드박스 경계에서 경로를 제어합니다. 이 제한은 Claude의 파일 도구뿐만 아니라 모든 서브프로세스 명령(예: kubectl, terraform, npm)에 적용됩니다.
• 권한 규칙: Edit allow/deny 규칙을 사용하여 Claude의 파일 도구 접근을 제어하고, Read deny 규칙으로 읽기를 차단하며, WebFetch allow/deny 규칙으로 네트워크 도메인을 제어합니다. 이 규칙의 경로도 샌드박스 구성에 병합됩니다.

어트리뷰션 설정

Claude Code는 git 커밋 및 풀 리퀘스트에 어트리뷰션을 추가합니다. 이들은 별도로 구성됩니다:

• 커밋은 기본적으로 git trailers (예: Co-Authored-By)를 사용하며, 커스터마이즈하거나 비활성화할 수 있습니다
• 풀 리퀘스트 설명은 일반 텍스트입니다

키	설명
commit	git 커밋에 대한 어트리뷰션(트레일러 포함). 빈 문자열은 커밋 어트리뷰션을 숨깁니다
pr	풀 리퀘스트 설명에 대한 어트리뷰션. 빈 문자열은 풀 리퀘스트 어트리뷰션을 숨깁니다

기본 커밋 어트리뷰션:

🤖 Generated with [Claude Code](https://claude.com/claude-code)

   Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

기본 풀 리퀘스트 어트리뷰션:

🤖 Generated with [Claude Code](https://claude.com/claude-code)

예시:

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <[email protected]>",
    "pr": ""
  }
}

참고: attribution 설정은 사용 중단된 includeCoAuthoredBy 설정보다 우선합니다. 모든 어트리뷰션을 숨기려면 commit과 pr을 빈 문자열로 설정하세요.

파일 제안 설정

@ 파일 경로 자동완성을 위한 커스텀 명령을 구성합니다. 내장 파일 제안은 빠른 파일 시스템 탐색을 사용하지만, 대규모 모노레포에서는 사전 빌드된 파일 인덱스나 커스텀 도구와 같은 프로젝트별 인덱싱이 도움이 될 수 있습니다.

{
  "fileSuggestion": {
    "type": "command",
    "command": "~/.claude/file-suggestion.sh"
  }
}

명령은 훅과 동일한 환경 변수(CLAUDE_PROJECT_DIR 포함)로 실행됩니다. query 필드가 포함된 JSON을 stdin으로 수신합니다:

{"query": "src/comp"}

stdout으로 개행으로 구분된 파일 경로를 출력합니다 (현재 15개로 제한):

src/components/Button.tsx
src/components/Modal.tsx
src/components/Form.tsx

예시:

#!/bin/bash
query=$(cat | jq -r '.query')
your-repo-file-index --query "$query" | head -20

훅 구성

이 설정은 어떤 훅이 실행될 수 있는지와 HTTP 훅이 접근할 수 있는 것을 제어합니다. allowManagedHooksOnly 설정은 관리 설정에서만 구성할 수 있습니다. URL 및 환경 변수 허용 목록은 모든 설정 수준에서 설정할 수 있으며 소스 간에 병합됩니다.

allowManagedHooksOnly가 true일 때의 동작:

• 관리 훅과 SDK 훅이 로드됩니다
• 사용자 훅, 프로젝트 훅 및 플러그인 훅이 차단됩니다

HTTP 훅 URL 제한:

HTTP 훅이 대상으로 할 수 있는 URL을 제한합니다. 매칭에 와일드카드로 *를 지원합니다. 배열이 정의된 경우 일치하지 않는 URL을 대상으로 하는 HTTP 훅은 자동으로 차단됩니다.

{
  "allowedHttpHookUrls": ["https://hooks.example.com/*", "http://localhost:*"]
}

HTTP 훅 환경 변수 제한:

HTTP 훅이 헤더 값에 삽입할 수 있는 환경 변수 이름을 제한합니다. 각 훅의 유효 allowedEnvVars는 자체 목록과 이 설정의 교집합입니다.

{
  "httpHookAllowedEnvVars": ["MY_TOKEN", "HOOK_SECRET"]
}

설정 우선순위

설정은 우선순위에 따라 적용됩니다. 높은 순서에서 낮은 순서로:

1. 관리 설정 (서버 관리, MDM/OS 수준 정책, 또는 관리 설정)

   • 서버 전달, MDM 구성 프로파일, 레지스트리 정책 또는 관리 설정 파일을 통해 IT에서 배포한 정책
   • 명령줄 인수를 포함한 다른 수준에서 재정의할 수 없음
   • 관리 계층 내에서의 우선순위: 서버 관리 > MDM/OS 수준 정책 > managed-settings.json > HKCU 레지스트리 (Windows 전용). 하나의 관리 소스만 사용되며 소스가 병합되지 않습니다.

2. 명령줄 인수

   • 특정 세션에 대한 임시 재정의

3. 로컬 프로젝트 설정 (.claude/settings.local.json)

   • 개인 프로젝트별 설정

4. 공유 프로젝트 설정 (.claude/settings.json)

   • 소스 컨트롤에 있는 팀 공유 프로젝트 설정

5. 사용자 설정 (~/.claude/settings.json)

   • 개인 전역 설정

이 계층 구조는 조직 정책이 항상 적용되면서도 팀과 개인이 경험을 커스터마이즈할 수 있도록 보장합니다.

예를 들어, 사용자 설정이 Bash(npm run *)을 허용하지만 프로젝트의 공유 설정이 이를 거부하면, 프로젝트 설정이 우선하여 해당 명령이 차단됩니다.

참고: 배열 설정은 범위 간에 병합됩니다. 동일한 배열 값 설정(예: sandbox.filesystem.allowWrite 또는 permissions.allow)이 여러 범위에 나타나면, 배열은 대체되지 않고 연결 및 중복 제거됩니다. 이는 낮은 우선순위 범위가 높은 우선순위 범위에서 설정한 항목을 재정의하지 않고 항목을 추가할 수 있음을 의미하며, 그 반대도 마찬가지입니다. 예를 들어, 관리 설정이 allowWrite를 ["//opt/company-tools"]로 설정하고 사용자가 ["~/.kube"]를 추가하면, 최종 구성에 두 경로가 모두 포함됩니다.

활성 설정 확인

Claude Code 내에서 /status를 실행하면 어떤 설정 소스가 활성화되어 있는지와 출처를 확인할 수 있습니다. 출력에는 각 구성 레이어(managed, user, project)와 Enterprise managed settings (remote), Enterprise managed settings (plist), Enterprise managed settings (HKLM) 또는 Enterprise managed settings (file) 같은 출처가 표시됩니다. 설정 파일에 오류가 있으면 /status가 문제를 보고하여 수정할 수 있습니다.

구성 시스템의 핵심 사항

• 메모리 파일 (CLAUDE.md): Claude가 시작 시 로드하는 지침과 컨텍스트를 포함합니다
• 설정 파일 (JSON): 권한, 환경 변수 및 도구 동작을 구성합니다
• 스킬: /skill-name으로 호출하거나 Claude가 자동으로 로드할 수 있는 커스텀 프롬프트입니다
• MCP 서버: 추가 도구와 통합을 통해 Claude Code를 확장합니다
• 우선순위: 상위 수준 구성(Managed)이 하위 수준(User/Project)을 재정의합니다
• 상속: 설정은 병합되며, 더 구체적인 설정이 더 넓은 설정에 추가하거나 재정의합니다

시스템 프롬프트

Claude Code의 내부 시스템 프롬프트는 공개되지 않습니다. 커스텀 지침을 추가하려면 CLAUDE.md 파일이나 --append-system-prompt 플래그를 사용하세요.

민감한 파일 제외

API 키, 시크릿, 환경 파일 같은 민감한 정보가 포함된 파일에 Claude Code가 접근하는 것을 방지하려면 .claude/settings.json 파일의 permissions.deny 설정을 사용하세요:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)",
      "Read(./build)"
    ]
  }
}

이는 사용 중단된 ignorePatterns 구성을 대체합니다. 이 패턴과 일치하는 파일은 파일 검색 및 검색 결과에서 제외되며, 이 파일에 대한 읽기 작업이 거부됩니다.

서브에이전트 구성

Claude Code는 사용자 및 프로젝트 수준 모두에서 구성할 수 있는 커스텀 AI 서브에이전트를 지원합니다. 이 서브에이전트는 YAML 프런트매터가 포함된 Markdown 파일로 저장됩니다:

• 사용자 서브에이전트: ~/.claude/agents/ - 모든 프로젝트에서 사용 가능
• 프로젝트 서브에이전트: .claude/agents/ - 프로젝트에 한정되며 팀과 공유 가능

서브에이전트 파일은 커스텀 프롬프트 및 도구 권한을 가진 전문화된 AI 어시스턴트를 정의합니다. 서브에이전트 생성 및 사용에 대한 자세한 내용은 서브에이전트 문서를 참조하세요.

플러그인 구성

Claude Code는 스킬, 에이전트, 훅 및 MCP 서버로 기능을 확장할 수 있는 플러그인 시스템을 지원합니다. 플러그인은 마켓플레이스를 통해 배포되며 사용자 및 저장소 수준 모두에서 구성할 수 있습니다.

플러그인 설정

settings.json의 플러그인 관련 설정:

{
  "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

범위:

• 사용자 설정 (~/.claude/settings.json): 개인 플러그인 선호 설정
• 프로젝트 설정 (.claude/settings.json): 팀과 공유되는 프로젝트별 플러그인
• 로컬 설정 (.claude/settings.local.json): 머신별 재정의 (커밋되지 않음)

예시:

{
  "enabledPlugins": {
    "code-formatter@team-tools": true,
    "deployment-tools@team-tools": true,
    "experimental-features@personal": false
  }
}

extraKnownMarketplaces

저장소에서 사용할 수 있도록 추가 마켓플레이스를 정의합니다. 일반적으로 저장소 수준 설정에서 팀원이 필요한 플러그인 소스에 접근할 수 있도록 사용됩니다.

저장소에 extraKnownMarketplaces가 포함된 경우:

1. 팀원이 폴더를 신뢰할 때 마켓플레이스 설치 프롬프트가 표시됩니다
2. 팀원에게 해당 마켓플레이스의 플러그인 설치 프롬프트가 표시됩니다
3. 사용자는 원하지 않는 마켓플레이스나 플러그인을 건너뛸 수 있습니다 (사용자 설정에 저장됨)
4. 설치는 신뢰 경계를 준수하며 명시적 동의가 필요합니다

예시:

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    },
    "security-plugins": {
      "source": {
        "source": "git",
        "url": "https://git.example.com/security/plugins.git"
      }
    }
  }
}

마켓플레이스 소스 유형:

• github: GitHub 저장소 (repo 사용)
• git: 모든 git URL (url 사용)
• directory: 로컬 파일 시스템 경로 (path 사용, 개발용)
• hostPattern: 마켓플레이스 호스트를 매칭하는 정규식 패턴 (hostPattern 사용)

strictKnownMarketplaces

관리 설정 전용: 사용자가 추가할 수 있는 플러그인 마켓플레이스를 제어합니다. 이 설정은 관리 설정에서만 구성할 수 있으며 관리자에게 마켓플레이스 소스에 대한 엄격한 제어를 제공합니다.

관리 설정 파일 위치:

• macOS: /Library/Application Support/ClaudeCode/managed-settings.json
• Linux 및 WSL: /etc/claude-code/managed-settings.json
• Windows: C:\Program Files\ClaudeCode\managed-settings.json

주요 특성:

• 관리 설정(managed-settings.json)에서만 사용 가능
• 사용자 또는 프로젝트 설정으로 재정의할 수 없음 (최상위 우선순위)
• 네트워크/파일 시스템 작업 전에 적용 (차단된 소스는 실행되지 않음)
• git 소스의 경우 ref, path를 포함한 정확한 매칭을 사용하며, hostPattern은 정규식 매칭을 사용

허용 목록 동작:

• undefined (기본값): 제한 없음 - 사용자가 모든 마켓플레이스를 추가할 수 있음
• 빈 배열 []: 완전 잠금 - 사용자가 새 마켓플레이스를 추가할 수 없음
• 소스 목록: 사용자가 정확히 일치하는 마켓플레이스만 추가할 수 있음

모든 지원되는 소스 유형:

허용 목록은 7가지 마켓플레이스 소스 유형을 지원합니다. 대부분의 소스는 정확한 매칭을 사용하고, hostPattern은 마켓플레이스 호스트에 대한 정규식 매칭을 사용합니다.

1. GitHub 저장소:

{ "source": "github", "repo": "acme-corp/approved-plugins" }
{ "source": "github", "repo": "acme-corp/security-tools", "ref": "v2.0" }
{ "source": "github", "repo": "acme-corp/plugins", "ref": "main", "path": "marketplace" }

필드: repo (필수), ref (선택: 브랜치/태그/SHA), path (선택: 하위 디렉토리)

2. Git 저장소:

{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git" }
{ "source": "git", "url": "https://bitbucket.org/acme-corp/plugins.git", "ref": "production" }
{ "source": "git", "url": "ssh://[email protected]/plugins.git", "ref": "v3.1", "path": "approved" }

필드: url (필수), ref (선택: 브랜치/태그/SHA), path (선택: 하위 디렉토리)

3. URL 기반 마켓플레이스:

{ "source": "url", "url": "https://plugins.example.com/marketplace.json" }
{ "source": "url", "url": "https://cdn.example.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }

필드: url (필수), headers (선택: 인증된 접근을 위한 HTTP 헤더)

참고: URL 기반 마켓플레이스는 marketplace.json 파일만 다운로드합니다. 서버에서 플러그인 파일을 다운로드하지 않습니다. URL 기반 마켓플레이스의 플러그인은 상대 경로 대신 외부 소스(GitHub, npm 또는 git URL)를 사용해야 합니다. 상대 경로를 사용하는 플러그인의 경우 Git 기반 마켓플레이스를 대신 사용하세요. 자세한 내용은 문제 해결을 참조하세요.

4. NPM 패키지:

{ "source": "npm", "package": "@acme-corp/claude-plugins" }
{ "source": "npm", "package": "@acme-corp/approved-marketplace" }

필드: package (필수, 스코프 패키지 지원)

5. 파일 경로:

{ "source": "file", "path": "/usr/local/share/claude/acme-marketplace.json" }
{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }

필드: path (필수: marketplace.json 파일의 절대 경로)

6. 디렉토리 경로:

{ "source": "directory", "path": "/usr/local/share/claude/acme-plugins" }
{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }

필드: path (필수: .claude-plugin/marketplace.json을 포함하는 디렉토리의 절대 경로)

7. 호스트 패턴 매칭:

{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }
{ "source": "hostPattern", "hostPattern": "^gitlab\\.internal\\.example\\.com$" }

필드: hostPattern (필수: 마켓플레이스 호스트에 대해 매칭할 정규식 패턴)

개별 저장소를 나열하지 않고 특정 호스트의 모든 마켓플레이스를 허용하려면 호스트 패턴 매칭을 사용하세요. 개발자가 자체 마켓플레이스를 만드는 내부 GitHub Enterprise 또는 GitLab 서버가 있는 조직에 유용합니다.

소스 유형별 호스트 추출:

• github: 항상 github.com에 대해 매칭
• git: URL에서 호스트명 추출 (HTTPS 및 SSH 형식 모두 지원)
• url: URL에서 호스트명 추출
• npm, file, directory: 호스트 패턴 매칭 미지원

구성 예시:

예시: 특정 마켓플레이스만 허용:

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    },
    {
      "source": "github",
      "repo": "acme-corp/security-tools",
      "ref": "v2.0"
    },
    {
      "source": "url",
      "url": "https://plugins.example.com/marketplace.json"
    },
    {
      "source": "npm",
      "package": "@acme-corp/compliance-plugins"
    }
  ]
}

예시 - 모든 마켓플레이스 추가 비활성화:

{
  "strictKnownMarketplaces": []
}

예시: 내부 git 서버의 모든 마켓플레이스 허용:

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

정확한 매칭 요구사항:

사용자의 추가가 허용되려면 마켓플레이스 소스가 정확히 일치해야 합니다. git 기반 소스(github 및 git)의 경우 모든 선택적 필드가 포함됩니다:

• repo 또는 url이 정확히 일치해야 함
• ref 필드가 정확히 일치해야 함 (또는 둘 다 미정의)
• path 필드가 정확히 일치해야 함 (또는 둘 다 미정의)

일치하지 않는 소스의 예:

// These are DIFFERENT sources:
{ "source": "github", "repo": "acme-corp/plugins" }
{ "source": "github", "repo": "acme-corp/plugins", "ref": "main" }

// These are also DIFFERENT:
{ "source": "github", "repo": "acme-corp/plugins", "path": "marketplace" }
{ "source": "github", "repo": "acme-corp/plugins" }

extraKnownMarketplaces와의 비교:

항목	strictKnownMarketplaces	extraKnownMarketplaces
목적	조직 정책 적용	팀 편의성
설정 파일	managed-settings.json 전용	모든 설정 파일
동작	허용 목록에 없는 추가 차단	누락된 마켓플레이스 자동 설치
적용 시점	네트워크/파일 시스템 작업 전	사용자 신뢰 프롬프트 후
재정의 가능	불가 (최상위 우선순위)	가능 (더 높은 우선순위 설정에 의해)
소스 형식	직접 소스 객체	중첩 소스가 포함된 이름 있는 마켓플레이스
사용 사례	컴플라이언스, 보안 제한	온보딩, 표준화

형식 차이:

strictKnownMarketplaces는 직접 소스 객체를 사용합니다:

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/plugins" }
  ]
}

extraKnownMarketplaces는 이름 있는 마켓플레이스가 필요합니다:

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "acme-corp/plugins" }
    }
  }
}

중요 참고사항:

• 제한은 네트워크 요청 또는 파일 시스템 작업 전에 확인됩니다
• 차단 시 사용자에게 관리 정책에 의해 소스가 차단되었음을 나타내는 명확한 오류 메시지가 표시됩니다
• 제한은 새 마켓플레이스 추가에만 적용됩니다; 이전에 설치된 마켓플레이스는 계속 접근 가능합니다
• 관리 설정은 최상위 우선순위를 가지며 재정의할 수 없습니다

자세한 내용은 관리 마켓플레이스 제한을 참조하세요.

플러그인 관리

/plugin 명령을 사용하여 플러그인을 대화형으로 관리합니다:

• 마켓플레이스에서 사용 가능한 플러그인 찾아보기
• 플러그인 설치/제거
• 플러그인 활성화/비활성화
• 플러그인 상세 정보 보기 (제공되는 명령, 에이전트, 훅)
• 마켓플레이스 추가/제거

플러그인 시스템에 대한 자세한 내용은 플러그인 문서를 참조하세요.

환경 변수

Claude Code는 동작을 제어하기 위해 다음 환경 변수를 지원합니다:

참고: 모든 환경 변수는 settings.json에서도 구성할 수 있습니다. 이는 각 세션에 자동으로 환경 변수를 설정하거나 팀 또는 조직 전체에 환경 변수 세트를 배포하는 방법으로 유용합니다.

변수	용도
ANTHROPIC_API_KEY	X-Api-Key 헤더로 전송되는 API 키, 일반적으로 Claude SDK용 (대화형 사용의 경우 /login 실행)
ANTHROPIC_AUTH_TOKEN	Authorization 헤더의 커스텀 값 (여기서 설정한 값 앞에 Bearer 가 붙습니다)
ANTHROPIC_CUSTOM_HEADERS	요청에 추가할 커스텀 헤더 (Name: Value 형식, 여러 헤더는 줄바꿈으로 구분)
ANTHROPIC_DEFAULT_HAIKU_MODEL	모델 구성 참조
ANTHROPIC_DEFAULT_OPUS_MODEL	모델 구성 참조
ANTHROPIC_DEFAULT_SONNET_MODEL	모델 구성 참조
ANTHROPIC_FOUNDRY_API_KEY	Microsoft Foundry 인증을 위한 API 키 (Microsoft Foundry 참조)
ANTHROPIC_FOUNDRY_BASE_URL	Foundry 리소스의 전체 기본 URL (예: https://my-resource.services.ai.azure.com/anthropic). ANTHROPIC_FOUNDRY_RESOURCE의 대안 (Microsoft Foundry 참조)
ANTHROPIC_FOUNDRY_RESOURCE	Foundry 리소스 이름 (예: my-resource). ANTHROPIC_FOUNDRY_BASE_URL이 설정되지 않은 경우 필수 (Microsoft Foundry 참조)
ANTHROPIC_MODEL	사용할 모델 설정 이름 (모델 구성 참조)
ANTHROPIC_SMALL_FAST_MODEL	[사용 중단됨] 백그라운드 작업을 위한 Haiku 급 모델 이름
ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION	Bedrock 사용 시 Haiku 급 모델의 AWS 리전을 재정의
AWS_BEARER_TOKEN_BEDROCK	Bedrock 인증을 위한 API 키 (Bedrock API 키 참조)
BASH_DEFAULT_TIMEOUT_MS	장시간 실행되는 bash 명령의 기본 타임아웃
BASH_MAX_OUTPUT_LENGTH	중간 잘림 처리 전 bash 출력의 최대 문자 수
BASH_MAX_TIMEOUT_MS	모델이 장시간 실행되는 bash 명령에 설정할 수 있는 최대 타임아웃
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE	자동 압축이 트리거되는 컨텍스트 용량 비율(1-100)을 설정합니다. 기본적으로 자동 압축은 약 95% 용량에서 트리거됩니다. 50 같은 낮은 값을 사용하면 더 일찍 압축됩니다. 기본 임계값 이상의 값은 효과가 없습니다. 메인 대화와 서브에이전트 모두에 적용됩니다. 이 비율은 상태 표시줄에서 사용할 수 있는 context_window.used_percentage 필드와 일치합니다
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR	각 Bash 명령 후 원래 작업 디렉토리로 복귀
CLAUDE_CODE_ACCOUNT_UUID	인증된 사용자의 계정 UUID. SDK 호출자가 계정 정보를 동기적으로 제공하여 초기 텔레메트리 이벤트에 계정 메타데이터가 누락되는 경합 조건을 방지하는 데 사용됩니다. CLAUDE_CODE_USER_EMAIL 및 CLAUDE_CODE_ORGANIZATION_UUID도 함께 설정해야 합니다
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD	1로 설정하면 --add-dir로 지정된 디렉토리에서 CLAUDE.md 파일을 로드합니다. 기본적으로 추가 디렉토리는 메모리 파일을 로드하지 않습니다	1
CLAUDE_CODE_API_KEY_HELPER_TTL_MS	자격 증명을 갱신해야 하는 간격(밀리초) (apiKeyHelper 사용 시)
CLAUDE_CODE_CLIENT_CERT	mTLS 인증을 위한 클라이언트 인증서 파일 경로
CLAUDE_CODE_CLIENT_KEY	mTLS 인증을 위한 클라이언트 개인 키 파일 경로
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE	암호화된 CLAUDE_CODE_CLIENT_KEY의 패스프레이즈 (선택)
CLAUDE_CODE_DISABLE_1M_CONTEXT	1로 설정하면 1M 컨텍스트 윈도우 지원을 비활성화합니다. 설정 시 모델 선택기에서 1M 모델 변형을 사용할 수 없습니다. 컴플라이언스 요구사항이 있는 기업 환경에 유용합니다
CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING	1로 설정하면 Opus 4.6 및 Sonnet 4.6의 적응형 추론을 비활성화합니다. 비활성화하면 이 모델들은 MAX_THINKING_TOKENS로 제어되는 고정 사고 예산으로 폴백합니다
CLAUDE_CODE_DISABLE_AUTO_MEMORY	1로 설정하면 자동 메모리를 비활성화합니다. 0으로 설정하면 점진적 배포 중에 자동 메모리를 강제 활성화합니다. 비활성화하면 Claude가 자동 메모리 파일을 생성하거나 로드하지 않습니다
CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS	1로 설정하면 Claude의 시스템 프롬프트에서 내장된 커밋 및 PR 워크플로우 지침을 제거합니다. 자체 git 워크플로우 스킬을 사용할 때 유용합니다. 설정 시 includeGitInstructions 설정보다 우선합니다
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS	1로 설정하면 Bash 및 서브에이전트 도구의 run_in_background 매개변수, 자동 백그라운딩, Ctrl+B 단축키를 포함한 모든 백그라운드 작업 기능을 비활성화합니다
CLAUDE_CODE_DISABLE_CRON	1로 설정하면 예약 작업을 비활성화합니다. /loop 스킬과 cron 도구를 사용할 수 없게 되며, 세션 중 실행 중인 작업을 포함하여 이미 예약된 작업의 실행이 중지됩니다
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS	1로 설정하면 Anthropic API 전용 anthropic-beta 헤더를 비활성화합니다. 서드파티 제공자와 함께 LLM 게이트웨이를 사용할 때 "anthropic-beta 헤더에 예상치 못한 값" 같은 문제가 발생하는 경우 사용합니다
CLAUDE_CODE_DISABLE_FAST_MODE	1로 설정하면 빠른 모드를 비활성화합니다
CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY	1로 설정하면 "How is Claude doing?" 세션 품질 설문을 비활성화합니다. 서드파티 제공자 사용 시 또는 텔레메트리가 비활성화된 경우에도 비활성화됩니다. 세션 품질 설문 참조
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC	DISABLE_AUTOUPDATER, DISABLE_BUG_COMMAND, DISABLE_ERROR_REPORTING, DISABLE_TELEMETRY를 동시에 설정하는 것과 동일
CLAUDE_CODE_DISABLE_TERMINAL_TITLE	1로 설정하면 대화 컨텍스트에 따른 자동 터미널 제목 업데이트를 비활성화합니다
CLAUDE_CODE_EFFORT_LEVEL	지원되는 모델의 노력 수준을 설정합니다. 값: low, medium, high. 낮은 노력은 더 빠르고 저렴하며, 높은 노력은 더 깊은 추론을 제공합니다. Opus 4.6 및 Sonnet 4.6에서 지원됩니다. 노력 수준 조정 참조
CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION	false로 설정하면 프롬프트 제안(/config의 "Prompt suggestions" 토글)을 비활성화합니다. 이는 Claude가 응답한 후 프롬프트 입력에 나타나는 회색 예측 텍스트입니다. 프롬프트 제안 참조
CLAUDE_CODE_ENABLE_TASKS	false로 설정하면 작업 추적 시스템 대신 이전 TODO 목록으로 임시 복귀합니다. 기본값: true. 작업 목록 참조
CLAUDE_CODE_ENABLE_TELEMETRY	1로 설정하면 메트릭 및 로깅을 위한 OpenTelemetry 데이터 수집을 활성화합니다. OTel 내보내기를 구성하기 전에 필수입니다. 모니터링 참조
CLAUDE_CODE_EXIT_AFTER_STOP_DELAY	쿼리 루프가 유휴 상태가 된 후 자동 종료까지 대기하는 시간(밀리초). SDK 모드를 사용하는 자동화 워크플로우 및 스크립트에 유용합니다
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS	1로 설정하면 에이전트 팀을 활성화합니다. 에이전트 팀은 실험적이며 기본적으로 비활성화되어 있습니다
CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS	파일 읽기의 기본 토큰 제한을 재정의합니다. 더 큰 파일을 전체로 읽어야 할 때 유용합니다
CLAUDE_CODE_HIDE_ACCOUNT_INFO	1로 설정하면 Claude Code UI에서 이메일 주소와 조직 이름을 숨깁니다. 스트리밍 또는 녹화 시 유용합니다
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL	IDE 확장 자동 설치를 건너뜁니다
CLAUDE_CODE_MAX_OUTPUT_TOKENS	대부분의 요청에 대한 최대 출력 토큰 수를 설정합니다. 기본값: 32,000. 최대값: 64,000. 이 값을 늘리면 자동 압축이 트리거되기 전에 사용 가능한 유효 컨텍스트 윈도우가 줄어듭니다.
CLAUDE_CODE_ORGANIZATION_UUID	인증된 사용자의 조직 UUID. SDK 호출자가 계정 정보를 동기적으로 제공하는 데 사용됩니다. CLAUDE_CODE_ACCOUNT_UUID 및 CLAUDE_CODE_USER_EMAIL도 함께 설정해야 합니다
CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS	동적 OpenTelemetry 헤더를 갱신하는 간격(밀리초) (기본값: 1740000 / 29분). 동적 헤더 참조
CLAUDE_CODE_PLAN_MODE_REQUIRED	에이전트 팀 팀원이 계획 승인을 필요로 할 때 자동으로 true로 설정됩니다. 읽기 전용: Claude Code가 팀원을 생성할 때 설정합니다. 팀원의 계획 승인 요구 참조
CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS	플러그인 설치 또는 업데이트 시 git 작업의 타임아웃(밀리초) (기본값: 120000). 대규모 저장소 또는 느린 네트워크 연결의 경우 이 값을 늘리세요. Git 작업 타임아웃 참조
CLAUDE_CODE_PROXY_RESOLVES_HOSTS	true로 설정하면 호출자 대신 프록시가 DNS 확인을 수행하도록 허용합니다. 프록시가 호스트명 확인을 처리해야 하는 환경에서 옵트인
CLAUDE_CODE_SHELL	자동 셸 감지를 재정의합니다. 로그인 셸이 선호하는 작업 셸과 다를 때 유용합니다 (예: bash vs zsh)
CLAUDE_CODE_SHELL_PREFIX	모든 bash 명령을 래핑하는 명령 접두사 (예: 로깅 또는 감사용). 예: /path/to/logger.sh는 /path/to/logger.sh <command>를 실행합니다
CLAUDE_CODE_SIMPLE	1로 설정하면 최소 시스템 프롬프트와 Bash, 파일 읽기, 파일 편집 도구만으로 실행됩니다. MCP 도구, 첨부 파일, 훅, CLAUDE.md 파일을 비활성화합니다
CLAUDE_CODE_SKIP_BEDROCK_AUTH	Bedrock의 AWS 인증을 건너뜁니다 (예: LLM 게이트웨이 사용 시)
CLAUDE_CODE_SKIP_FOUNDRY_AUTH	Microsoft Foundry의 Azure 인증을 건너뜁니다 (예: LLM 게이트웨이 사용 시)
CLAUDE_CODE_SKIP_VERTEX_AUTH	Vertex의 Google 인증을 건너뜁니다 (예: LLM 게이트웨이 사용 시)
CLAUDE_CODE_SUBAGENT_MODEL	모델 구성 참조
CLAUDE_CODE_TASK_LIST_ID	세션 간에 작업 목록을 공유합니다. 여러 Claude Code 인스턴스에서 동일한 ID를 설정하면 공유 작업 목록에서 조율할 수 있습니다. 작업 목록 참조
CLAUDE_CODE_TEAM_NAME	이 팀원이 속한 에이전트 팀의 이름. 에이전트 팀 멤버에 자동으로 설정됩니다
CLAUDE_CODE_TMPDIR	내부 임시 파일에 사용되는 임시 디렉토리를 재정의합니다. Claude Code는 이 경로에 /claude/를 추가합니다. 기본값: Unix/macOS에서 /tmp, Windows에서 os.tmpdir()
CLAUDE_CODE_USER_EMAIL	인증된 사용자의 이메일 주소. SDK 호출자가 계정 정보를 동기적으로 제공하는 데 사용됩니다. CLAUDE_CODE_ACCOUNT_UUID 및 CLAUDE_CODE_ORGANIZATION_UUID도 함께 설정해야 합니다
CLAUDE_CODE_USE_BEDROCK	Bedrock 사용
CLAUDE_CODE_USE_FOUNDRY	Microsoft Foundry 사용
CLAUDE_CODE_USE_VERTEX	Vertex 사용
CLAUDE_CONFIG_DIR	Claude Code가 구성 및 데이터 파일을 저장하는 위치를 커스터마이즈
DISABLE_AUTOUPDATER	1로 설정하면 자동 업데이트를 비활성화합니다.
DISABLE_BUG_COMMAND	1로 설정하면 /bug 명령을 비활성화합니다
DISABLE_COST_WARNINGS	1로 설정하면 비용 경고 메시지를 비활성화합니다
DISABLE_ERROR_REPORTING	1로 설정하면 Sentry 오류 보고를 옵트아웃합니다
DISABLE_INSTALLATION_CHECKS	1로 설정하면 설치 경고를 비활성화합니다. 설치 위치를 수동으로 관리하는 경우에만 사용하세요. 표준 설치의 문제를 마스킹할 수 있습니다
DISABLE_NON_ESSENTIAL_MODEL_CALLS	1로 설정하면 장식 텍스트 같은 비필수 경로의 모델 호출을 비활성화합니다
DISABLE_PROMPT_CACHING	1로 설정하면 모든 모델의 프롬프트 캐싱을 비활성화합니다 (모델별 설정보다 우선)
DISABLE_PROMPT_CACHING_HAIKU	1로 설정하면 Haiku 모델의 프롬프트 캐싱을 비활성화합니다
DISABLE_PROMPT_CACHING_OPUS	1로 설정하면 Opus 모델의 프롬프트 캐싱을 비활성화합니다
DISABLE_PROMPT_CACHING_SONNET	1로 설정하면 Sonnet 모델의 프롬프트 캐싱을 비활성화합니다
DISABLE_TELEMETRY	1로 설정하면 Statsig 텔레메트리를 옵트아웃합니다 (Statsig 이벤트에는 코드, 파일 경로, bash 명령 같은 사용자 데이터가 포함되지 않습니다)
ENABLE_CLAUDEAI_MCP_SERVERS	false로 설정하면 Claude Code에서 claude.ai MCP 서버를 비활성화합니다. 로그인한 사용자에게는 기본적으로 활성화되어 있습니다
ENABLE_TOOL_SEARCH	MCP 도구 검색을 제어합니다. 값: auto (기본값, 컨텍스트 10%에서 활성화), auto:N (커스텀 임계값, 예: auto:5는 5%), true (항상 켜짐), false (비활성화)
FORCE_AUTOUPDATE_PLUGINS	true로 설정하면 DISABLE_AUTOUPDATER를 통해 메인 자동 업데이터가 비활성화된 경우에도 플러그인 자동 업데이트를 강제합니다
HTTP_PROXY	네트워크 연결을 위한 HTTP 프록시 서버를 지정합니다
HTTPS_PROXY	네트워크 연결을 위한 HTTPS 프록시 서버를 지정합니다
IS_DEMO	true로 설정하면 데모 모드를 활성화합니다: UI에서 이메일과 조직을 숨기고, 온보딩을 건너뛰며, 내부 명령을 숨깁니다. 스트리밍 또는 세션 녹화에 유용합니다
MAX_MCP_OUTPUT_TOKENS	MCP 도구 응답에 허용되는 최대 토큰 수. 출력이 10,000 토큰을 초과하면 Claude Code가 경고를 표시합니다 (기본값: 25000)
MAX_THINKING_TOKENS	확장 사고 토큰 예산을 재정의합니다. 기본적으로 사고는 최대 예산(31,999 토큰)으로 활성화됩니다. 예산을 제한하거나 (예: MAX_THINKING_TOKENS=10000) 사고를 완전히 비활성화하는 데 사용합니다 (MAX_THINKING_TOKENS=0). Opus 4.6의 경우 사고 깊이는 대신 노력 수준으로 제어되며, 0으로 설정하여 사고를 비활성화하는 경우를 제외하고 이 변수는 무시됩니다.
MCP_CLIENT_SECRET	사전 구성된 자격 증명이 필요한 MCP 서버의 OAuth 클라이언트 시크릿. --client-secret으로 서버를 추가할 때 대화형 프롬프트를 방지합니다
MCP_OAUTH_CALLBACK_PORT	사전 구성된 자격 증명으로 MCP 서버를 추가할 때 --callback-port의 대안인 OAuth 리다이렉트 콜백의 고정 포트
MCP_TIMEOUT	MCP 서버 시작 타임아웃(밀리초)
MCP_TOOL_TIMEOUT	MCP 도구 실행 타임아웃(밀리초)
NO_PROXY	프록시를 우회하여 직접 요청을 보낼 도메인 및 IP 목록
SLASH_COMMAND_TOOL_CHAR_BUDGET	Skill 도구에 표시되는 스킬 메타데이터의 문자 예산을 재정의합니다. 예산은 컨텍스트 윈도우의 2%로 동적 조정되며, 폴백은 16,000자입니다. 하위 호환성을 위해 레거시 이름이 유지됩니다
USE_BUILTIN_RIPGREP	0으로 설정하면 Claude Code에 포함된 rg 대신 시스템에 설치된 rg를 사용합니다
VERTEX_REGION_CLAUDE_3_5_HAIKU	Vertex AI 사용 시 Claude 3.5 Haiku의 리전을 재정의합니다
VERTEX_REGION_CLAUDE_3_7_SONNET	Vertex AI 사용 시 Claude 3.7 Sonnet의 리전을 재정의합니다
VERTEX_REGION_CLAUDE_4_0_OPUS	Vertex AI 사용 시 Claude 4.0 Opus의 리전을 재정의합니다
VERTEX_REGION_CLAUDE_4_0_SONNET	Vertex AI 사용 시 Claude 4.0 Sonnet의 리전을 재정의합니다
VERTEX_REGION_CLAUDE_4_1_OPUS	Vertex AI 사용 시 Claude 4.1 Opus의 리전을 재정의합니다

Claude에서 사용 가능한 도구

Claude Code는 코드베이스를 이해하고 수정하는 데 도움이 되는 강력한 도구 세트에 접근할 수 있습니다:

도구	설명	권한 필요
AskUserQuestion	요구사항을 수집하거나 모호성을 해소하기 위해 객관식 질문을 합니다	아니오
Bash	사용자 환경에서 셸 명령을 실행합니다 (아래의 Bash 도구 동작 참조)	예
TaskOutput	백그라운드 작업(bash 셸 또는 서브에이전트)의 출력을 검색합니다	아니오
Edit	특정 파일에 대해 타겟 편집을 수행합니다	예
ExitPlanMode	사용자에게 계획 모드를 종료하고 코딩을 시작하도록 프롬프트합니다	예
Glob	패턴 매칭을 기반으로 파일을 찾습니다	아니오
Grep	파일 내용에서 패턴을 검색합니다	아니오
KillShell	ID로 실행 중인 백그라운드 bash 셸을 종료합니다	아니오
MCPSearch	도구 검색이 활성화된 경우 MCP 도구를 검색하고 로드합니다	아니오
NotebookEdit	Jupyter 노트북 셀을 수정합니다	예
Read	파일의 내용을 읽습니다	아니오
Skill	메인 대화 내에서 스킬을 실행합니다	예
Agent	복잡한 다단계 작업을 처리하기 위해 서브에이전트를 실행합니다	아니오
TaskCreate	작업 목록에 새 작업을 생성합니다	아니오
TaskGet	특정 작업의 전체 세부 정보를 검색합니다	아니오
TaskList	모든 작업과 현재 상태를 나열합니다	아니오
TaskUpdate	작업 상태, 종속성, 세부 정보를 업데이트하거나 작업을 삭제합니다	아니오
WebFetch	지정된 URL에서 콘텐츠를 가져옵니다	예
WebSearch	도메인 필터링을 사용하여 웹 검색을 수행합니다	예
Write	파일을 생성하거나 덮어씁니다	예
LSP	언어 서버를 통한 코드 인텔리전스. 파일 편집 후 타입 오류 및 경고를 자동으로 보고합니다. 정의로 이동, 참조 찾기, 타입 정보 가져오기, 심볼 나열, 구현체 찾기, 호출 계층 추적 등의 네비게이션 작업도 지원합니다. 코드 인텔리전스 플러그인과 해당 언어 서버 바이너리가 필요합니다	아니오

권한 규칙은 /allowed-tools 또는 권한 설정에서 구성할 수 있습니다. 도구별 권한 규칙도 참조하세요.

Bash 도구 동작

Bash 도구는 다음과 같은 지속성 동작으로 셸 명령을 실행합니다:

• 작업 디렉토리는 유지됩니다: Claude가 작업 디렉토리를 변경하면 (예: cd /path/to/dir), 이후 Bash 명령은 해당 디렉토리에서 실행됩니다. CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1을 사용하면 각 명령 후 프로젝트 디렉토리로 리셋됩니다.
• 환경 변수는 유지되지 않습니다: 하나의 Bash 명령에서 설정한 환경 변수 (예: export MY_VAR=value)는 이후 Bash 명령에서 사용할 수 없습니다. 각 Bash 명령은 새로운 셸 환경에서 실행됩니다.

Bash 명령에서 환경 변수를 사용하려면 세 가지 옵션이 있습니다:

옵션 1: Claude Code 시작 전에 환경 활성화 (가장 간단한 방법)

Claude Code를 실행하기 전에 터미널에서 가상 환경을 활성화합니다:

conda activate myenv
# or: source /path/to/venv/bin/activate
claude

이 방법은 셸 환경에는 작동하지만, Claude의 Bash 명령 내에서 설정한 환경 변수는 명령 간에 유지되지 않습니다.

옵션 2: Claude Code 시작 전에 CLAUDE_ENV_FILE 설정 (지속적인 환경 설정)

환경 설정을 포함하는 셸 스크립트의 경로를 내보냅니다:

export CLAUDE_ENV_FILE=/path/to/env-setup.sh
claude

/path/to/env-setup.sh의 내용:

conda activate myenv
# or: source /path/to/venv/bin/activate
# or: export MY_VAR=value

Claude Code는 각 Bash 명령 전에 이 파일을 소스하여 모든 명령에서 환경이 유지되도록 합니다.

옵션 3: SessionStart 훅 사용 (프로젝트별 구성)

.claude/settings.json에서 구성합니다:

{
  "hooks": {
    "SessionStart": [{
      "matcher": "startup",
      "hooks": [{
        "type": "command",
        "command": "echo 'conda activate myenv' >> \"$CLAUDE_ENV_FILE\""
      }]
    }]
  }
}

훅은 $CLAUDE_ENV_FILE에 쓰고, 이 파일은 각 Bash 명령 전에 소스됩니다. 이는 팀 공유 프로젝트 구성에 이상적입니다.

옵션 3에 대한 자세한 내용은 SessionStart 훅을 참조하세요.

훅으로 도구 확장

Claude Code 훅을 사용하여 도구 실행 전후에 커스텀 명령을 실행할 수 있습니다.

예를 들어, Claude가 Python 파일을 수정한 후 자동으로 Python 포맷터를 실행하거나, 특정 경로에 대한 Write 작업을 차단하여 프로덕션 구성 파일의 수정을 방지할 수 있습니다.

관련 항목

• 권한: 권한 시스템, 규칙 문법, 도구별 패턴 및 관리 정책
• 인증: Claude Code에 대한 사용자 접근 설정
• 문제 해결: 일반적인 구성 문제에 대한 해결 방법