권한 모드

Claude Code는 파일 수정, 명령어 실행 등 실제 시스템에 영향을 주는 작업을 합니다. 이런 작업을 얼마나 자유롭게 허용할지 결정하는 것이 권한 시스템입니다.

권한 계층

Claude Code는 도구 유형에 따라 승인 수준이 다릅니다:

도구 유형	예시	승인 필요	"다시 묻지 않기" 범위
읽기 전용	파일 읽기, Grep, Glob	불필요	-
Bash 명령	셸 실행	필요	프로젝트 디렉토리당 영구 저장
파일 수정	Edit, Write	필요	세션 종료까지

6가지 권한 모드

모드	설명	사용 시점
manual (구 default)	도구 첫 사용 시 승인 요청	일반적인 개발 작업
acceptEdits	파일 수정 자동 승인	신뢰할 수 있는 로컬 개발
plan	분석만 가능, 수정/실행 불가	코드 탐색, 아키텍처 검토
auto	분류기가 자동 승인/차단	장시간 작업, 프롬프트 피로 감소
dontAsk	사전 승인된 도구만 허용, 나머지 자동 거부	제한된 자동화
bypassPermissions	모든 승인 건너뜀	격리된 컨테이너/VM만

v2.1.200 — default 모드 → Manual 개칭

v2.1.200부터 기본(default) 모드의 이름이 CLI·--help·VS Code·JetBrains 전반에서 Manual 모드로 바뀌었습니다. --permission-mode manual·"defaultMode": "manual" 표기가 기존 default와 나란히 인식되므로 기존 설정은 그대로 동작합니다. v2.1.203부터는 Manual 모드일 때 푸터에 회색 ⏸ 배지가 표시되어 현재 모드를 항상 확인할 수 있습니다.

실시간 모드 전환

세션 중에 Shift+Tab 또는 Alt+M으로 모드를 실시간 전환할 수 있습니다:

Manual(기본) 모드 → Shift+Tab → 자동승인 모드 → Shift+Tab → Plan 모드 → Shift+Tab → Auto 모드 → ...

Auto 모드 표시 조건

Shift+Tab 순환에 Auto 모드가 나타나려면 계정이 사용 조건(아래 표)을 충족해야 합니다. 모든 플랜에서 쓸 수 있으며(Pro 포함), Anthropic API 기준 Opus 4.6 이상 또는 Sonnet 4.6 모델이 필요합니다.

승인 옵션 이해하기

Manual(기본) 모드에서 Claude가 승인을 요청할 때:

Claude: auth/login.ts를 생성하겠습니다. 허용하시겠습니까?
[y] Yes  [n] No  [a] Always allow this type  [d] Don't allow

