Claude Code 권한 모드 총정리 — plan·accept edits·auto 차이와 shift+tab 활용법

이 글 한 줄 요약

Claude Code 하단 상태바의 ⏵⏵ accept edits on, ⏸ plan mode on, auto mode는 모두 "권한 모드(permission mode)"다. Claude에게 얼마만큼의 자율성을 줄지 결정하는 스위치이며, Shift+Tab으로 순환한다. 모드별 동작 범위·진입 방법·설정 파일까지 한 번에 정리했다.

Claude Code를 쓰다 보면 터미널 맨 아래에 이런 줄이 보인다.

auto mode
? for shortcuts · ← for agents

 ⏵⏵ accept edits on (shift+tab to cycle) · ← for agents

 ⏸ plan mode on (shift+tab to cycle) · ← for agents

처음엔 그냥 상태 표시처럼 보이지만, 사실 이건 Claude가 파일을 고치거나 명령을 실행할 때 매번 물어볼지, 알아서 진행할지를 정하는 권한 모드다. 단순한 키 토글처럼 생겼지만 어떤 모드를 언제 쓰느냐에 따라 작업 흐름 자체가 완전히 달라진다. 사내 폐쇄망에서 LLM 인프라를 운영하면서 코드 리뷰 봇이나 자동화 파이프라인에 Claude Code를 붙일 때도 이 모드 이해가 출발점이 된다. 이번 글에서 각 모드의 동작 범위와 설정 방법을 실전 위주로 정리한다.

Claude Code 권한 모드란 무엇인가

권한 모드는 Claude Code가 도구(Bash, Read, Edit, WebFetch, MCP 등)를 사용할 때 사람에게 확인을 받는 "기준선(baseline)"이다. 핵심은 모드가 전부를 결정하지 않는다는 점이다. 모드는 큰 틀의 자동 승인 범위만 잡고, 그 위에 /permissions로 개별 허용·차단 규칙을 얹는 2단 구조다.

중요한 안전장치가 하나 있다. bypassPermissions를 제외한 모든 모드에서 보호 경로(.git, .claude 같은 설정 디렉터리)에 대한 쓰기는 절대 자동 승인되지 않는다. 저장소 상태와 Claude 자신의 설정이 사고로 깨지는 걸 막기 위해서다.

또 하나 헷갈리기 쉬운 부분 — 모드는 채팅으로 "이제 자동 승인해줘"라고 Claude에게 부탁하는 게 아니라, Shift+Tab이나 모드 선택기로 사용자가 직접 바꾼다. 세션 도중에도, 시작 시점에도, 설정 파일의 영구 기본값으로도 지정할 수 있다.

💡 모드 vs 권한 규칙

모드는 "기본적으로 얼마나 물어볼지", /permissions의 allow/deny 규칙은 "특정 도구는 항상 허용/차단". deny 규칙과 명시적 ask 규칙은 bypassPermissions를 포함한 모든 모드에서 적용된다. 반면 allow 규칙은 bypass 모드에서는 의미가 없다(이미 전부 승인되므로).

모드 전환의 기본 — Shift+Tab 사이클

가장 자주 쓰는 전환 방법은 Shift+Tab이다. 기본 사이클은 다음 순서로 돈다.

Shift+Tab 한 번씩 누를 때마다:

default → acceptEdits → plan → (auto) → default ...
   ↑          ↑           ↑       ↑
 기본    파일편집 자동   읽기전용  계정 조건 충족 시 노출

현재 어떤 모드인지는 상태바에 그대로 표시된다. 모든 모드가 사이클에 들어있는 건 아니다. auto는 계정이 조건을 만족할 때만 사이클에 나타나고, dontAsk와 bypassPermissions는 기본 사이클에서 빠져 있어 시작 옵션이나 설정으로만 켠다.

프로젝트마다 시작 모드를 고정하고 싶다면 .claude/settings.json에 defaultMode를 지정한다.

{
  "permissions": {
    "defaultMode": "plan"
  }
}

이렇게 두면 해당 프로젝트에서 Claude Code가 항상 plan 모드로 시작한다. 마이그레이션이나 인증·결제처럼 위험한 코드베이스에서는 plan을 기본값으로 두는 게 안전하다.

accept edits 모드 (⏵⏵ accept edits on)

상태바에 ⏵⏵ accept edits on이 뜨면 이 모드다. 작업 디렉터리 안에서 파일 생성·편집을 프롬프트 없이 자동 승인한다. default 모드에서 Shift+Tab을 한 번 누르면 진입한다.

흔한 오해가 여기서 생긴다. accept edits는 "전부 승인"이 아니다. 파일 편집과 함께 일부 기본 파일시스템 명령만 자동 승인된다.

accept edits가 자동 승인하는 것

