settings.json으로 권한과 실행 환경 제어하기

settings.json의 역할 #

settings.json은 Claude Code의 동작을 JSON으로 제어하는 설정 파일입니다.

주로 다음을 조절합니다.

어떤 도구와 명령을 자동 허용/확인/거부할지
어떤 파일/디렉터리와 네트워크 접근을 허용할지
기본 모델, 응답 스타일, 언어, thinking/effort 수준
환경 변수, 인증 helper, telemetry, timeout 등 실행 환경
UI 표시 방식, status line, file suggestion, worktree 동작
MCP, plugin, skill, managed policy 관련 제어

파일 위치와 우선순위 #

범위	위치	용도	커밋 여부	우선순위
Managed	서버 관리 설정, MDM/Registry, `/etc/claude-code/managed-settings.json` 등	조직/관리자가 강제하는 정책	일반적으로 커밋 안 함	가장 높음
CLI 인자	`claude --settings ...`, `--model`, `--permission-mode` 등	현재 세션에만 임시 적용	안 함	Managed 다음
Local	`<repo>/.claude/settings.local.json`	프로젝트별 개인 설정, 실험, 로컬 경로	안 함. gitignore 권장/자동 ignore	Project/User보다 높음
Project	`<repo>/.claude/settings.json`	팀 전체가 공유할 프로젝트 정책	커밋	User보다 높음
User	`~/.claude/settings.json`	모든 프로젝트에 적용할 개인 전역 설정	안 함	가장 낮음

병합 규칙 #

스칼라 값: 더 높은 우선순위의 값이 낮은 값을 덮어씁니다.
- 예: User에서 spinnerTipsEnabled: true, Project에서 false면 Project의 false가 적용됩니다.
배열 값: 대부분 연결 후 중복 제거됩니다.
- 예: permissions.allow, sandbox.filesystem.allowWrite는 여러 scope의 배열이 합쳐집니다.
권한 규칙은 단순 override가 아니라 여러 scope에서 병합된 뒤 평가됩니다.
Managed 설정은 원칙적으로 사용자가 덮어쓸 수 없습니다.

settings.json 예시 #

{
  "$schema": "<https://json.schemastore.org/claude-code-settings.json>",
  "model": "claude-sonnet-4-6",
  "effortLevel": "high",
  "language": "korean",
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": [
      "Bash(git diff *)",
      "Bash(npm run test:*)",
      "Read(./docs/**)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(curl *)"
    ],
    "additionalDirectories": [
      "../docs"
    ]
  },
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "300000",
    "BASH_MAX_OUTPUT_LENGTH": "20000"
  },
  "attribution": {
    "commit": "Generated with Claude Code",
    "pr": ""
  },
  "cleanupPeriodDays": 30
}

{
  "$schema": "<https://json.schemastore.org/claude-code-settings.json>",
  "model": "claude-sonnet-4-6",
  "effortLevel": "high",
  "language": "korean",
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": [
      "Bash(git diff *)",
      "Bash(npm run test:*)",
      "Read(./docs/**)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(curl *)"
    ],
    "additionalDirectories": [
      "../docs"
    ]
  },
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "300000",
    "BASH_MAX_OUTPUT_LENGTH": "20000"
  },
  "attribution": {
    "commit": "Generated with Claude Code",
    "pr": ""
  },
  "cleanupPeriodDays": 30
}

`$schema`를 넣는 이유 #

$schema를 넣으면 VS Code, Cursor 같은 JSON Schema 지원 에디터에서 자동완성/검증을 받을 수 있습니다.

"$schema": "<https://json.schemastore.org/claude-code-settings.json>"

"$schema": "<https://json.schemastore.org/claude-code-settings.json>"

단, 공식 문서에 새로 추가된 키가 SchemaStore에 반영되기 전이면 에디터가 경고를 띄울 수 있습니다.

공식 문서에 있는 키라면 CLI 버전과 함께 확인하세요.

