클로드 코드 권한 모드: 매번 확인부터 완전 자동까지

클로드 코드를 쓰다 보면 “이 파일을 수정해도 될까요?”, “이 명령어를 실행해도 될까요?” 하는 승인 팝업이 끊임없이 뜹니다. 한두 번이면 괜찮지만 리팩토링처럼 파일을 수십 개씩 고치는 작업에서는 클릭 노동이 되죠. 반대로 CI/CD 파이프라인에서는 묻더라도 답할 사람이 없습니다. 😅

이처럼 상황마다 필요한 자율성이 다릅니다. 탐색만 할 때는 코드를 건드리지 못하게 막고 싶고, 빌드를 돌릴 때는 편하게 허용하고 싶죠. 클로드 코드의 권한 모드가 이 스펙트럼을 조절해 줍니다. 권한 설정이 “무엇을 허용/차단할까”를 정한다면, 권한 모드는 “얼마나 자율적으로 작업하게 할까”를 정하는 거예요.

전체 비교

각 모드는 편의성과 통제력 사이에서 다른 균형을 잡고 있어요.

위에서 아래로 갈수록 자율성이 높아지고 통제력은 줄어듭니다. 어떤 모드든 뒤에서 설명할 보호 경로에 대한 쓰기는 자동 허용되지 않아요.

모드 전환 방법

가장 빠른 건 Shift+Tab입니다. 입력창에서 누르면 default → acceptEdits → plan 순서로 순환해요. 현재 모드는 상태 표시줄에 나타나죠.

auto와 bypassPermissions는 기본 순환에 포함되지 않습니다. auto는 계정이 요구사항을 충족하면 순환에 자동으로 나타나고, bypassPermissions는 --allow-dangerously-skip-permissions 플래그로 활성화하면 추가돼요. dontAsk은 순환에 포함되지 않고 CLI 인자로만 진입할 수 있습니다.

CLI에서 세션을 시작할 때 모드를 지정할 수도 있어요.

claude --permission-mode acceptEdits

영구적으로 기본 모드를 바꾸려면 settings.json에 defaultMode를 설정하면 됩니다.

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

VS Code에서는 프롬프트 입력 상자 하단의 모드 표시기를 클릭하면 됩니다. 확장 설정의 claudeCode.initialPermissionMode로 기본값을 지정할 수도 있어요.

default 모드

기본 모드입니다. 파일 읽기와 코드 검색 같은 읽기 전용 도구만 자동으로 허용하고 파일 수정이나 명령어 실행은 매번 승인을 받아야 해요.

클로드 코드를 처음 쓸 때는 이 모드가 좋습니다. Claude가 어떤 도구를 어떤 순서로 호출하는지 직접 확인하면서 감을 잡을 수 있거든요. 민감한 프로젝트에서 모든 변경 사항을 하나하나 확인하고 싶을 때도 적합하고요.

다만 파일을 많이 고쳐야 하는 작업에서는 승인 클릭이 꽤 잦아집니다. 흐름이 자주 끊기는 게 불편해지면 acceptEdits로 올라가면 돼요.

acceptEdits 모드

파일 편집에 더해 기본 파일 시스템 명령어까지 자동 허용합니다. mkdir, touch, rm, rmdir, mv, cp, sed 같은 명령어가 승인 없이 실행되죠. LANG=C나 NO_COLOR=1 같은 환경 변수 접두사가 붙어도 허용되고, timeout이나 nice 같은 프로세스 래퍼로 감싸져 있어도 마찬가지예요.

물론 아무 곳이나 건드릴 수 있는 건 아닙니다. 자동 허용은 작업 디렉토리와 additionalDirectories로 지정한 경로 안에서만 적용돼요. 보호 경로에 대한 쓰기와 그 외의 Bash 명령어는 여전히 승인이 필요합니다.

Shift+Tab을 한 번 누르면 default에서 바로 전환됩니다.

claude --permission-mode acceptEdits

코드 변경은 자동으로 허용하되 git diff나 에디터에서 나중에 확인하는 스타일이라면 이 모드가 가장 균형 잡혀 있습니다.

plan 모드

읽기 전용 분석 모드입니다. Claude가 코드베이스를 탐색하고 구현 계획을 세울 수는 있지만 파일을 수정하거나 명령어를 실행하지는 못해요. 승인 팝업 동작은 default와 같습니다.

Shift+Tab을 두 번 누르거나 단일 프롬프트에 /plan 접두어를 붙여서 진입할 수 있습니다.

claude --permission-mode plan

계획이 완성되면 Claude가 어떻게 진행할지 물어봅니다. 이 시점에서 auto 모드로 승인하거나 acceptEdits로 승인하거나 매번 확인하며 진행하거나 피드백을 줘서 계획을 다듬을 수 있어요.

처음 접하는 코드베이스를 탐색하거나 복잡한 리팩토링의 방향을 잡을 때 유용합니다. 5단계 워크플로우, 플랜 파일 관리 같은 심화 내용은 클로드 코드 계획 모드에서 다루고 있습니다.

