권한 시스템 아키텍처

Claude Code는 권한 시스템(Permission System) 을 통해 도구 호출의 자동 승인 수준을 제어합니다. 어떤 작업은 사용자 확인 없이 바로 실행되고, 어떤 작업은 반드시 승인을 받아야 합니다. 이 동작 방식은 6가지 권한 모드 중 하나로 결정됩니다.

왜 권한 시스템이 필요한가

AI가 파일을 읽고 코드를 실행하고 네트워크에 접근하는 환경에서, 모든 작업을 무조건 허용하면 위험합니다. 반대로 매번 확인을 요구하면 생산성이 떨어집니다. 권한 시스템은 이 두 극단 사이에서 상황에 맞는 균형점 을 제공합니다.

대화형 개발 세션에서는 위험한 작업 전에 확인을 요청하고, 자동화에서는 사전에 허용한 도구만 열거나 격리 환경을 사용해 승인 표면을 줄일 수 있습니다.

6가지 권한 모드

Default

기본 모드입니다. 잠재적으로 위험한 작업(파일 쓰기, Bash 실행 등)에는 확인 프롬프트를 표시하고, 읽기 전용 작업(파일 읽기, 목록 조회 등)은 자동 승인합니다.

Claude: 이 파일을 삭제할까요?
> [y/N]

AcceptEdits

파일 편집과 쓰기 작업을 자동 승인합니다. Bash 명령어 실행은 여전히 확인이 필요합니다. 코드 편집 작업이 많지만 셸 명령어는 신중히 다루고 싶을 때 유용합니다.

Plan

읽기 전용 작업만 허용합니다. 파일을 읽고 분석하는 것은 가능하지만, 어떤 쓰기나 실행도 허용되지 않습니다. ExitPlanMode 도구를 통해 실행 모드로의 전환을 요청 할 수 있으며, 사용자가 이를 승인하면 전환됩니다. 큰 변경을 실행하기 전에 계획을 먼저 검토하는 워크플로우에 적합합니다.

BypassPermissions

대부분의 권한 프롬프트를 건너뜁니다. 그러나 명시적 ask 규칙, 조직이 확인을 강제한 커넥터, 사용자 상호작용이 필요한 MCP 도구, 루트·홈 디렉터리 제거 회로 차단기는 계속 확인할 수 있습니다. 사전에 충분히 검토한 격리 환경에서만 사용해야 합니다.

주의

BypassPermissions 는 CI/CD나 감독된 자동화 환경에서만 사용하세요. 사용자 대화형 세션에서 이 모드를 사용하면 의도치 않은 파일 삭제나 시스템 변경이 발생할 수 있습니다.

DontAsk

비대화형 시나리오에서 “묻지 않고 거절”하는 모드입니다. allowed_tools나 설정 파일의 allow 규칙, 훅에서 미리 승인된 도구는 실행되지만, 그 외의 도구는 사용자 확인 프롬프트를 띄우는 대신 거절됩니다. 따라서 DontAsk는 자동 승인 모드가 아니라 명시적으로 허용한 도구 표면만 열어두는 잠금 모드에 가깝습니다.

{
  "allowedTools": ["Read", "Glob", "Grep"],
  "permissionMode": "dontAsk"
}

Auto

백그라운드 안전 검사가 사용자 요청과의 정합성을 평가하면서 도구 호출을 자동 승인합니다. 조직은 permissions.disableAutoMode를 "disable"로 설정해 이 모드 사용을 막을 수 있습니다. 자동 승인은 샌드박스나 최소 권한 설계를 대체하지 않습니다.

6가지 모드 비교

| 모드 | 읽기 | 파일 편집 | Bash 실행 | 적합한 용도 | |------|------|-----------|-----------|------------| | Default | 자동 | 확인 필요 | 확인 필요 | 일반 대화형 개발 | | AcceptEdits | 자동 | 자동 | 확인 필요 | 빠른 코드 편집 세션 | | Plan | 자동 | 차단 | 차단 | 계획 검토, 읽기 전용 분석 | | BypassPermissions | 자동 | 자동 | 자동 | 감사된 자동화 워크플로우 | | DontAsk | 허용 규칙만 | 허용 규칙만 | 허용 규칙만 | 고정된 도구 표면의 비대화형 실행 | | Auto | 자동 | 안전 검사 | 안전 검사 | 감독된 자동 승인 |

규칙 우선순위

명시적 권한 규칙은 deny → ask → allow 순서로 평가됩니다. 더 구체적인 allow 규칙이 있어도 넓은 deny 규칙과 함께 일치하면 deny가 우선합니다. CLAUDE.md의 지시는 행동을 유도하지만 권한 경계를 변경하지 않습니다.

권한 모드 설정 방법

권한 모드를 변경하는 방법은 세 가지입니다.

1. CLI 플래그 (단일 실행)

# BypassPermissions 모드로 실행
claude --permission-mode bypassPermissions "모든 테스트 파일 업데이트"

# Plan 모드로 실행
claude --permission-mode plan "리팩토링 계획 수립"

2. /permissions 명령어 (세션 중 변경)

Claude Code REPL 내에서 실시간으로 모드를 전환할 수 있습니다.

/permissions
> 현재 모드: Default
> 변경할 모드 선택: [1] AcceptEdits  [2] Plan  [3] DontAsk

3. 설정 파일 (영구 설정)

~/.claude/settings.json 또는 프로젝트의 .claude/settings.json에서 기본 모드를 지정할 수 있습니다.

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

팁

프로젝트 .claude/settings.json에 설정하면 팀 전체가 동일한 기본 권한 모드로 작업할 수 있습니다. 단, BypassPermissions는 개인 설정에만 두는 것을 권장합니다.

모드 선택 가이드

실제로 어떤 모드를 언제 사용해야 할지는 작업 컨텍스트에 따라 다릅니다.

• 탐색/분석만 할 때 → Plan 모드로 안전하게 코드베이스를 파악
• 활발한 개발 중 → Default 또는 AcceptEdits로 균형 유지
• 허용 도구가 명확한 자동화 → DontAsk + allow 규칙으로 도구 표면 고정
• 격리되고 감사된 자동화 → BypassPermissions로 속도 극대화
• 위험도 불명확 → Default로 시작해서 필요시 완화

권한 시스템은 보안과 생산성의 균형입니다. 무조건 제한하거나 무조건 허용하는 대신, 상황에 맞는 모드를 선택하는 것이 핵심입니다.