최상위 키 #

키	값 형태	무엇을 조절하나	예시	비고
`$schema`	string	JSON schema 연결	`"<https://json.schemastore.org/claude-code-settings.json>"`	자동완성/검증용
`permissions`	object	도구 사용 허용/확인/거부, 기본 permission mode	`{"allow":["Bash(git diff *)"]}`	가장 중요
`sandbox`	object	Bash/PowerShell 실행의 파일시스템·네트워크 격리	`{"enabled":true}`	macOS/Linux/WSL2 중심
`env`	object	Claude Code와 하위 프로세스에 주입할 환경 변수	`{"BASH_DEFAULT_TIMEOUT_MS":"300000"}`	값은 문자열 권장
`model`	string	기본 모델 지정	`"claude-sonnet-4-6"`	`--model`, `/model`, `ANTHROPIC_MODEL`이 우선할 수 있음
`availableModels`	array	사용자가 선택 가능한 모델 제한	`["sonnet", "haiku"]`	관리/팀 정책에 유용
`modelOverrides`	object	모델 ID를 Bedrock/Vertex/Foundry 등 provider별 ID로 매핑	`{"claude-sonnet-4-6":"arn:aws:..."}`	엔터프라이즈/프록시 환경
`effortLevel`	string	reasoning effort 기본값	`"low"`, `"medium"`, `"high"`, `"xhigh"`	`/effort`, env var와 상호작용
`alwaysThinkingEnabled`	boolean	extended thinking을 기본 활성화	`true`	`CLAUDE_CODE_DISABLE_THINKING`으로 강제 비활성 가능
`showThinkingSummaries`	boolean	interactive session에서 thinking summary 표시 여부	`true`	표시만 조절. 비용 절감은 별도 설정 필요
`outputStyle`	string	응답 스타일/system prompt 스타일	`"Explanatory"`	`/output-style` 계열과 관련
`language`	string	기본 응답 언어	`"korean"`, `"japanese"`	voice dictation 언어에도 영향
`attribution`	object	commit/PR attribution 문구	`{"commit":"", "pr":""}`	`includeCoAuthoredBy`보다 우선
`includeCoAuthoredBy`	boolean	commit/PR에 Co-authored-by 포함 여부	`false`	Deprecated. `attribution` 권장
`cleanupPeriodDays`	number	세션 파일/오래된 worktree 정리 주기	`30`	최소 1. `0`은 거부
`autoUpdatesChannel`	string	자동 업데이트 채널	`"latest"`, `"stable"`	업데이트 비활성은 env 사용
`minimumVersion`	string	Claude Code 최소 버전 고정	`"2.1.100"`	조직 표준화에 유용
`autoMemoryEnabled`	boolean	auto memory 사용 여부	`false`	기본 true
`autoMemoryDirectory`	string	auto memory 저장 위치	`"~/my-memory-dir"`	project/local에서는 허용되지 않음
`claudeMdExcludes`	array	로드하지 않을 `CLAUDE.md` 경로 패턴	`["/vendor//CLAUDE.md"]`	absolute path 기준 매칭
`includeGitInstructions`	boolean	내장 git commit/PR 지침과 git status snapshot 포함 여부	`false`	자체 git skill/command가 있으면 false 고려
`plansDirectory`	string	plan 파일 저장 위치	`"./plans"`	프로젝트 root 기준
`fileSuggestion`	object	`@` 파일 자동완성용 커스텀 명령	`{"type":"command","command":"~/.claude/file-suggestion.sh"}`	대형 monorepo에 유용
`respectGitignore`	boolean	`@` 파일 picker가 `.gitignore`를 존중할지	`false`	기본 true
`statusLine`	object	터미널 하단 status line 커스터마이징	`{"type":"command","command":"~/.claude/statusline.sh"}`	현재 branch/토큰/비용 표시 등에 활용
`hooks`	object	도구 호출/프롬프트/세션 이벤트에 command 실행	`{"PreToolUse":[...]}`	여기서는 간략히만 설명
`worktree`	object	`--worktree`와 background session 격리 방식	`{"baseRef":"head"}`	대형 repo/병렬 작업에 중요
`skillOverrides`	object	skill별 노출 수준 제어	`{"deploy":"off"}`	`on`, `name-only`, `user-invocable-only`, `off`
`skillListingBudgetFraction`	number	skill 목록에 배정할 context 비율	`0.02`	기본 0.01
`maxSkillDescriptionChars`	number	skill 설명 최대 길이	`2048`	길게 쓰는 skill이 많을 때 조절
`enableAllProjectMcpServers`	boolean	프로젝트 `.mcp.json`의 모든 MCP 서버 자동 승인	`true`	팀 공유 MCP에 사용
`enabledMcpjsonServers`	array	특정 MCP 서버만 승인	`["github", "memory"]`	화이트리스트 성격
`disabledMcpjsonServers`	array	특정 MCP 서버 거부	`["filesystem"]`	로컬/프로젝트 보안
`allowedMcpServers` / `deniedMcpServers`	array	관리 설정에서 MCP allow/deny list	`[{"serverName":"github"}]`	Managed 중심
`enabledPlugins`	array	활성화할 plugin	plugin 설정 참고	plugin 문서와 함께 확인
`extraKnownMarketplaces`, `strictKnownMarketplaces`, `blockedMarketplaces`	array	plugin marketplace 허용/차단/고정	`[{"source":"github","repo":"acme/plugins"}]`	Managed에서 중요
`disableAllHooks`	boolean	모든 hook과 custom status line 비활성	`true`	긴급 차단용
`allowedHttpHookUrls`	array	HTTP hook이 호출 가능한 URL 패턴	`["<https://hooks.example.com/*>"]`	hooks는 간략 설명만
`httpHookAllowedEnvVars`	array	HTTP hook header에 보간 가능한 env var 제한	`["HOOK_SECRET"]`	secret 유출 방지
`apiKeyHelper`	string	API key/auth token을 생성하는 helper script	`"/bin/generate_temp_api_key.sh"`	동적 credential
`awsAuthRefresh`, `awsCredentialExport`, `gcpAuthRefresh`	string	클라우드 credential 갱신/내보내기 script	`"aws sso login --profile dev"`	Bedrock/Vertex 등
`forceLoginMethod`, `forceLoginOrgUUID`	string/array	로그인 방식/조직 제한	`"claudeai"`, org UUID	Managed에서 주로 사용
`disableAutoMode`, `disableBypassPermissionsMode`, `disableRemoteControl`, `disableDeepLinkRegistration`	string/boolean	위험하거나 조직에서 제한할 기능 비활성	`"disable"`, `true`	보안 정책

