읽는 시간: 14분 | 난이도: 중급자
기준일: 2026-07-26
공식 기준: Configure permissions, Permission modes, Configure auto mode

Claude Code는 세밀한 권한 시스템을 지원하여 에이전트가 할 수 있는 것과 없는 것을 정확하게 지정할 수 있습니다. 권한 설정은 버전 관리에 체크인하여 조직의 모든 개발자에게 배포하거나, 개별 개발자가 커스터마이징할 수 있습니다.

권한 규칙은 Claude Code가 강제합니다. CLAUDE.md 지시만으로는 허용 범위가 바뀌지 않습니다. 변경은 /permissions, 규칙, permission mode, 또는 PreToolUse 훅으로 합니다.

권한 시스템 개요

Claude Code는 강력함과 안전성을 균형 있게 유지하기 위해 계층적 권한 시스템을 사용합니다.

도구 유형	예시	승인 필요 여부	"다시 묻지 않기" 동작
읽기 전용	파일 읽기, Grep	불필요	해당 없음
Bash 명령	셸 실행	필요	프로젝트 디렉토리 및 명령별 영구 저장
파일 수정	파일 편집/쓰기	필요	세션 종료 시까지

권한 관리 UI

/permissions 명령으로 Claude Code의 도구 권한을 보고 관리할 수 있습니다. 이 UI는 모든 권한 규칙과 해당 규칙이 어느 settings.json 파일에서 왔는지 목록으로 보여줍니다.

• Allow 규칙: 수동 승인 없이 지정된 도구를 사용할 수 있습니다.
• Ask 규칙: Claude Code가 해당 도구를 사용하려 할 때마다 확인을 요청합니다.
• Deny 규칙: Claude Code가 해당 도구를 사용하는 것을 방지합니다.

규칙 평가 순서는 deny -> ask -> allow 입니다. 첫 번째로 매칭되는 규칙이 적용되므로, deny 규칙은 항상 우선합니다.

권한 모드

Claude Code는 도구 승인 방식을 제어하는 여러 권한 모드를 지원합니다. 상세 동작·UI 라벨·보호 경로는 공식 Permission modes를 따릅니다. 설정 파일에서 permissions.defaultMode로 두고, CLI에서는 claude --permission-mode <mode> 또는 세션 중 Shift+Tab 순환(일부 모드는 조건부로 포함)을 사용합니다.

모드	프롬프트 없이 실행되는 것 (요약)	용도
default (UI: Manual; v2.1.200+ 별칭 manual)	읽기 위주	시작·민감 작업
acceptEdits	읽기, 작업 디렉터리 내 파일 편집, 일부 파일시스템 Bash (mkdir, touch, mv, cp 등)	편집을 사후 git diff로 검토
plan	읽기·탐색; 소스 편집은 plan 승인 전 차단. auto 사용 가능 시 계획 중 classifier 승인 명령 가능	변경 전 조사
auto	대부분 도구 + 백그라운드 classifier 안전 검사	장시간 작업, 프롬프트 피로 감소
dontAsk	allow 규칙·읽기 전용 Bash·PreToolUse 허용분만	잠긴 CI/스크립트
bypassPermissions	거의 전부 (격리 환경 전용)	컨테이너·VM

경고: bypassPermissions는 권한 프롬프트를 건너뜁니다. 명시적 ask 규칙, org connector ask, requiresUserInteraction MCP, 루트/홈 디렉터리 제거 서킷 브레이커(rm -rf /, rm -rf ~ 및 치환 형태 등)는 여전히 프롬프트될 수 있습니다. 격리된 환경에서만 사용하세요. permissions.disableBypassPermissionsMode 또는 permissions.disableAutoMode를 "disable"로 두면 해당 모드를 막을 수 있습니다(관리형 설정에 두면 재정의 불가).

Auto mode 요약

Auto mode는 별도 classifier가 행동을 검토해 irreversible·파괴적·신뢰 경계 밖 동작을 막습니다. 가용 조건·모델·Team/Enterprise Owner enable·보호 경로 라우팅은 Permission modes — auto를 확인하세요. 조직 인프라(리포, 버킷, 내부 도메인) 신뢰 목록은 autoMode.environment로 넣습니다 (Configure auto mode).

{
  "permissions": {
    "defaultMode": "auto",
    "ask": [
      "Bash(git push *)",
      "Bash(gh pr create *)"
    ]
  },
  "autoMode": {
    "environment": [
      "$defaults",
      "Source control: github.example.com/acme-corp and all repos under it"
    ]
  }
}

