권한 시스템 아키텍처

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

왜 권한 시스템이 필요한가

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

대화형 개발 세션에서는 위험한 작업 전에 확인을 요청하고, 신뢰할 수 있는 CI/CD 파이프라인에서는 모든 검사를 생략해 속도를 높일 수 있습니다.

6가지 권한 모드

Default

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

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

AcceptEdits

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

Plan

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

BypassPermissions

모든 권한 검사를 비활성화합니다. 사전에 충분히 검토되고 감사된 자동화 워크플로우에서만 사용해야 합니다. 이 모드는 모든 도구 호출을 즉시 실행하므로, 신뢰할 수 없는 입력과 함께 사용하면 매우 위험합니다.

DontAsk

스크립트나 비대화형 시나리오에서 모든 작업을 자동 승인합니다. BypassPermissions와 달리 보안 검사 자체는 유지되지만, 사용자에게 확인을 요청하지 않습니다. --print 모드와 함께 파이프라인에서 자주 사용됩니다.

Auto (실험적)

보조 AI 모델이 각 도구 호출을 평가하여 자동 승인 또는 사용자에게 에스컬레이션할지 결정합니다. 위험도 평가를 AI에게 위임하는 실험적 모드로, 아직 프로덕션 환경에서는 권장되지 않습니다.

6가지 모드 비교

모드	읽기	파일 편집	Bash 실행	적합한 용도
Default	자동	확인 필요	확인 필요	일반 대화형 개발
AcceptEdits	자동	자동	확인 필요	빠른 코드 편집 세션
Plan	자동	차단	차단	계획 검토, 읽기 전용 분석
BypassPermissions	자동	자동	자동	감사된 자동화 워크플로우
DontAsk	자동	자동	자동	스크립트, CI 파이프라인
Auto	자동	AI 평가	AI 평가	실험적 환경

권한 모드 설정 방법

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

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

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

# 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에서 기본 모드를 지정할 수 있습니다.

{
  "permissionMode": "acceptEdits"
}

모드 선택 가이드

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

탐색/분석만 할 때 → Plan 모드로 안전하게 코드베이스를 파악
활발한 개발 중 → Default 또는 AcceptEdits로 균형 유지
신뢰된 자동화 → DontAsk 또는 BypassPermissions로 속도 극대화
위험도 불명확 → Default로 시작해서 필요시 완화

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