permissions #

permissions는 Claude Code에서 가장 자주 쓰는 핵심 설정입니다.

{
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": ["Bash(git diff *)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)", "Read(./secrets/**)"],
    "additionalDirectories": ["../docs"],
    "disableBypassPermissionsMode": "disable"
  }
}

{
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": ["Bash(git diff *)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)", "Read(./secrets/**)"],
    "additionalDirectories": ["../docs"],
    "disableBypassPermissionsMode": "disable"
  }
}

키	값	설명	예시
`allow`	array of rules	일치하는 도구 호출을 자동 허용	`["Bash(npm run test *)"]`
`ask`	array of rules	일치하는 도구 호출 전 확인 요청	`["Bash(git push *)"]`
`deny`	array of rules	일치하는 도구 호출 차단	`["Read(./.env)", "Bash(curl *)"]`
`additionalDirectories`	array of paths	현재 repo 외에 접근 가능한 작업 디렉터리 추가	`["../shared-docs"]`
`defaultMode`	string	Claude Code 시작 시 기본 권한 모드	`"default"`, `"acceptEdits"`, `"plan"`, `"auto"`, `"dontAsk"`, `"bypassPermissions"`
`disableBypassPermissionsMode`	`"disable"`	`bypassPermissions` 모드 진입 자체를 막음	`"disable"`
`skipDangerousModePermissionPrompt`	boolean	`bypassPermissions` 진입 전 경고 prompt 생략	`true`

권한 평가 순서 #

권한 규칙은 다음 순서로 평가됩니다.

deny
ask
allow

먼저 매칭되는 규칙이 적용됩니다. 따라서 민감한 파일이나 위험 명령은 deny에 명시하는 것이 가장 안전합니다.

권한 규칙 문법 #

규칙은 다음 두 형태 중 하나입니다.

Tool
Tool(specifier)

Tool
Tool(specifier)

규칙	의미	추천도
`Bash`	모든 Bash 명령에 매칭	낮음. 너무 넓음
`Bash(npm run test *)`	`npm run test` 로 시작하는 명령 허용	높음
`Bash(git diff *)`	git diff 계열 명령 허용	높음
`Bash(git push *)`	git push 계열 명령 확인/차단	높음
`Read(./.env)`	프로젝트의 `.env` 읽기 매칭	높음. 보통 deny
`Read(./secrets/**)`	secrets 디렉터리 전체 읽기 매칭	높음. 보통 deny
`Edit(./src/**)`	src 아래 파일 편집 매칭	상황에 따라 유용
`WebFetch(domain:github.com)`	github.com fetch 매칭	도메인 제한에 유용
`mcp__github__search_repositories`	특정 MCP tool 매칭	MCP는 풀네임 권장

Permission 패턴 예시 #

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(npm run lint *)",
      "Bash(npm run test *)",
      "Read(./docs/**)"
    ],
    "ask": [
      "Bash(git commit *)",
      "Bash(git push *)",
      "Bash(npm install *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Bash(wget *)"
    ]
  }
}

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(npm run lint *)",
      "Bash(npm run test *)",
      "Read(./docs/**)"
    ],
    "ask": [
      "Bash(git commit *)",
      "Bash(git push *)",
      "Bash(npm install *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Bash(wget *)"
    ]
  }
}

sandbox 상세 #

sandbox는 Bash/PowerShell 명령을 OS-level sandbox 안에서 실행하도록 제어합니다.

권한 규칙이 Claude Code의 tool 사용을 제어한다면, sandbox는 실제 하위 프로세스의 파일/네트워크 접근을 제한합니다.

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker *"],
    "filesystem": {
      "allowWrite": ["./tmp", "/tmp/build"],
      "denyRead": ["~/.aws/credentials", "./.env"],
      "denyWrite": ["/etc", "/usr/local/bin"],
      "allowRead": ["."]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"],
      "deniedDomains": ["uploads.github.com"],
      "allowLocalBinding": true
    }
  }
}

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker *"],
    "filesystem": {
      "allowWrite": ["./tmp", "/tmp/build"],
      "denyRead": ["~/.aws/credentials", "./.env"],
      "denyWrite": ["/etc", "/usr/local/bin"],
      "allowRead": ["."]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"],
      "deniedDomains": ["uploads.github.com"],
      "allowLocalBinding": true
    }
  }
}

`sandbox` 주요 키 #

키	값	설명	예시
`enabled`	boolean	Bash sandbox 활성화	`true`
`failIfUnavailable`	boolean	sandbox를 시작할 수 없으면 Claude Code 시작 실패 처리	`true`
`autoAllowBashIfSandboxed`	boolean	sandbox 안에서 실행되는 Bash를 자동 허용	`true`
`excludedCommands`	array	sandbox 밖에서 실행해야 하는 명령 패턴	`["docker *"]`
`allowUnsandboxedCommands`	boolean	`dangerouslyDisableSandbox` escape hatch 허용 여부	`false`
`filesystem.allowWrite`	array	sandbox 명령이 쓸 수 있는 추가 경로	`["/tmp/build", "~/.kube"]`
`filesystem.denyWrite`	array	쓰기 금지 경로	`["/etc", "/usr/local/bin"]`
`filesystem.denyRead`	array	읽기 금지 경로	`["~/.aws/credentials"]`
`filesystem.allowRead`	array	`denyRead` 안에서 다시 허용할 경로	`["."]`
`network.allowedDomains`	array	외부 네트워크 허용 도메인	`["github.com", "*.npmjs.org"]`
`network.deniedDomains`	array	외부 네트워크 차단 도메인. allow보다 우선	`["sensitive.example.com"]`
`network.allowLocalBinding`	boolean	localhost 포트 바인딩 허용	`true`
`network.httpProxyPort`	number	직접 운영하는 HTTP proxy port	`8080`
`network.socksProxyPort`	number	직접 운영하는 SOCKS proxy port	`8081`

sandbox path prefix #

prefix	의미	예시
`/`	파일시스템 root 기준 absolute path	`/tmp/build`
`~/`	home directory 기준	`~/.kube`
`./` 또는 prefix 없음	project settings에서는 project root 기준, user settings에서는 `~/.claude` 기준	`./output`

주의: sandbox filesystem path의 /path는 absolute path입니다.

permission rule의 path 문법과 다를 수 있으니 혼동하지 마세요.

메모리, 파일 추천, git 관련 키 #

키	값	설명	예시
`autoMemoryEnabled`	boolean	auto memory 기능 사용 여부	`false`
`autoMemoryDirectory`	string	auto memory 저장 경로	`"~/my-memory-dir"`
`claudeMdExcludes`	array	로드하지 않을 `CLAUDE.md` 패턴	`["/vendor//CLAUDE.md"]`
`includeGitInstructions`	boolean	내장 git commit/PR 지침과 git status snapshot 포함 여부	`false`
`attribution.commit`	string	git commit attribution 문구	`"Generated with Claude Code"`
`attribution.pr`	string	PR description attribution 문구	`""`
`includeCoAuthoredBy`	boolean	deprecated byline 설정	`false`
`fileSuggestion`	object	`@` file autocomplete용 command	`{"type":"command","command":"~/.claude/file-suggestion.sh"}`
`respectGitignore`	boolean	`@` file picker가 `.gitignore`를 반영할지	`true`
`plansDirectory`	string	plan 파일 저장 위치	`"./plans"`
`prUrlTemplate`	string	PR badge URL template	`"<https://reviews.example.com/{owner}/{repo}/pull/{number}>"`

attribution으로 co-author 제거하기 #

{
  "attribution": {
    "commit": "",
    "pr": ""
  }
}

{
  "attribution": {
    "commit": "",
    "pr": ""
  }
}

attribution이 있으면 deprecated된 includeCoAuthoredBy보다 우선합니다.

Worktree 관련 키 #

worktree는 claude --worktree, background session, subagent isolation에서 새 git worktree를 어떻게 만들고 관리할지 정합니다.

키	값	설명	예시
`worktree.baseRef`	string	새 worktree가 어디서 branch될지	`"fresh"`, `"head"`
`worktree.symlinkDirectories`	array	새 worktree에 복사하지 않고 symlink할 디렉터리	`["node_modules", ".cache"]`
`worktree.sparsePaths`	array	sparse-checkout할 경로	`["packages/my-app", "shared/utils"]`
`worktree.bgIsolation`	string	background session의 격리 방식	`"worktree"`, `"none"`

Claude Worktree 설정 예시 모음

아래는 실제 상황별로 추천하는 worktree 설정 예시들입니다.

일반적인 대형 Monorepo

대부분의 Next.js, Turborepo, Yarn/PNPM Workspace 프로젝트에 적합

{
  "worktree": {
    "baseRef": "head",
    "symlinkDirectories": ["node_modules", ".cache", "dist", ".next"],
    "sparsePaths": ["packages/**", "apps/**", "shared/**", "turbo.json", "package.json"],
    "bgIsolation": "worktree"
  }
}

{
  "worktree": {
    "baseRef": "head",
    "symlinkDirectories": ["node_modules", ".cache", "dist", ".next"],
    "sparsePaths": ["packages/**", "apps/**", "shared/**", "turbo.json", "package.json"],
    "bgIsolation": "worktree"
  }
}

이유:

head로 현재 상태에서 빠르게 브랜치
무거운 디렉토리는 symlink로 복사 비용 절감
sparse-checkout으로 필요한 부분만 체크아웃

완전 깨끗한 새 작업 환경 (실험/새 기능 개발 시)

{
  "worktree": {
    "baseRef": "fresh",
    "symlinkDirectories": ["node_modules", ".cache"],
    "sparsePaths": [],
    "bgIsolation": "worktree"
  }
}

{
  "worktree": {
    "baseRef": "fresh",
    "symlinkDirectories": ["node_modules", ".cache"],
    "sparsePaths": [],
    "bgIsolation": "worktree"
  }
}

이유:

fresh → main 브랜치 최신 상태에서 완전히 새로 시작
sparsePaths를 비우면 전체 저장소를 체크아웃 (필요 시)

Background Session / Subagent 전용 (격리 강조)

{
  "worktree": {
    "baseRef": "head",
    "symlinkDirectories": ["node_modules", ".cache", "dist"],
    "sparsePaths": ["."],                    // 전체 체크아웃
    "bgIsolation": "worktree"
  }
}

{
  "worktree": {
    "baseRef": "head",
    "symlinkDirectories": ["node_modules", ".cache", "dist"],
    "sparsePaths": ["."],                    // 전체 체크아웃
    "bgIsolation": "worktree"
  }
}

이유:

background session과 subagent가 서로 영향을 주지 않도록 별도 worktree 사용
bgIsolation: "worktree"가 핵심

최소 리소스 / 빠른 시작 우선 (작은 프로젝트)

{
  "worktree": {
    "baseRef": "head",
    "symlinkDirectories": ["node_modules"],
    "sparsePaths": ["src", "public", "package.json", "tsconfig.json"],
    "bgIsolation": "none"
  }
}

{
  "worktree": {
    "baseRef": "head",
    "symlinkDirectories": ["node_modules"],
    "sparsePaths": ["src", "public", "package.json", "tsconfig.json"],
    "bgIsolation": "none"
  }
}

이유:

bgIsolation을 none으로 해서 오버헤드 최소화
정말 필요한 파일만 sparse하게 체크아웃

특정 패키지만 작업할 때 (Monorepo 내 특정 앱/패키지)

{
  "worktree": {
    "baseRef": "head",
    "symlinkDirectories": ["node_modules", ".cache"],
    "sparsePaths": [
      "apps/my-app",
      "packages/shared",
      "packages/ui",
      "package.json",
      "turbo.json"
    ],
    "bgIsolation": "worktree"
  }
}

{
  "worktree": {
    "baseRef": "head",
    "symlinkDirectories": ["node_modules", ".cache"],
    "sparsePaths": [
      "apps/my-app",
      "packages/shared",
      "packages/ui",
      "package.json",
      "turbo.json"
    ],
    "bgIsolation": "worktree"
  }
}

PR 리뷰 / 버그 수정 전용 (안전하게)

{
  "worktree": {
    "baseRef": "fresh",
    "symlinkDirectories": ["node_modules", ".cache", ".next"],
    "sparsePaths": [],
    "bgIsolation": "worktree"
  }
}

{
  "worktree": {
    "baseRef": "fresh",
    "symlinkDirectories": ["node_modules", ".cache", ".next"],
    "sparsePaths": [],
    "bgIsolation": "worktree"
  }
}

추천 기본 설정

{
  "worktree": {
    "baseRef": "head",
    "symlinkDirectories": ["node_modules", ".cache", "dist", ".turbo"],
    "sparsePaths": ["**/*"],           // 전체 체크아웃하고 싶으면 이렇게
    "bgIsolation": "worktree"
  }
}