auto 모드

승인 팝업 없이 모든 도구를 자동 실행합니다. 다만 무방비로 실행하는 게 아니라 클로드 코드가 각 작업을 실행 전에 스스로 검사해서 위험하다고 판단하면 차단해요. 뒤에서 자세히 다룰 bypassPermissions와의 핵심 차이가 여기에 있습니다.

auto 모드를 쓰려면 몇 가지 조건을 충족해야 합니다. 우선 Max, Team, Enterprise, 또는 API 플랜이어야 해요. 모델은 Claude Sonnet 4.6, Opus 4.6, Opus 4.7을 지원하는데 Max 플랜에서는 Opus 4.7만 사용할 수 있어요. 프로바이더는 Anthropic API만 지원하고 Bedrock이나 Vertex에서는 사용할 수 없습니다.

조건을 충족하면 클로드 코드를 실행할 때 Auto Mode에 대한 팝업이 뜹니다. 여기서 Auto Mode를 활성화하면 Shift+Tab 순환에 auto가 자동으로 나타납니다. CLI에서 바로 시작할 수도 있어요.

claude --permission-mode auto

이 검사는 작업 디렉토리와 설정된 Git 원격 저장소를 신뢰합니다. 그 밖의 대상에 대한 작업은 기본적으로 외부로 취급해서 검사하죠.

기본적으로 차단되는 작업이 있습니다. 외부 스크립트를 다운로드해서 실행하는 것(curl | bash)이나 외부 엔드포인트로 민감 데이터를 보내는 건 당연히 막히고요. 프로덕션 배포, DB 테이블 삭제, 클라우드 스토리지 대량 삭제, IAM이나 저장소 권한 변경, 공유 인프라 수정도 차단됩니다. 세션 시작 전에 존재하던 파일을 복구 불가능하게 삭제하거나 main으로 force push하는 것도 마찬가지예요.

반대로 기본 허용되는 작업도 있습니다. 작업 디렉토리 안에서의 파일 조작이나 lock 파일에 선언된 의존성 설치는 문제없이 실행돼요. .env 파일을 읽고 해당 API로 인증 정보를 보내는 것, 읽기 전용 HTTP 요청, 현재 브랜치나 Claude가 만든 브랜치로의 push도 허용됩니다.

claude auto-mode defaults 명령으로 전체 차단/허용 목록을 확인할 수 있습니다. 일상적인 작업이 자꾸 차단된다면 관리자가 autoMode.environment 설정에서 신뢰할 저장소나 서비스를 추가할 수 있어요.

대화 중에 “push하지 마” 또는 “배포 전에 먼저 확인해줘”처럼 경계를 설정하면 클로드 코드가 이를 차단 신호로 인식합니다. 기본 규칙이 허용하더라도 대화에서 명시한 제약이 우선이에요. 경계는 다음 메시지에서 직접 해제할 때까지 유지되지만 컨텍스트 컴팩션으로 해당 메시지가 사라지면 함께 사라질 수 있어요. 확실하게 보장하려면 대화 경계 대신 deny 규칙을 쓰는 게 낫습니다.

작업이 차단되면 알림이 뜨고 /permissions의 “Recently denied” 탭에 기록됩니다. 여기서 r을 눌러 수동 승인으로 재시도할 수 있죠. 연속으로 차단이 반복되거나 누적 차단 횟수가 한도에 도달하면 auto 모드가 일시 중단되고 일반 승인 모드로 돌아갑니다. 수동 승인 후에는 auto 모드가 다시 재개돼요.

권한 규칙과의 관계도 알아두면 좋습니다. auto 모드에 진입하면 임의 코드 실행을 허용하는 광범위한 allow 규칙이 자동으로 해제됩니다. Bash(*) 같은 전체 허용이나 Bash(python*) 같은 인터프리터 와일드카드가 여기에 해당하죠. Bash(npm test) 같은 좁은 범위의 규칙은 유지됩니다. auto 모드를 벗어나면 해제됐던 규칙이 복원돼요.

이 안전 검사는 세션에서 선택한 모델과 별개로 서버에서 지정한 모델에서 실행되고 토큰 사용량에 포함됩니다. 읽기 작업과 보호 경로 외의 파일 편집은 이 검사를 거치지 않으니 오버헤드는 주로 셸 명령어와 네트워크 작업에서 발생해요.

dontAsk 모드

권한 설정의 allow 규칙에 매칭되는 도구와 ls, cat, grep 같은 읽기 전용 명령어만 자동 실행하고 나머지는 묻지 않고 거부합니다. ask 규칙에 해당하는 도구도 물어보는 대신 거부하기 때문에 사람의 개입이 전혀 필요 없는 완전 비대화형 모드예요.

claude --permission-mode dontAsk