• defaultMode: "auto"는 user / managed 설정에 둡니다. 프로젝트 .claude/settings.json의 auto는 저장소 자체 부여를 막기 위해 무시될 수 있습니다.
• CLI 점검: claude auto-mode defaults, claude auto-mode config, claude auto-mode critique, claude auto-mode reset
• 연속 거부 시 auto가 일시 중단되고 수동 승인으로 재개됩니다(임계값은 비구성).

Hard deny (permissions.deny)

규칙 평가 순서는 deny → ask → allow입니다. 첫 매칭이 결과이며, 좁은 allow가 넓은 deny를 예외로 뚫지 않습니다.

목적	메커니즘	auto mode에서의 효과
해당 액션 전 항상 프롬프트	permissions.ask	classifier가 자동 승인 불가
절대 실행 금지	permissions.deny	classifier 전에 차단. 사용자 의도·autoMode.allow로도 우회 불가
세션 한시 경계	대화에 "don't push" 등 명시	classifier가 차단할 수 있으나 compaction으로 메시지 소실 가능 → 내구성은 ask/deny

bare 도구 이름 deny(예: Bash)는 도구를 컨텍스트에서 제거합니다. 패턴 deny(예: Bash(rm *))는 도구를 남기고 매칭 호출만 차단합니다. EndConversation 예외 등 세부 사항은 공식 permissions 문서를 따릅니다.

Auto mode 내부 규칙 오버라이드(autoMode.hard_deny / soft_deny / allow)는 classifier 설정입니다. 도구 호출 자체를 강제 차단하려면 항상 permissions.deny를 사용하세요. autoMode 배열에서 "$defaults" 없이 목록을 바꾸면 해당 섹션 기본 규칙 전체를 대체하므로 주의합니다.

권한 규칙 문법

권한 규칙은 도구 또는 도구(지정자) 형식을 따릅니다.

도구의 모든 사용 매칭

괄호 없이 도구 이름만 사용하면 해당 도구의 모든 사용을 매칭합니다.

규칙	효과
Bash	모든 Bash 명령 매칭
WebFetch	모든 웹 가져오기 요청 매칭
Read	모든 파일 읽기 매칭

Bash(*)는 Bash와 동일하며 모든 Bash 명령과 매칭됩니다.

세밀한 제어를 위한 지정자

괄호 안에 지정자를 추가하면 특정 도구 사용만 매칭할 수 있습니다.

규칙	효과
Bash(npm run build)	정확히 npm run build 명령 매칭
Read(./.env)	현재 디렉토리의 .env 파일 읽기 매칭
WebFetch(domain:example.com)	example.com으로의 가져오기 요청 매칭

와일드카드 패턴

Bash 규칙은 *를 사용한 글로브 패턴을 지원합니다. 와일드카드는 명령의 어느 위치에도 사용할 수 있습니다. 다음 설정은 npm과 git commit 명령은 허용하면서 git push를 차단합니다.

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)",
      "Bash(git * main)",
      "Bash(* --version)",
      "Bash(* --help *)"
    ],
    "deny": [
      "Bash(git push *)"
    ]
  }
}

중요: * 앞의 공백이 중요합니다. Bash(ls *)는 ls -la와 매칭되지만 lsof와는 매칭되지 않습니다. 반면 Bash(ls*)는 둘 다 매칭됩니다.

도구별 권한 규칙

Bash 규칙

Bash 권한 규칙은 *를 사용한 와일드카드 매칭을 지원합니다. 와일드카드는 명령의 시작, 중간, 끝 어디에도 사용할 수 있습니다.

• Bash(npm run build): 정확히 npm run build 명령 매칭
• Bash(npm run test *): npm run test로 시작하는 명령 매칭
• Bash(npm *): npm 으로 시작하는 명령 매칭
• Bash(* install): install로 끝나는 명령 매칭
• Bash(git * main): git checkout main, git merge main 같은 명령 매칭

팁: Claude Code는 && 같은 셸 연산자를 인식합니다. Bash(safe-cmd *)와 같은 접두사 매칭 규칙은 safe-cmd && other-cmd 실행 권한을 주지 않습니다.