{
  "worktree": {
    "baseRef": "head",
    "symlinkDirectories": ["node_modules", ".cache", "dist", ".turbo"],
    "sparsePaths": ["**/*"],           // 전체 체크아웃하고 싶으면 이렇게
    "bgIsolation": "worktree"
  }
}

MCP 관련 키 #

키	값	설명	예시
`enableAllProjectMcpServers`	boolean	프로젝트 `.mcp.json` 서버를 모두 자동 승인	`true`
`enabledMcpjsonServers`	array	특정 `.mcp.json` 서버만 승인	`["github", "memory"]`
`disabledMcpjsonServers`	array	특정 `.mcp.json` 서버 거부	`["filesystem"]`
`allowedMcpServers`	array	허용 가능한 MCP 서버 목록	`[{"serverName":"github"}]`
`deniedMcpServers`	array	차단할 MCP 서버 목록	`[{"serverName":"filesystem"}]`
`allowManagedMcpServersOnly`	boolean	managed settings의 allowlist만 존중	`true`
`allowAllClaudeAiMcps`	boolean	managed MCP와 claude.ai connector 병행 로드	`true`

일반 프로젝트에서는 보통 enableAllProjectMcpServers, enabledMcpjsonServers, disabledMcpjsonServers 정도를 씁니다. allowedMcpServers, deniedMcpServers, allowManagedMcpServersOnly는 조직 관리 정책에서 더 자주 사용됩니다.