선택	의미
y (Yes)	이번 한 번만 허용
n (No)	거절, Claude가 다른 방법 시도
a (Always)	이 세션에서 같은 종류 작업 자동 허용
d (Don't allow)	이 세션에서 이 종류 작업 항상 거절

bypassPermissions 주의

bypassPermissions 모드는 모든 권한 검사를 비활성화합니다. 격리된 환경(Docker, VM)에서만 사용하세요. 조직 관리자는 managed settings에서 disableBypassPermissionsMode: "disable"로 이 모드를 차단할 수 있습니다.

Auto 모드 — 분류기 기반 자동 승인

Auto 모드는 매번 수동으로 승인하는 대신, 백그라운드 분류기(Anthropic이 서버 측에서 결정하는 모델로, 사용자의 /model 선택과 무관)가 각 도구 호출을 자동으로 평가합니다. bypassPermissions처럼 모든 걸 허용하는 것이 아니라, 작업 맥락에 맞는지 판단한 뒤 안전한 것만 실행합니다.

Claude Code v2.1.83+ 필요

Auto 모드는 v2.1.83 이상에서 동작합니다. claude --version으로 먼저 확인하세요.

사용 조건 (전부 충족 필요)

항목	요구사항
플랜	모든 플랜 (Pro 포함 — 이전엔 Team 이상이었으나 확대됨)
모델	Anthropic API: Opus 4.6 이상 또는 Sonnet 4.6 Bedrock·Vertex·Foundry: Opus 4.7·4.8만 Sonnet 4.5·Opus 4.5·Haiku·claude-3 계열은 미지원
Provider	Anthropic API·Bedrock·Vertex AI·Foundry 모두 기본 사용 가능 — v2.1.207부터 Bedrock·Vertex·Foundry도 CLAUDE_CODE_ENABLE_AUTO_MODE=1 opt-in 없이 동작. 차단하려면 settings의 disableAutoMode 사용
Admin (Team/Enterprise)	관리자가 Claude Code Admin Settings에서 활성화 필요. permissions.disableAutoMode: "disable"로 lock 가능
활성화	CLI: --permission-mode auto 또는 세션 중 Shift+Tab으로 모드 사이클. Desktop/VS Code: 모드 선택기에서 "자동 모드" 또는 "Auto mode" 선택

# CLI에서 Auto 모드로 시작
claude --permission-mode auto

조건을 하나라도 충족하지 않으면 Auto 모드 옵션 자체가 활성화되지 않습니다 (일시적 outage가 아니라 영구 비활성).

평가 순서

각 도구 호출은 다음 순서로 평가됩니다:

1. allow/deny 규칙에 매칭 → 즉시 허용/차단
2. 읽기 전용 + 작업 디렉토리 내 파일 수정 → 자동 승인
3. 그 외 → 분류기 평가
4. 분류기 차단 시 → Claude가 대안 시도

v2.1.193 — 거부 사유 표시·셸 전수 분류

분류기가 차단하면 거부 사유가 transcript·거부 토스트·/permissions(최근 거부 내역)에 표시되어 왜 막혔는지 바로 확인할 수 있습니다. 또 settings의 autoMode.classifyAllShell을 켜면 모든 Bash·PowerShell 명령이 분류기를 거치도록 할 수 있습니다.

기본 차단 목록

분류기가 기본적으로 차단하는 행위:

• 다운로드한 코드 실행 (curl | bash, 클론한 repo의 스크립트)
• 외부 엔드포인트로 민감 데이터 전송
• 프로덕션 배포/마이그레이션
• 클라우드 스토리지 대량 삭제
• IAM/repo 권한 변경
• main 브랜치 직접 push, force push
• 세션 시작 전 존재하던 파일의 비가역적 삭제
• 로컬 작업물을 버리는 파괴적 git 명령 (git reset --hard·git checkout -- .·git clean -fd·git stash drop) — "버려달라"고 명시적으로 요청하지 않은 경우 (v2.1.183 강화)
• git commit --amend — 이번 세션에서 에이전트가 만든 커밋이 아닌 경우 (v2.1.183 강화)
• 인프라 파괴 명령 (terraform destroy·pulumi destroy·cdk destroy) — 특정 스택을 지정해 요청하지 않은 경우 (v2.1.183 강화)
• 세션 transcript(대화 기록) 파일 변조 (v2.1.205 강화)
• 값을 확인할 수 없는 변수 대상 rm -rf — 차단 대신 실행 전 확인을 요청 (v2.1.206 강화)

v2.1.183·v2.1.205~206 — Auto 모드 안전 강화

(v2.1.183 강화) 세 줄의 핵심은 "시키지 않았는데 작업물을 날리는" 명령을 막는다는 것입니다. 사용자가 직접 "이 변경 전부 버려줘", "이 스택 destroy 해줘"라고 요청하면 통과하고, 그런 맥락 없이 분류기가 보기에 비가역적 파괴면 차단합니다. 마지막 두 줄은 W28에서 추가된 안전장치입니다 — 세션 기록(transcript)의 무결성을 지키고, rm -rf $DIR처럼 변수 값이 불분명한 삭제는 실행 전에 한 번 더 묻습니다.

분류기가 기본적으로 허용하는 행위:

• 작업 디렉토리 내 파일 작업
• lock 파일에 선언된 의존성 설치
• .env 읽기 및 해당 API로 인증 전송
• 읽기 전용 HTTP 요청
• 현재 브랜치 또는 Claude가 생성한 브랜치에 push

기본 규칙 확인

claude auto-mode defaults 명령으로 분류기가 사용하는 전체 규칙 목록을 확인할 수 있습니다. 설정을 만졌다가 초기 상태로 되돌리고 싶으면 claude auto-mode reset을 쓰세요 (v2.1.212 — 확인 프롬프트가 뜨며 --yes로 생략 가능).

폴백 동작

분류기가 연속 3회 또는 세션 내 총 20회 차단하면, Auto 모드가 일시 중지되고 수동 승인으로 전환됩니다. 수동 승인 후 카운터가 리셋되어 Auto 모드를 계속 사용할 수 있습니다.

Auto 모드 vs bypassPermissions

	Auto	bypassPermissions
안전 검사	분류기가 매 행위 평가	없음
사용 환경	일반 개발 환경	격리된 컨테이너/VM만
토큰 비용	분류기 호출로 추가 비용	표준
프롬프트	폴백 시에만	없음

Auto 모드 주의사항

Auto 모드는 research preview입니다. 수동 검토보다 보호 수준이 낮으며, 민감한 작업에는 Manual(기본) 모드를 사용하세요. 관리자는 disableAutoMode: "disable" 설정으로 이 모드를 차단할 수 있습니다.

권한 규칙 관리

/permissions 커맨드로 현재 규칙을 확인하고 관리합니다:

/permissions

Allow:
  - Read(*)
  - Edit(/src/**)
  - Bash(npm test *)

Deny:
  - Bash(rm *)
  - Bash(git push *)

규칙 평가 순서: deny → ask → allow. deny가 항상 우선합니다.

권한 규칙 문법

기본 형식

도구명 또는 도구명(지정자) 형식입니다.

{
  "permissions": {
    "allow": [
      "Read",                    // 모든 파일 읽기 허용
      "Bash(npm run *)",         // npm run으로 시작하는 모든 명령
      "Edit(/src/**/*.ts)"       // src 하위 TypeScript 파일만 수정
    ],
    "deny": [
      "Bash(rm *)",              // rm 명령 차단
      "Bash(git push *)"         // git push 차단
    ]
  }
}

