Claude Code 설정과 권한 규칙

설정이란

Claude Code의 동작(시작 모델, 묻지 않고 실행할 것, 읽으면 안 되는 파일, 화면 표시, 조직이 강제하는 정책)은 JSON 설정 파일의 키로 정한다. 어느 파일에 적느냐가 곧 누구에게 적용되느냐다. 지시문(CLAUDE.md)은 모델이 잊을 수 있지만, 설정은 하네스가 강제한다. 그래서 「Co-Authored-By를 절대 넣지 마」를 CLAUDE.md에 쓰기보다 attribution.commit: ""로 설정하는 편이 확실하다.

입문용 개요(권한 모드, 팀 공유 계층, 계정 분리)는 Claude Code 활용 가이드에 있다. 이 노트는 설정 파일 자체를 깊게 다룬다.

계층과 우선순위

높은 쪽이 같은 키를 덮어쓴다.

• ~/.claude.json은 Claude Code가 스스로 쓰는 다섯 번째 파일이다. 계정 정보, 사용자 범위 MCP 서버, 프로젝트별 신뢰 결정, /config가 쓰는 전역 키(autoConnectIde, diffTool, externalEditorContext 등)가 들어 있다.
• 환경변수는 계층이 아니다. 키와 변수가 짝을 이루면 짝마다 규칙이 따로 있다. 셸에서 export한 ANTHROPIC_MODEL은 어느 파일의 model보다 이기고, ANTHROPIC_DEFAULT_MODEL은 어느 파일에도 model이 없을 때만 쓰인다.
• /status의 Setting sources 줄로 실제로 읽힌 파일을 확인하고, 거부된 항목은 claude doctor로 본다. 파일은 엄격한 JSON이라 주석·끝 쉼표가 있으면 오류다.

목록은 합쳐진다

permissions.allow 같은 배열은 덮어쓰지 않고 모든 계층을 이어 붙인다. 그래서 각 파일은 항목을 더할 수만 있다. 예외는 모델 관련 넷이다.

프로젝트 파일은 신뢰가 필요하다

커밋된 .claude/settings.json의 permissions.allow, additionalDirectories, extraKnownMarketplaces, 대부분의 env는 각자 그 폴더를 신뢰한 뒤에야 적용된다. deny·ask는 바로 적용된다. 추적되지 않는 settings.local.json의 allow는 신뢰 단계 없이 적용된다. 하위 폴더에서 시작해도 로컬 파일은 저장소 루트에 둔다(v2.1.211부터).

저장소가 스스로 권한을 올리지 못하게

악의적인 저장소가 커밋한 설정으로 권한을 넓히지 못하도록, 일부 키는 프로젝트·로컬 파일에서 무시된다.

반대로 더 엄격한 값은 낮은 계층에서도 이긴다: permissions.blockReadsOutsideWorkingDirectories: true, blockWritesOutsideWorkingDirectories: true, disableClaudeAiConnectors: true, maxEffortLevel(가장 낮은 상한), crossSessionInbound(accept < hold < refuse), 프로젝트의 remoteControlAtStartup: false.

전역과 프로젝트에 두는 것

원칙은 개인 상태와 프로젝트를 넘는 조율은 전역, 팀이 공유할 프로젝트 설정은 프로젝트다.

권한 규칙

{ "permissions": {
  "allow": ["Edit(*)", "Bash(npm run *)", "Bash(git *)", "WebFetch(domain:*)", "mcp__memory__*"],
  "ask":   ["Bash(rm *)", "Bash(git push *)"],
  "deny":  ["Read(.env)", "Read(./secrets/**)", "Bash(curl *)"],
  "additionalDirectories": ["../shared-libs/"] } }

평가 순서는 deny → ask → allow이고 처음 맞는 규칙이 이긴다. 로컬 파일에 「Yes, and don't ask again」으로 쌓인 allow도 프로젝트·관리 파일의 ask를 이기지 못한다.

도구별 문법

• allow의 도구 이름 글롭은 mcp__<서버>__ 뒤에서만 인정된다. "*", "mcp__*"를 allow에 넣으면 경고 후 무시된다.
• 심링크는 allow면 링크와 대상이 둘 다, deny면 둘 중 하나만 맞아도 적용된다.

Read·Edit 경로 접두사

샌드박스 filesystem.* 경로에서는 /가 절대 경로라 의미가 다르다.

Bash 매칭