Skill / Plugin 관련 키 #

Skill 관련 #

키	값	설명	예시
`skillOverrides`	object	skill별 노출 방식 제어	`{"legacy-context":"name-only","deploy":"off"}`
`skillListingBudgetFraction`	number	skill listing에 배정할 context 비율	`0.02`
`maxSkillDescriptionChars`	number	skill 설명 최대 문자 수	`2048`
`disableSkillShellExecution`	boolean	skill/custom command 안의 inline shell 실행 비활성	`true`

skillOverrides 값:

값	의미
`"on"`	정상 노출
`"name-only"`	이름만 노출. 설명은 줄임
`"user-invocable-only"`	사용자가 명시적으로 호출할 때만 사용
`"off"`	숨김/비활성

env 키로 넣을 수 있는 주요 환경 변수 #

환경 변수는 shell에서 직접 export할 수도 있고, settings.json의 env 아래에 넣을 수도 있습니다. 동일한 동작에 settings field와 environment variable이 모두 있으면 일반적으로 environment variable이 우선합니다.

{
  "env": {
    "ANTHROPIC_MODEL": "claude-sonnet-4-6",
    "API_TIMEOUT_MS": "1200000",
    "BASH_DEFAULT_TIMEOUT_MS": "300000",
    "BASH_MAX_OUTPUT_LENGTH": "20000",
    "CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS": "1"
  }
}