Bash 규칙: 와일드카드 매칭

*는 글로브 패턴으로 동작합니다. 명령어 어디에서든 사용 가능합니다:

규칙	매칭
Bash(npm run build)	정확히 npm run build만
Bash(npm run *)	npm run test, npm run lint 등
Bash(* --version)	node --version, npm --version 등
Bash(git * main)	git checkout main, git merge main 등

공백+* vs *

Bash(ls *)는 ls -la에 매칭되지만 lsof에는 매칭되지 않습니다. 공백이 단어 경계를 강제합니다. Bash(ls*)는 둘 다 매칭됩니다.

셸 연산자 인식

Claude Code는 && 같은 셸 연산자를 인식합니다. Bash(safe-cmd *)는 safe-cmd && dangerous-cmd를 허용하지 않습니다.

Read/Edit 규칙: gitignore 스타일 패턴

파일 경로 규칙은 gitignore 스펙을 따릅니다:

패턴	의미	예시
//path	파일시스템 절대 경로	Read(//Users/alice/secrets/**)
~/path	홈 디렉토리 기준	Read(~/Documents/*.pdf)
/path	프로젝트 루트 기준	Edit(/src/**/*.ts)
path	현재 디렉토리 기준	Read(*.env)

{
  "permissions": {
    "allow": [
      "Edit(/docs/**)",          // 프로젝트 docs/ 하위만 수정 허용
      "Read(~/.zshrc)"           // 홈 디렉토리 .zshrc 읽기 허용
    ],
    "deny": [
      "Read(.env)",              // .env 파일 읽기 차단
      "Edit(//etc/*)"            // /etc/ 수정 차단
    ]
  }
}

* vs **

*는 한 디렉토리 내 파일만 매칭, **는 하위 디렉토리까지 재귀적으로 매칭합니다.

MCP 도구 규칙

{
  "permissions": {
    "allow": [
      "mcp__puppeteer",                       // puppeteer 서버의 모든 도구
      "mcp__github__github_list_repos"         // github 서버의 특정 도구만
    ]
  }
}