CI/CD 파이프라인이나 비대화형 모드(-p 플래그)에서 사용하는 게 일반적입니다. allow 목록에 필요한 명령어를 미리 정의해두고 그 범위 안에서만 Claude가 동작하게 하는 거죠.

{
  "permissions": {
    "allow": [
      "Bash(npm run build)",
      "Bash(npm run test *)",
      "Bash(git add *)",
      "Bash(git commit *)"
    ],
    "defaultMode": "dontAsk"
  }
}

allow에 없는 건 전부 조용히 거부되니까 필요한 명령어를 빠뜨리지 않도록 주의하세요.

bypassPermissions 모드

모든 권한 확인을 건너뜁니다. 보호 경로를 제외하면 어떤 도구든 즉시 실행돼요.

claude --permission-mode bypassPermissions

--dangerously-skip-permissions 플래그도 같은 효과입니다.

이 모드는 컨테이너나 VM처럼 호스트 시스템과 완전히 격리된 환경에서만 써야 합니다. 프롬프트 인젝션이나 의도치 않은 작업에 대한 보호가 전혀 없거든요. 안전장치 없이 자동 실행하고 싶다면 bypassPermissions 대신 클로드 코드가 스스로 보호해주는 auto 모드를 고려하세요.

관리자가 disableBypassPermissionsMode를 "disable"로 설정하면 이 모드와 --dangerously-skip-permissions 플래그를 조직 전체에서 완전히 차단할 수 있습니다.

보호 경로

어떤 모드를 쓰든 특정 경로에 대한 쓰기는 자동 허용되지 않습니다. Git 상태나 클로드 코드 설정이 실수로 망가지는 걸 막기 위한 안전장치예요.

보호되는 디렉토리는 .git, .vscode, .idea, .husky입니다. .claude 디렉토리도 보호 대상이지만 .claude/commands, .claude/agents, .claude/skills, .claude/worktrees는 Claude가 일상적으로 파일을 생성하는 곳이라 예외예요.

보호되는 파일은 .gitconfig, .gitmodules 같은 Git 설정 파일, .bashrc, .bash_profile, .zshrc, .zprofile, .profile 같은 셸 설정 파일, .ripgreprc, 그리고 .mcp.json, .claude.json입니다.

모드에 따라 보호 경로를 만났을 때의 동작이 달라집니다. default, acceptEdits, bypassPermissions에서는 승인 팝업이 뜨고, auto에서는 클로드 코드가 자동으로 판단하며, dontAsk에서는 거부됩니다.

상황별 추천

어떤 모드를 써야 할지 고민된다면 작업의 성격을 기준으로 판단하면 됩니다.

혼자 개발할 때는 acceptEdits가 가장 균형 잡혀 있습니다. 코드 변경은 자동으로 허용하되 npm이나 git 같은 셸 명령어는 확인하니까 편하면서도 안전하거든요.

코드를 탐색하거나 설계를 검토할 때는 plan 모드가 딱입니다. 코드를 건드리지 않고 분석만 하니까 처음 보는 코드베이스에서 안전하게 구조를 파악할 수 있어요.

장시간 자율 작업을 맡기려면 auto를 고려하세요. “이 모듈 리팩토링해줘”처럼 큰 작업을 맡기고 중간중간 팝업에 답하기 싫을 때 유용합니다. 분류기가 위험한 작업을 걸러주니 bypassPermissions보다 안전하고요.

CI/CD 파이프라인에서는 dontAsk을 쓰세요. 사람이 승인 팝업에 답할 수 없으니 allow 목록에 필요한 명령어를 미리 정의해두고 나머지는 조용히 거부하는 게 맞습니다.

컨테이너나 VM처럼 완전히 격리된 환경에서만 bypassPermissions를 쓰세요. 호스트 시스템에 영향을 줄 수 없는 환경이라면 모든 확인을 건너뛰어도 괜찮습니다.

모드를 고른 뒤에는 권한 규칙으로 세밀하게 조정할 수 있습니다. 예를 들어 acceptEdits 모드에서 Bash(npm run test *)를 allow에 넣으면 테스트 실행까지 자동 허용하면서 다른 셸 명령어는 여전히 확인을 거치게 할 수 있어요.

마치며

권한 모드는 한 가지만 고집할 필요 없이 작업 단계에 따라 자유롭게 바꾸는 게 핵심입니다. 설계 단계에서는 plan으로 탐색하고, 코드를 고칠 때는 acceptEdits로 전환하고, 큰 작업을 맡길 때는 auto로 올리면 됩니다. Shift+Tab으로 순식간에 바꿀 수 있으니까요.

모드가 “얼마나 자율적으로”를 정한다면 권한 규칙은 “무엇을 허용/차단할지”를 정합니다. 두 설정을 함께 조합하면 팝업 피로를 줄이면서도 안전한 작업 환경을 만들 수 있어요. OS 레벨 격리까지 적용하고 싶다면 클로드 코드 샌드박스도 참고하세요.

더 자세한 내용은 Permission modes 공식 문서를 참고하세요.