{
  "env": {
    "ANTHROPIC_MODEL": "claude-sonnet-4-6",
    "API_TIMEOUT_MS": "1200000",
    "BASH_DEFAULT_TIMEOUT_MS": "300000",
    "BASH_MAX_OUTPUT_LENGTH": "20000",
    "CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS": "1"
  }
}

환경 변수	설명	예시
`ANTHROPIC_API_KEY`	Anthropic API key 인증	`"sk-ant-..."`
`ANTHROPIC_AUTH_TOKEN`	custom Authorization Bearer token	`"token"`
`ANTHROPIC_BASE_URL`	API endpoint/proxy/gateway 변경	`"<https://gateway.example.com>"`
`ANTHROPIC_MODEL`	사용 모델 override	`"claude-sonnet-4-6"`
`ANTHROPIC_DEFAULT_OPUS_MODEL` / `ANTHROPIC_DEFAULT_SONNET_MODEL` / `ANTHROPIC_DEFAULT_HAIKU_MODEL`	모델 alias의 기본 ID 변경	provider/gateway 환경
`API_TIMEOUT_MS`	API 요청 timeout	`"1200000"`
`BASH_DEFAULT_TIMEOUT_MS`	Bash 기본 timeout	`"300000"`
`BASH_MAX_TIMEOUT_MS`	Bash 최대 timeout	`"600000"`
`BASH_MAX_OUTPUT_LENGTH`	Bash 출력이 너무 길 때 truncate 기준	`"20000"`
`CLAUDE_CODE_DISABLE_AUTO_MEMORY`	auto memory 비활성화	`"1"`
`CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS`	내장 git 지침 제거	`"1"`
`CLAUDE_CODE_DISABLE_THINKING`	extended thinking 강제 비활성화	`"1"`
`CLAUDE_CODE_EFFORT_LEVEL`	effort level override	`"low"`, `"medium"`, `"high"`, `"xhigh"`
`CLAUDE_CODE_ENABLE_TELEMETRY`	OpenTelemetry 활성화	`"1"`
`CLAUDE_CODE_NO_FLICKER`	fullscreen rendering 사용	`"1"`
`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`	자동 업데이트/telemetry/feedback 등 비필수 트래픽 비활성	`"1"`
`DISABLE_AUTOUPDATER`	자동 업데이트 비활성	`"1"`
`NO_COLOR`, `FORCE_COLOR`	하위 프로세스 색상 제어	`"1"`