서브에이전트(Task) 규칙

{
  "permissions": {
    "deny": [
      "Agent(Explore)"           // Explore 서브에이전트 비활성화
    ]
  }
}

파라미터 매칭 규칙 — Tool(param:value)

v2.1.178부터 도구의 입력 파라미터 값으로 규칙을 매칭할 수 있습니다. 도구(파라미터:값) 형식이며 값에 * 와일드카드를 쓸 수 있습니다.

{
  "permissions": {
    "deny": [
      "Agent(model:opus)"        // Opus 모델을 쓰는 서브에이전트 차단
    ]
  }
}

Agent(model:opus)는 서브에이전트가 Opus 모델로 실행되는 것을 막습니다(비용 통제 등). 기존 Agent(Explore)가 서브에이전트 종류로 매칭한다면, Tool(param:value)는 입력 값 단위로 더 세밀하게 제어합니다.

settings.json 계층

권한 규칙은 여러 위치에 정의할 수 있으며, 우선순위는:

Managed (조직) → CLI 인수 → Local 프로젝트 → Shared 프로젝트 → User 전역

위치	파일	우선순위
조직 관리형	MDM/서버 정책	최고
CLI 인수	--allowedTools, --disallowedTools	높음
로컬 프로젝트	.claude/settings.local.json	중간
공유 프로젝트	.claude/settings.json	중간
전역 사용자	~/.claude/settings.json	낮음

프로젝트 설정이 사용자 설정보다 우선합니다. 사용자 settings에서 허용하더라도 프로젝트 settings에서 거부하면 차단됩니다.

추가 디렉토리 접근

기본적으로 Claude는 실행 디렉토리의 파일만 접근합니다. 추가 디렉토리를 열려면:

# 시작 시 추가
claude --add-dir /path/to/other-project

# 세션 중 추가
/add-dir /path/to/other-project

샌드박스와의 관계

권한(permissions)과 샌드박스(sandboxing)는 상호 보완적입니다:

	권한	샌드박스
적용 대상	모든 도구	Bash 명령만
동작	Claude의 도구 사용 제어	OS 수준 파일/네트워크 격리
방어	Claude의 의사결정 제한	프롬프트 인젝션 우회 방지

둘을 함께 사용하면 **심층 방어(defense-in-depth)**를 구현할 수 있습니다.

📬 매주 Claude Code 실전 팁을 이메일로

권한 설정부터 자동화까지 — 실제 사용 경험을 정리해서 보내드립니다. 무료 구독 →

모드 선택 가이드

지금 뭘 하려고?
│
├─ 새 코드베이스 탐색/이해
│   → Plan 모드 (읽기 전용)
│
├─ 혼자 로컬에서 빠르게 개발
│   → acceptEdits 또는 Manual(기본) 모드 (git 커밋 먼저)
│
├─ 장시간 리팩토링, 승인 피로 줄이기
│   → Auto 모드 (분류기가 대신 판단)
│
├─ 팀 프로젝트, 중요한 코드
│   → Manual(기본) 모드 + 프로젝트 settings.json에 규칙 정의
│
├─ CI/CD, 자동화 스크립트
│   → 헤드리스 모드 + allowedTools 지정
│
└─ 격리된 Docker/VM 테스트 환경
    → bypassPermissions (주의!)

실전 설정 예시

안전한 개발 환경

{
  "permissions": {
    "allow": [
      "Read",
      "Edit(/src/**)",
      "Bash(npm test *)",
      "Bash(npm run lint *)",
      "Bash(git diff *)",
      "Bash(git status *)",
      "Bash(git log *)"
    ],
    "deny": [
      "Bash(rm *)",
      "Bash(git push *)",
      "Bash(curl *)",
      "Bash(wget *)",
      "Edit(*.env)"
    ]
  }
}

CI/CD 환경 (헤드리스)

claude -p "코드 리뷰해줘" \
  --allowedTools "Read,Grep,Glob" \
  --disallowedTools "Bash,Edit,Write"