경고: 명령 인수를 제한하려는 Bash 권한 패턴은 취약할 수 있습니다. 예를 들어 Bash(curl http://github.com/ *)는 GitHub URL로 curl을 제한하려 하지만, 다음 변형은 매칭하지 못합니다:

• URL 앞에 옵션: curl -X GET http://github.com/...
• 다른 프로토콜: curl https://github.com/...
• 리다이렉트: curl -L http://bit.ly/xyz (github로 리다이렉트)
• 변수: URL=http://github.com && curl $URL

더 신뢰할 수 있는 URL 필터링을 위해서는 WebFetch 권한 규칙과 PreToolUse 훅을 함께 사용하는 것을 권장합니다.

Read와 Edit 규칙

Edit 규칙은 파일을 편집하는 모든 빌트인 도구에 적용됩니다. Claude는 Grep, Glob 같은 파일을 읽는 모든 빌트인 도구에 Read 규칙을 최선을 다해 적용합니다.

Read와 Edit 규칙은 모두 gitignore 명세를 따르며 네 가지 패턴 유형이 있습니다.

패턴	의미	예시	매칭 대상
//path	파일시스템 루트에서의 절대 경로	Read(//Users/alice/secrets/**)	/Users/alice/secrets/**
~/path	홈 디렉토리에서의 경로	Read(~/Documents/*.pdf)	/Users/alice/Documents/*.pdf
/path	설정 파일 기준 상대 경로	Edit(/src/**/*.ts)	<설정 파일 경로>/src/**/*.ts
path 또는 ./path	현재 디렉토리 기준 상대 경로	Read(*.env)	<현재 디렉토리>/*.env

주의: /Users/alice/file 같은 패턴은 절대 경로가 아닙니다. 설정 파일 기준 상대 경로입니다. 절대 경로에는 //Users/alice/file을 사용하세요.

예시:

• Edit(/docs/**): <project>/docs/의 편집 (NOT /docs/)
• Read(~/.zshrc): 홈 디렉토리의 .zshrc 읽기
• Edit(//tmp/scratch.txt): 절대 경로 /tmp/scratch.txt 편집
• Read(src/**): <현재 디렉토리>/src/에서 읽기

참고: gitignore 패턴에서 *는 단일 디렉토리의 파일과 매칭되고, **는 디렉토리를 재귀적으로 매칭합니다. 모든 파일 접근을 허용하려면 괄호 없이 도구 이름만 사용하세요: Read, Edit, Write.

WebFetch 규칙

• WebFetch(domain:example.com): example.com으로의 가져오기 요청 매칭

MCP 규칙

• mcp__puppeteer: puppeteer 서버가 제공하는 모든 도구 매칭
• mcp__puppeteer__*: puppeteer 서버의 모든 도구와 매칭하는 와일드카드 문법
• mcp__puppeteer__puppeteer_navigate: puppeteer 서버의 puppeteer_navigate 도구 매칭

Task (서브에이전트) 규칙

Task(에이전트이름) 규칙으로 Claude가 사용할 수 있는 서브에이전트를 제어할 수 있습니다.

• Task(Explore): Explore 서브에이전트 매칭
• Task(Plan): Plan 서브에이전트 매칭
• Task(my-custom-agent): my-custom-agent라는 커스텀 서브에이전트 매칭

설정의 deny 배열이나 --disallowedTools CLI 플래그로 특정 에이전트를 비활성화할 수 있습니다. Explore 에이전트를 비활성화하는 예시입니다.

{
  "permissions": {
    "deny": ["Task(Explore)"]
  }
}

훅을 통한 권한 확장

Claude Code 훅은 런타임에 권한 평가를 수행하기 위한 커스텀 셸 명령을 등록하는 방법을 제공합니다. Claude Code가 도구 호출을 할 때, PreToolUse 훅이 권한 시스템보다 먼저 실행되며 훅 출력이 도구 호출을 승인하거나 거부할 수 있습니다.

작업 디렉토리

기본적으로 Claude는 실행된 디렉토리의 파일에 접근할 수 있습니다. 다음 방법으로 이 접근 범위를 확장할 수 있습니다.

• 시작 시: --add-dir <경로> CLI 인수 사용
• 세션 중: /add-dir 명령 사용
• 영구 설정: 설정 파일의 additionalDirectories에 추가

추가 디렉토리의 파일은 원래 작업 디렉토리와 동일한 권한 규칙을 따릅니다. 프롬프트 없이 읽을 수 있게 되고, 파일 편집 권한은 현재 권한 모드를 따릅니다.

권한과 샌드박싱의 상호작용

권한과 샌드박싱은 상호 보완적인 보안 레이어입니다.

• 권한: Claude Code가 사용할 수 있는 도구와 접근 가능한 파일이나 도메인을 제어합니다. Bash, Read, Edit, WebFetch, MCP 등 모든 도구에 적용됩니다.
• 샌드박싱: Bash 도구의 파일시스템 및 네트워크 접근을 제한하는 OS 수준의 강제 메커니즘입니다. Bash 명령과 그 자식 프로세스에만 적용됩니다.

심층 방어를 위해 두 가지를 함께 사용하세요.

• 권한 deny 규칙으로 Claude가 제한된 리소스에 접근 시도 자체를 차단
• 샌드박스 제한으로 프롬프트 인젝션이 Claude의 의사 결정을 우회하더라도 정의된 경계 외부의 리소스에 접근 방지

관리형 설정

중앙 집중식 제어가 필요한 조직의 경우, 관리자가 시스템 디렉토리에 managed-settings.json 파일을 배포할 수 있습니다. 이 정책 파일은 일반 설정 파일과 동일한 형식을 따르며 사용자 또는 프로젝트 설정으로 재정의할 수 없습니다.

관리형 설정 파일 위치:

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

참고: 이 경로들은 시스템 전체 경로(~/Library/... 같은 사용자 홈 디렉토리가 아닙니다)로 관리자 권한이 필요합니다. IT 관리자가 배포하도록 설계되었습니다.

관리형 전용 설정

일부 설정은 관리형 설정에서만 효과가 있습니다.

설정	설명
disableBypassPermissionsMode	"disable"로 설정하면 bypassPermissions 모드와 --dangerously-skip-permissions 플래그를 방지
allowManagedPermissionRulesOnly	true이면 사용자 및 프로젝트 설정이 allow, ask, deny 권한 규칙을 정의하지 못하도록 방지. 관리형 설정의 규칙만 적용
allowManagedHooksOnly	true이면 사용자, 프로젝트, 플러그인 훅 로드를 방지. 관리형 훅과 SDK 훅만 허용
strictKnownMarketplaces	사용자가 추가할 수 있는 플러그인 마켓플레이스를 제어

설정 우선순위

권한 규칙은 다른 Claude Code 설정과 동일한 설정 우선순위를 따릅니다. 관리형 설정이 가장 높은 우선순위를 가지며, 그 다음은 명령줄 인수, 로컬 프로젝트, 공유 프로젝트, 사용자 설정 순입니다.

사용자 설정에서 허용된 권한이 프로젝트 설정에서 거부된 경우, 프로젝트 설정이 우선하여 권한이 차단됩니다.

설정 예시

개발 환경용 기본 설정

{
  "permissions": {
    "allow": [
      "Bash(npm *)",
      "Bash(yarn *)",
      "Bash(git status *)",
      "Bash(git log *)",
      "Bash(git diff *)",
      "Read(src/**)",
      "Edit(src/**)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(rm -rf *)",
      "Read(~/.ssh/*)",
      "Read(.env*)"
    ]
  }
}

CI/CD 환경용 설정

{
  "permissions": {
    "defaultMode": "bypassPermissions",
    "allow": [
      "Bash(npm run test *)",
      "Bash(npm run build *)",
      "Bash(git *)",
      "Read(**)",
      "Edit(**)"
    ],
    "deny": [
      "Bash(curl *)",
      "Bash(wget *)",
      "WebFetch"
    ]
  }
}

읽기 전용 코드 리뷰 모드

{
  "permissions": {
    "defaultMode": "plan",
    "allow": [
      "Read(**)",
      "Bash(grep *)",
      "Bash(find *)"
    ],
    "deny": [
      "Edit",
      "Write",
      "Bash"
    ]
  }
}

다음 단계

• 권한 모드 (한국어 전용 가이드) — default·plan·acceptEdits·auto·bypass 요약
• Permission modes · Configure auto mode — 모드·classifier 상세
• 설정(Settings) 가이드 — 권한·autoMode 키 포함 설정 레퍼런스
• 훅(Hooks) 가이드 — PreToolUse·PermissionRequest
• 샌드박싱 — Bash OS 격리
• 헤드리스 모드 — -p와 permission mode
• 보안 가이드 — workspace trust 및 안전장치
• 최신 운영 기능 맵 — 자율 권한 표면 위치