주의: env에 민감한 API key를 프로젝트 공유 설정 파일(.claude/settings.json)에 넣지 마세요. 개인 전역 설정, 로컬 설정, OS secret manager, apiKeyHelper 등을 사용하는 편이 안전합니다.

공식 문서 링크 #

Claude Code Settings: https://code.claude.com/docs/en/settings
Configure Permissions: https://code.claude.com/docs/en/permissions
Hooks Reference: https://code.claude.com/docs/en/hooks
Environment Variables: https://code.claude.com/docs/en/env-vars
JSON Schema: https://json.schemastore.org/claude-code-settings.json

AI 코딩 에이전트 Wiki

LangChain/LangGraph

OpenSearch

settings.json으로 권한과 실행 환경 제어하기

settings.json의 역할 #

파일 위치와 우선순위 #

병합 규칙 #

settings.json 예시 #

`$schema`를 넣는 이유 #

최상위 키 #

permissions #

권한 평가 순서 #

권한 규칙 문법 #

Permission 패턴 예시 #

sandbox 상세 #

`sandbox` 주요 키 #

sandbox path prefix #

메모리, 파일 추천, git 관련 키 #

attribution으로 co-author 제거하기 #

Worktree 관련 키 #

MCP 관련 키 #

Skill / Plugin 관련 키 #

Skill 관련 #

env 키로 넣을 수 있는 주요 환경 변수 #

공식 문서 링크 #

글이 도움이 되셨나요?

답글 남기기 응답 취소

settings.json의 역할 #

파일 위치와 우선순위 #

병합 규칙 #

settings.json 예시 #

$schema를 넣는 이유 #

최상위 키 #

permissions #

권한 평가 순서 #

권한 규칙 문법 #

Permission 패턴 예시 #

sandbox 상세 #

sandbox 주요 키 #

sandbox path prefix #

메모리, 파일 추천, git 관련 키 #

attribution으로 co-author 제거하기 #

Worktree 관련 키 #

MCP 관련 키 #

Skill / Plugin 관련 키 #

Skill 관련 #

env 키로 넣을 수 있는 주요 환경 변수 #

공식 문서 링크 #

글이 도움이 되셨나요?

공유하기

답글 남기기 응답 취소

`$schema`를 넣는 이유 #

`sandbox` 주요 키 #