• 작업 디렉터리 내 파일 생성·편집
• 기본 파일시스템 명령: mkdir, touch, rm, rmdir, mv, cp, sed
• 위 명령에 안전한 환경변수(LANG=C, NO_COLOR=1)나 래퍼(timeout, nice, nohup)가 붙은 경우

accept edits가 여전히 물어보는 것

• 작업 디렉터리(또는 additionalDirectories) 밖의 경로에 대한 쓰기
• 보호 경로에 대한 쓰기
• 그 외 모든 Bash 명령 — npm test, git push, 빌드/배포 등

실시간으로 변경이 적용되니 빠르지만, 각 변경을 사전에 검토하지는 못한다. accept edits를 켜기 전에 반드시 커밋해 두면, 마음에 안 드는 변경을 git으로 쉽게 되돌릴 수 있다. 뭔가 잘못되면 Ctrl+C로 작업을 중단할 수 있다는 점도 기억해 두자.

plan mode (⏸ plan mode on)

상태바에 ⏸ plan mode on이 뜨는 읽기 전용 모드다. Claude가 코드베이스를 분석하고 해결책을 제안하고 복잡한 작업을 추론할 수는 있지만, 파일을 수정하거나 명령을 실행하지 못한다. default에서 Shift+Tab을 두 번 누르면 도달한다(한 번은 accept edits, 두 번째가 plan).

진입 방법 3가지

• Shift+Tab 순환: 가장 빠른 방법
• 프롬프트 프리픽스: 단일 프롬프트 앞에 /plan을 붙이면 그 한 번만 plan으로 동작
• CLI 시작 옵션 (헤드리스 분석에 유용):

claude --permission-mode plan -p "인증 플로우를 분석하고 리팩토링 전 리스크를 정리해줘"

플랜 검토와 승인

플랜이 준비되면 Claude가 어떻게 진행할지 물어본다. auto로 전환해서 승인, accept edits로 승인, 수동 검토로 승인, 계속 다듬기 중에서 고른다. 플랜을 승인하면 plan 모드를 빠져나가 선택한 모드로 전환되며 그때부터 편집을 시작한다.

실전 팁 — Claude가 플랜을 제시했을 때 Ctrl+G를 누르면 기본 텍스트 에디터에서 플랜을 직접 열어 수정할 수 있다. 주석을 달거나 일부를 지우고 돌아와서 "이렇게 바꿔줘"라고 지시하면 된다.

💡 언제 plan을 쓰나

잘못된 변경의 비용이 클 때 — DB 마이그레이션, 대규모 리팩토링, 인증·결제 로직, 프로덕션 설정, 여러 파일에 걸친 기능. 작은 오타 수정에는 과하지만, 공유 로직이나 익숙하지 않은 코드를 건드릴 땐 짧은 분석 한 번이 값싼 보험이 된다.

auto 모드 — 분류기가 지키는 자율 실행

가장 최근에 추가된 모드로, 프롬프트 피로(매번 뜨는 승인 창에 무의식적으로 Enter를 치게 되는 현상)를 해결하기 위해 설계됐다. auto 모드는 Claude Code v2.1.83 이상이 필요하다.

핵심은 별도의 분류기(classifier) 모델이 안전망 역할을 한다는 점이다. 매 동작이 실행되기 전에 별도 분류기가 검토해서, 요청 범위를 넘어 권한이 확대되거나 인식되지 않은 인프라를 건드리는 행동을 차단한다. 배포, 대량 삭제, force push, curl | bash 같은 위험한 작업은 막고, 안전한 작업은 조용히 실행한다.

사용 조건

• 플랜: Max·Team·Enterprise·API 플랜에서 사용 가능(개인 Pro에서는 현재 미지원)
• 모델: 분류기는 Sonnet 4.6 계열이 담당하며, 활성 모델로 Sonnet 4.6 / Opus 4.6 / Opus 4.7 필요(일부 플랜에서는 상위 Opus만 동작)

조건이 충족되면 auto가 Shift+Tab 사이클에 자동으로 나타난다. 처음 auto로 순환할 때 일회성 opt-in 프롬프트가 뜨고, "아니오, 다시 묻지 않기"를 선택하면 사이클에서 제거된다.

auto는 --dangerously-skip-permissions(YOLO)의 안전한 대안이다. YOLO는 안전망이 전혀 없지만, auto는 지치지 않는 분류기가 모든 동작을 검사한다. 20번째 승인 창에서 이미 화면을 안 읽고 누르고 있는 사람보다, 매번 검사하는 분류기가 실제로 더 안전할 수 있다.

사이클 밖의 두 모드 — dontAsk·bypassPermissions

Shift+Tab 기본 사이클에는 없지만, 자동화·CI 환경에서 알아둘 만한 두 모드가 더 있다.

dontAsk — 화이트리스트 외 전부 거부