• Bash(ls *)(공백 있음)는 ls -la는 맞지만 lsof는 아니다. Bash(ls*)는 둘 다 맞는다. Bash(npm:*) 접미 문법도 끝에서만 인식된다.
• 복합 명령은 쪼개서 각각 검사한다. &&, ||, ;, |, &, 줄바꿈으로 나누므로 Bash(safe-cmd *)가 safe-cmd && other-cmd를 허용하지 않는다.
• timeout, time, nice, nohup, stdbuf, 플래그 없는 xargs 같은 래퍼는 벗기고 검사한다. watch, setsid, flock, find -exec·-delete는 항상 묻는다.

권한 모드별 세부

모드의 개념과 자동 모드 분류기는 활용 가이드의 「권한 모드」에 있다. 여기서는 놓치기 쉬운 동작만 적는다.

무인 실행용 키: permissions.denyInsteadOfPrompting(프롬프트가 뜰 호출을 바로 거부해 턴이 멈추지 않게, v2.1.319+), permissions.blockWritesOutsideWorkingDirectories(작업 폴더 밖 쓰기 차단).

주요 설정 키

키는 수백 개다(v2.1.322 기준 249개 이상, 환경변수 400개 이상). 전체 목록은 공식 설정 레퍼런스에서 찾고, 여기서는 자주 손대는 것만 묶는다.

상태줄

{ "statusLine": { "type": "command", "command": "~/.claude/statusline.sh", "padding": 2, "refreshInterval": 5 } }

스크립트는 stdin으로 JSON을 받는다. 자주 쓰는 필드는 model.display_name, workspace.current_dir, context_window.used_percentage, cost.total_cost_usd, rate_limits.five_hour.*, effort.level, pr.number다. 맥락 사용률을 늘 보이게 두면 압축·초기화 시점을 잡기 쉽다. /statusline에 원하는 모양을 말하면 Claude가 스크립트를 만든다.

샌드박스

/sandbox로 켜는 오픈소스 샌드박스 런타임은 bash의 파일·네트워크 접근을 OS 수준에서 가둔다. 안에서 도는 bash는 자동 승인되므로 권한 프롬프트가 크게 줄어든다.

MCP와 플러그인 거버넌스

• .mcp.json 서버는 자동 승인되지 않는다(v2.1.196부터). enableAllProjectMcpServers 또는 enabledMcpjsonServers·disabledMcpjsonServers로 고른다.
• 조직은 allowedMcpServers·deniedMcpServers(이름·명령·URL 글롭), allowManagedMcpServersOnly로 통제한다. disableClaudeAiConnectors는 claude.ai 커넥터 자동 로드를 끈다.
• 플러그인은 enabledPlugins({"formatter@acme-tools": true})와 extraKnownMarketplaces로 팀에 배포한다. 관리 전용 strictKnownMarketplaces는 빈 배열이면 공식 마켓까지 막는다.

관리 설정

조직은 서버 관리 설정(claude.ai 콘솔), MDM(macOS plist com.anthropic.claudecode, Windows HKLM\SOFTWARE\Policies\ClaudeCode), 파일(/Library/Application Support/ClaudeCode/, /etc/claude-code/, C:\Program Files\ClaudeCode\의 managed-settings.json)로 정책을 내린다.

• managed-settings.d/*.json 드롭인 폴더는 systemd처럼 알파벳순으로 위에 합친다. 10-telemetry.json, 20-security.json처럼 숫자로 순서를 정한다.
• 관리 전용 키: allowManagedPermissionRulesOnly(사용자·프로젝트 규칙 무시), requiredMinimumVersion·requiredMaximumVersion(버전 범위 밖이면 시작 거부), forceRemoteSettingsRefresh(원격 정책을 받기 전까지 시작 차단), claudeMd(조직 메모리로 주입할 문구).

환경변수

settings.json의 env로 넣거나 셸에서 export한다. 인증 관련 변수(CLAUDE_CONFIG_DIR, ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN)는 활용 가이드의 「계정과 인증」에 있다.

정리

• 설정은 관리 > CLI > 로컬 > 프로젝트 > 사용자 순으로 덮어쓰고, 배열은 합쳐진다. 팀 규칙은 .claude/settings.json에 커밋하고 개인 예외는 settings.local.json에 둔다.
• 저장소 파일은 권한을 넓히는 키를 쓸 수 없고, 더 엄격한 값은 어느 계층에서든 이긴다.
• 권한은 deny → ask → allow 순서다. Bash 복합 명령은 쪼개서 검사되고, Write·Glob 규칙은 allow에서 무시된다는 점을 기억한다.
• 모델이 지켜야 할 규칙 중 하네스가 강제할 수 있는 것(attribution, 권한, 모델, 샌드박스)은 CLAUDE.md가 아니라 설정으로 옮긴다.

관련 노트: Claude Code 활용 가이드, Claude Code 훅, Claude Code 명령어·플래그 레퍼런스, Claude Code 메모리, 에이전트를 믿을 수 있는 환경 만들기