목차
- settings.json 5단계 우선순위 — 어떤 설정이 이기는가
- permissions 설정 — deny가 allow를 이기는 평가 순서
- sandbox 설정으로 claude code settings.json 파일·네트워크 격리
- hooks 설정과 LSP 기반 토큰 절약 전략
- 플러그인·마켓플레이스 — enabledPlugins 설정 구조
- 나머지 핵심 키 — attribution, worktree, $schema
- claude code settings.json 설정 시 주의할 한계점
- 다음 단계 — CLAUDE.md와 MCP 서버 연동
이 JSON 파일 하나가 Claude Code 에이전트의 행동 범위를 결정한다. curl 실행을 막을 수도 있고, .env 파일 읽기를 차단할 수도 있다. claude code settings.json 전체 옵션 가이드를 찾는 이유는 대부분 비슷하다 — 설정 키가 50개를 넘기는데 어디서부터 손대야 할지 모르기 때문이다.
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": ["Bash(npm run lint)", "Bash(npm run test *)"],
"deny": ["Bash(curl *)", "Read(./.env)", "Read(./secrets/**)"]
},
"env": {
"CLAUDE_CODE_ENABLE_TELEMETRY": "1",
"OTEL_METRICS_EXPORTER": "otlp"
}
}settings.json의 주요 설정 키는 카테고리별로 역할이 다르다. 우선순위 체계, permissions, sandbox, hooks, 플러그인까지 각 키가 실제로 무엇을 제어하는지 코드와 함께 설명한다.
settings.json 5단계 우선순위 — 어떤 설정이 이기는가
Claude Code의 설정 시스템은 단일 파일이 아니다. 총 5단계 레이어로 구성되어 있으며, 상위 레벨이 하위 레벨을 덮어쓴다.
// 우선순위 (높 → 낮)
// 1. Managed (server-managed / MDM / file-based)
// 2. Command line arguments
// 3. Local (.claude/settings.local.json)
// 4. Project (.claude/settings.json)
// 5. User (~/.claude/settings.json)핵심 규칙이 하나 있다. Managed 설정은 어떤 하위 레벨에서도 오버라이드할 수 없다. 조직 관리자가 Managed에서 deny로 지정한 명령어는 개발자가 User나 Project 레벨에서 allow로 풀어도 차단 상태를 유지한다.
배열 값의 처리 방식도 독특하다. permissions.allow, sandbox.filesystem.allowWrite 같은 배열 타입 설정은 스코프 간 병합(concatenate + deduplicate) 된다. 예를 들어 User 레벨에서 Bash(git diff *)를 allow하고, Project 레벨에서 Bash(npm run test *)를 allow하면, 실제 적용되는 allow 배열에는 두 항목이 모두 포함된다.
User 설정(`~/.claude/settings.json`)은 전역 기본값, Project 설정(`.claude/settings.json`)은 팀 공유용, Local 설정(`.claude/settings.local.json`)은 개인 오버라이드용이다. `.gitignore`에 `settings.local.json`을 추가하면 개인 설정이 커밋에 포함되지 않는다.
permissions 설정 — deny가 allow를 이기는 평가 순서
settings.json에서 가장 먼저 만지게 되는 섹션이 permissions다. allow, ask, deny 세 개의 배열로 에이전트의 도구 사용 권한을 제어한다.
{
"permissions": {
"allow": ["Bash(git diff *)"],
"ask": ["Bash(git push *)"],
"deny": ["WebFetch", "Bash(curl *)", "Read(./.env)"]
}
}규칙 형식은 Tool 또는 Tool(specifier)다. Bash(npm run lint)처럼 구체적인 명령어를 지정할 수도 있고, WebFetch처럼 도구 전체를 대상으로 할 수도 있다. 와일드카드(*)는 셸의 glob과 동일한 방식으로 동작한다.
평가 순서가 중요하다. deny → ask → allow 순서로 매칭되며, 첫 번째로 매칭된 규칙이 적용된다. 같은 명령어가 allow와 deny에 동시에 들어 있으면 deny가 이긴다.
| 시나리오 | allow | deny | 결과 |
|---|---|---|---|
| git diff | Bash(git diff *) | — | 자동 허용 |
| curl 요청 | — | Bash(curl *) | 차단 |
| .env 읽기 | Read(*) | Read(./.env) | 차단 (deny 우선) |
| git push | — (ask에 등록) | — | 매번 확인 |
WebFetch(domain:example.com) 같은 도메인 기반 필터링도 된다. 특정 도메인만 허용하고 나머지 외부 요청을 전부 차단하는 패턴이 가능하다는 뜻이다.
`defaultMode`로 `bypassPermissions`나 `dontAsk`를 설정하면 모든 권한 확인을 건너뛴다. 편리하지만 프로덕션 프로젝트에서는 위험하다. `acceptEdits` 정도가 코드 수정 자동 수락만 허용하면서 위험한 명령은 여전히 확인하는 균형점이 된다.
sandbox 설정으로 claude code settings.json 파일·네트워크 격리
permissions가 “어떤 도구를 쓸 수 있는가”를 제어한다면, sandbox는 “허용된 도구가 어디까지 접근할 수 있는가”를 제한한다. 파일시스템과 네트워크 두 축으로 격리 경계를 설정한다.
{
"sandbox": {
"enabled": true,
"autoAllowBashIfSandboxed": true,
"excludedCommands": ["docker *"],
"filesystem": {
"allowWrite": ["/tmp/build", "~/.kube"],
"denyRead": ["~/.aws/credentials"]
},
"network": {
"allowedDomains": ["github.com", "*.npmjs.org"],
"allowLocalBinding": true
}
}
}파일시스템 격리
filesystem 하위에는 allowWrite, denyWrite, denyRead, allowRead 네 개 키가 있다. 경로 프리픽스로 세 가지 표기를 지원한다:
/— 절대 경로~/— 홈 디렉토리 상대./— 프로젝트 루트 상대
~/.aws/credentials를 denyRead에 넣으면 에이전트가 AWS 자격증명을 읽지 못한다. /tmp/build를 allowWrite에 넣으면 빌드 아티팩트 쓰기를 허용하되, 그 외 시스템 디렉토리 쓰기는 차단 상태를 유지한다.
네트워크 격리
network 하위의 allowedDomains와 deniedDomains로 외부 도메인 접근을 제어한다. 와일드카드 서브도메인(*.npmjs.org)도 지원한다. allowLocalBinding을 true로 설정하면 localhost 바인딩이 가능해져서 로컬 개발 서버 실행을 허용한다.
allowUnixSockets 키도 있는데, Docker socket 같은 Unix 소켓 접근을 제어할 때 쓴다.
`autoAllowBashIfSandboxed`를 `true`로 설정하면 sandbox가 켜진 상태에서 Bash 명령 실행마다 confirm을 받지 않아도 된다. sandbox 경계 밖으로는 이미 나갈 수 없으니 매번 물어볼 필요가 없다는 논리다. `excludedCommands`로 `docker *` 같은 특정 명령만 별도로 제외할 수 있다.
hooks 설정과 LSP 기반 토큰 절약 전략
hooks는 Claude Code의 라이프사이클 이벤트에 외부 스크립트를 연결하는 기능이다. settings.json의 hooks 키 아래에 이벤트별 핸들러를 등록한다. PreToolUse, PostToolUse, SessionStart 같은 이벤트가 지원된다.
토큰 최적화 관점에서 hooks가 흥미로운 이유가 있다. Claude Code LSP Enforcement Kit은 PreToolUse 훅 5개와 PostToolUse 훅 1개, SessionStart 훅 1개로 구성된 오픈소스 프로젝트다. Grep 호출 시 코드 심볼(camelCase, PascalCase 패턴)이 포함되면 LSP 사용을 강제하여, 불필요한 전문 검색 대신 정확한 심볼 참조를 사용하게 만든다.
// settings.json hook 등록 예시
{
"matcher": "Grep",
"hooks": [
{"type": "command", "command": "node ~/.claude/hooks/lsp-first-guard.js"}
]
}실측 토큰 절감 효과
이 프로젝트의 실측 데이터에 따르면, TypeScript 프로젝트에서 1주간 약 235,000 토큰을 절감했다. 비율로는 73~80% 수준의 토큰 절약이다. Grep을 통한 넓은 범위 텍스트 검색 대신 LSP의 정밀한 심볼 조회를 사용하면, 응답에 포함되는 컨텍스트 양이 대폭 줄어들기 때문이다.
다만 한 가지 유의할 점이 있다. LSP enforcement 같은 토큰 최적화 hooks는 공식 문서에서 다루지 않는 영역이다. 커뮤니티 레포에서만 사례를 찾을 수 있으며, Anthropic이 hooks API를 변경하면 호환성 문제가 생길 수 있다.
| 항목 | Grep 기반 | LSP 기반 | 차이 |
|---|---|---|---|
| 심볼 검색 토큰 | 높음 | 낮음 | 73~80% 절감 |
| 정확도 | 텍스트 매칭 | 구문 분석 | LSP가 정밀 |
| 설정 복잡도 | 없음 | 훅 5~7개 등록 | LSP가 높음 |
hooks의 활용 범위는 토큰 최적화 외에도 넓다. 커밋 전 자동 린트, 파일 변경 후 테스트 실행, 세션 시작 시 환경변수 주입 같은 자동화를 settings.json 하나로 구성할 수 있다.
플러그인·마켓플레이스 — enabledPlugins 설정 구조
Claude Code는 플러그인 시스템을 갖추고 있다. settings.json의 enabledPlugins 키로 활성화·비활성화를 관리한다.
{
"enabledPlugins": {
"formatter@acme-tools": true,
"deployer@acme-tools": true,
"analyzer@security-plugins": false
},
"extraKnownMarketplaces": {
"acme-tools": {
"source": "github",
"repo": "acme-corp/claude-plugins"
}
}
}플러그인 식별자는 plugin-name@marketplace-name 형식을 따른다. true로 활성화, false로 비활성화한다. 단순하다.
커스텀 마켓플레이스 등록
extraKnownMarketplaces에 GitHub 레포를 소스로 지정하면 사내 전용 마켓플레이스를 구성할 수 있다. 팀원이 프로젝트 폴더를 trust하면 해당 마켓플레이스의 플러그인 설치를 자동으로 안내하는 흐름이 동작한다.
조직 수준에서는 Managed 설정의 strictKnownMarketplaces와 blockedMarketplaces를 활용한다. strictKnownMarketplaces를 true로 설정하면 등록되지 않은 마켓플레이스의 플러그인 설치가 차단된다. blockedMarketplaces에 특정 마켓플레이스 이름을 넣으면 해당 소스의 플러그인을 아예 사용할 수 없게 된다.
Managed 설정에서 `strictKnownMarketplaces: true`와 `blockedMarketplaces`를 조합하면 “허용된 마켓플레이스의 플러그인만 설치 가능” 정책을 만들 수 있다. 이 설정은 MDM(Jamf, Intune 등)으로 배포하게 되는데, 실전 배포 예제는 공식 문서에서 간략하게만 다루고 있다.
settings.json에는 권한·샌드박스·훅·플러그인 외에도 실전에서 자주 건드리는 키가 여럿 있다. 카테고리별로 나눠서 정리한다.
$schema와 자동완성
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"worktree": {
"symlinkDirectories": ["node_modules", ".cache"],
"sparsePaths": ["packages/my-app", "shared/utils"]
}
}$schema 키에 https://json.schemastore.org/claude-code-settings.json을 지정하면 VS Code, Cursor 등에서 자동완성과 인라인 유효성 검사가 활성화된다. 50개가 넘는 설정 키를 외우지 않아도 에디터가 후보를 보여주니, Claude Code 설정 공식 문서를 매번 찾아보는 수고를 줄일 수 있다.
worktree 설정 — 대형 모노레포 최적화
worktree.symlinkDirectories에 node_modules, .cache 같은 디렉토리를 지정하면 워크트리 생성 시 이 디렉토리들을 심볼릭 링크로 처리한다. 디스크 사용량이 줄어든다.
worktree.sparsePaths는 모노레포에서 특정 패키지만 체크아웃하도록 한다. 전체 레포를 다 내려받지 않아도 되니 시작 시간이 단축된다. 수십 개 패키지가 있는 모노레포에서 체감 차이가 크다.
attribution 커스터마이즈
{
"attribution": {
"commit": "Generated with AI\n\nCo-Authored-By: AI <ai@example.com>",
"pr": ""
}
}attribution 설정은 commit과 pr 두 키를 가진다. 기본값에는 ‘🤖 Generated with Claude Code’와 Co-Authored-By 트레일러가 포함되어 있다. 빈 문자열("")로 설정하면 어트리뷰션을 숨길 수 있다.
이전에 사용되던 includeCoAuthoredBy 키는 deprecated 상태다. 지금은 attribution.commit에 Co-Authored-By 라인을 직접 넣는 방식으로 대체됐다.
기타 주요 키 요약
settings.json의 주요 설정 키는 50개 이상이다. 위에서 다루지 않은 키 중 자주 쓰이는 항목을 정리하면 아래와 같다:
model— 기본 모델 오버라이드. Sonnet, Opus 등을 명시적으로 지정alwaysThinkingEnabled— 확장 사고(Extended Thinking)를 상시 활성화autoUpdatesChannel—stable또는latest중 선택cleanupPeriodDays— 세션 보관 기간. 기본값 30일effortLevel—low,medium,high,xhigh네 단계. 응답 품질과 토큰 소비의 트레이드오프fileSuggestion—@파일 자동완성을 커스텀 스크립트로 대체
`low`는 빠르지만 얕은 분석, `xhigh`는 정밀하지만 토큰 소비가 크다. 일반적인 코드 리뷰에는 `medium`, 복잡한 리팩토링이나 아키텍처 분석에는 `high` 이상이 적합하다. 프로젝트 성격에 맞게 Project 레벨 settings.json에 고정해 두면 된다.
settings.json을 본격적으로 활용할수록 부딪히는 한계가 몇 가지 있다.
첫째, 설정 키 간 상호작용 문서가 부족하다. 50개가 넘는 키 중 일부는 서로 영향을 줄 수 있지만, 어떤 조합이 충돌하는지 정리한 공식 가이드가 아직 없다. 일부 키가 동시에 설정되면 어떻게 되는지는 직접 테스트해 봐야 한다.
둘째, Managed 설정의 MDM 배포 실전 예제가 부족하다. Jamf나 Intune을 통한 managed-settings.json 배포는 공식 문서에서 간략하게만 다루고 있다. 엔터프라이즈 환경에서 수백 대 개발 머신에 일괄 배포하려면 추가적인 시행착오가 필요하다.
셋째, 한국어 공식 문서의 업데이트 지연 가능성이 있다. 영어 원문 대비 한국어 버전은 반영이 늦을 수 있으므로, 최신 키를 확인할 때는 영어 문서를 기준으로 하는 편이 안전하다.
settings.json 키 50여 개의 상호작용·충돌 사례를 정리한 공식 가이드는 현재 존재하지 않는다. 새로운 키가 추가될 때마다 $schema 기반 에디터 자동완성에 의존하면서, Claude Code 전체 설정 키 문서에서 변경사항을 추적하는 방법이 현실적이다.
다음 단계 — CLAUDE.md와 MCP 서버 연동
claude code settings.json 전체 옵션 가이드에서 다룬 설정은 에이전트의 행동 범위를 정의하는 인프라다. 이 인프라 위에서 에이전트가 “어떻게” 동작할지를 결정하는 건 CLAUDE.md 프롬프트 파일이다. settings.json의 permissions로 도구 접근을 열어두고, CLAUDE.md에서 코딩 컨벤션과 작업 지침을 지시하는 조합이 실전 구성의 기본 형태가 된다.
hooks 설정이 어느 정도 잡히면, 다음으로 살펴볼 영역은 MCP 서버 연동이다. Claude Code에 외부 API를 직접 연결하는 MCP 서버를 구성하면 settings.json의 permissions와 sandbox가 MCP 도구에도 동일하게 적용된다. 그리고 조직 규모가 커지면 managed settings의 MDM 배포 자동화도 검토 대상이 되는데, 이 부분은 claude code managed settings 엔터프라이즈 설정을 별도로 다뤄야 할 분량이다.
관련 글
- Claude Code LSP 설정 완전 가이드 — TypeScript·Python 언어 서버 5단계 연동 – Claude Code에서 LSP를 설정하면 코드 컨텍스트 파악 정확도가 올라가고 토큰 소비가 줄어든다. TypeScript와 Python …
- Claude Code 모노레포 토큰 최적화 — LSP 컨텍스트 폭발 방지 실전 설정법 – 모노레포에서 Claude Code 세션당 토큰 소비가 급증하는 원인과 해결법을 다룬다. CLAUDE.md 계층 설계, 경로 범위 규칙, L…
- Claude Code 웹 버전 사용법 — 브라우저 AI 코딩 시작하는 7단계 – Claude Code 웹 버전은 로컬 설정 없이 브라우저에서 AI 코딩 에이전트를 실행한다. GitHub 연동, 클라우드 환경 설정, 병렬…