permissions.allow 규칙에 맞는 도구만 실행하고, 나머지는 프롬프트 없이 조용히 거부한다. CI 파이프라인이나 잠긴 스크립트용이다. 미리 허용 목록을 정의해 두고 그 안에서만 돌리는 방식이다.

# /permissions 로 사전 허용 규칙 추가
Bash(npm test)
Bash(git add *)
Bash(git commit *)

bypassPermissions — 모든 안전장치 해제

모든 권한 프롬프트와 안전 검사를 끈다. 보호 경로 쓰기를 제외하면 전부 즉시 실행된다. CLI 플래그로 켠다.

claude --dangerously-skip-permissions

플래그 이름에 "dangerously"가 붙은 데는 이유가 있다. 분류기도, 가드레일도, 프롬프트 주입(prompt injection) 방어도 없다. 호스트 머신에서 돌리면 Claude가 파괴적 명령을 그대로 실행할 수 있다. 반드시 컨테이너·VM·일회용 CI 러너 같은 격리 환경에서만 써야 한다. 같은 "프롬프트 없는 흐름"을 자기 머신에서 안전하게 쓰고 싶다면, 가드레일을 제거하는 대신 OS 레벨 샌드박스(/sandbox)로 운영체제 차원의 벽을 세우는 쪽이 낫다.

한눈에 보는 모드 비교

모드	상태바 표시	파일 편집	Bash 명령	사이클	주 용도
default	(기본)	물어봄	물어봄	포함	가장 안전, 일반 작업
acceptEdits	⏵⏵ accept edits on	자동 승인	기본 fs만 자동	포함	반복 편집 속도
plan	⏸ plan mode on	불가(읽기전용)	불가	포함	분석·설계 후 실행
auto 신규	auto mode	분류기 검사 후 자동	분류기 검사 후 자동	조건부 노출	프롬프트 피로 해소
dontAsk	(시작 옵션)	allow만 허용	allow만 허용	제외	CI·잠긴 스크립트
bypassPermissions	(시작 옵션)	전부 실행	전부 실행	제외	격리 환경 자동화

참고로 코드 에이전트를 종일 돌리다 보면 작업 환경 자체가 생산성에 은근히 영향을 줍니다. 듀얼 모니터, USB-C 허브, 기계식 키보드 같은 개발자용 주변기기를 찾는다면 아래에서 인기 아이템을 둘러보세요.

어떤 모드를 언제 쓰나 — 실전 가이드

모드 자체보다 "상황에 맞게 고르는 습관"이 더 중요하다. 작업 성격에 따라 이렇게 매칭하면 무난하다.

• 탐색·설계 단계: plan 모드로 시작. 제안을 검토하기 전엔 아무것도 못 건드리게 한다.
• 반복 편집·리팩토링: accept edits. 단, 사전 커밋 필수. git 클린 상태를 만들어 두면 언제든 되돌린다.
• 프롬프트 피로가 심할 때: 조건이 되면 auto. 분류기가 위험 동작을 걸러준다.
• 팀·운영 환경: 모드만 믿지 말고 샌드박스 병행. 권한 deny 규칙 + 샌드박스(파일시스템·네트워크 경계)를 함께 쓰는 게 가장 강한 구성이다.

폐쇄망·자동화에 붙일 때

사내 폐쇄망에서 LiteLLM→vLLM 파이프라인 위에 Claude Code를 코드 리뷰 봇이나 배치 자동화로 붙이는 경우라면, default를 유지하면서 자주 쓰는 명령만 /permissions로 사전 허용하는 방식이 통제하기 가장 좋다. 무인 실행이 필요하면 호스트가 아니라 격리된 컨테이너에서 dontAsk(화이트리스트) 또는 bypass + 샌드박스 조합으로 경계를 명확히 잡는다. 모드 하나로 끝내기보다, "모드 + allow/deny 규칙 + OS 샌드박스"를 겹쳐 쌓는 게 핵심이다.

정리

상태바의 세 줄은 권한 모드 표시다. Shift+Tab으로 default → acceptEdits → plan을 순환하고, 조건이 되면 auto가 추가된다. accept edits는 "파일 편집 + 기본 fs 명령"만 자동 승인하지 전부가 아니며, plan은 읽기 전용 분석, auto는 분류기가 지키는 자율 실행이다. 격리 환경이 아니라면 bypassPermissions는 피하고, 모드 위에 /permissions 규칙과 샌드박스를 겹쳐 쓰는 것이 안전과 속도의 균형점이다.

※ UI 라벨·단축키·버전 요구사항은 업데이트로 바뀔 수 있습니다. 설치된 버전에서 실제 동작을 확인하고, 최신 정보는 Claude Code 공식 문서(code.claude.com/docs)를 참고하세요. 본 글은 작성 시점 기준 정리이며 특정 환경에서의 동작을 보장하지 않습니다.