Quick Comparison

권한 모드는 Claude Code가 어떤 도구 호출을 바로 실행하고, 어떤 호출에서 멈출지를 정하는 기본선입니다. plan은 소스 파일 편집을 막고 계획을 만들지만, 탐색용 명령까지 모두 차단하는 완전한 읽기 전용 sandbox는 아닙니다. 모드 위에 allow, ask, deny 규칙과 sandbox가 별도로 겹칩니다.

# 현재 세션을 계획부터 시작한다.
claude --permission-mode plan

# 비대화형 CI는 승인 대기 대신 허용되지 않은 호출을 실패시킨다.
claude -p --permission-mode dontAsk "테스트 결과만 요약해 줘."

# plan에서 나온 계획을 수정으로 전환하기 전에는 파일·테스트 범위를 다시 확인한다.

모드별 실제 경계

default는 읽기만 자동으로 허용하고, 파일 수정과 대부분의 셸 명령은 묻습니다. acceptEdits는 현재 작업 디렉터리와 additionalDirectories 안에서 파일 생성·편집, mkdir, touch, rm, rmdir, mv, cp, sed 같은 일반 파일 시스템 명령을 자동 승인합니다. 보호 경로, 범위 밖 경로, 그 밖의 Bash 명령은 계속 승인을 요구합니다.

plan에서는 Claude가 파일을 읽고 탐색 명령을 실행해 계획을 만들지만 소스 파일을 편집하지 않습니다. 계획이 제시된 뒤에는 자동 모드·편집 자동 승인·수동 승인 중 하나를 골라 실행으로 넘어갑니다. 계획 자체는 변경 결과가 아니므로, 전환 전에 수정 파일·제외 경로·검증 명령을 다시 적습니다.

auto는 권한 창을 단순히 모두 없애는 모드가 아닙니다. 별도 분류기가 요청 범위를 벗어나는 동작, 낯선 인프라, 위험한 외부 전송 등을 검사하며, 명시 ask 규칙과 사용자 상호작용이 필요한 connector·MCP 도구는 여전히 멈춥니다. 이 검사는 리뷰를 대체하지 않으므로 인프라·배포·민감 자료 변경에는 사람이 확인할 경계를 요청과 규칙에 남깁니다.

dontAsk는 프롬프트가 필요한 호출을 허용하지 않고 거부합니다. CI에서 쓰려면 작업에 필요한 도구를 permissions.allow로 미리 좁게 허용해야 합니다. bypassPermissions는 권한 계층과 안전 검토를 건너뛰며, 일반 호스트에서는 사용하지 않습니다. 루트·홈 디렉터리 대상으로 한 파괴적 제거에는 별도 차단 장치가 남을 수 있어도, 이 모드를 안전하다고 해석하면 안 됩니다.

Plan에서 실행으로 넘어가기

계획은 문제를 이해하는 단계에 맞고, 실행 승인은 변경 계약을 확정하는 단계에 맞습니다. 아래 순서로 닫으면 계획이 길어도 실제 수정 범위가 흐려지지 않습니다.

1. Plan에서 수정 후보 파일, 영향을 받는 기능, 테스트 방법을 적는다.
2. 불필요한 파일과 외부 호출을 제외하도록 계획을 되돌려 보낸다.
3. 실행 전 "이 파일만 수정, 이 명령만 실행"으로 범위를 다시 고정한다.
4. 수동 승인 또는 acceptEdits로 구현한다.
5. diff와 테스트 결과를 본 뒤 커밋·배포는 별도로 판단한다.

세션 중 CLI에서는 Shift+Tab으로 기본 순환인 default → acceptEdits → plan을 바꿀 수 있습니다. auto, bypassPermissions, dontAsk는 환경·계정·시작 옵션에 따라 기본 순환에 없을 수 있습니다. 시작할 때는 --permission-mode <이름>, 지속 기본값은 permissions.defaultMode를 사용합니다. 단, auto 기본값은 user 또는 managed 설정에서만 허용되는 표면이 있으므로 프로젝트가 스스로 자동 실행 권한을 얻는 방식으로 쓰지 않습니다.

규칙과 보호 경로

권한 모드는 모든 규칙을 무시하지 않습니다. deny는 어느 범위에서든 우선하고, 보호 경로인 .git, .vscode, .idea, .husky, .mcp.json, .claude.json 등은 bypassPermissions를 제외한 모드에서 자동 승인되지 않습니다. sandbox를 켜면 Bash와 그 자식 프로세스에는 OS 수준의 파일·네트워크 제한도 추가됩니다.

잘못된 선택
- CI에서 default 모드로 실행하고 승인 대기 상태를 성공으로 취급한다.
- plan의 설명만 보고 검증 범위 없이 auto 또는 bypassPermissions로 전환한다.
- auto의 분류기가 있으니 배포·권한 변경도 검토하지 않는다.

권장 선택
- 처음 보는 작업: default 또는 plan
- 작은 코드 변경을 diff로 묶어 볼 때: acceptEdits
- CI 분석: dontAsk + 좁은 allow 규칙
- 완전 격리된 재현 환경: 필요한 경우만 bypassPermissions