양파개발자 실바의 블로그

VSCode Claude Code 확장의 권한 모드 4가지 제대로 쓰는 법

dev ai

1. 권한 모드란 무엇인가

AI 코딩 어시스턴트가 파일을 수정하거나 셸 명령을 실행하려 할 때, 도구는 일단 멈추고 사용자에게 승인을 요청합니다. 권한 모드(Permission Mode)는 이 “멈춤”이 얼마나 자주 일어날지를 정하는 설정입니다.

VSCode Claude Code 확장에서는 프롬프트 입력창 하단의 모드 표시기를 클릭하거나 Shift + Tab으로 전환할 수 있습니다.

여기서 중요한 개념이 하나 있습니다. 모드는 “기준선(baseline)”일 뿐입니다.

  • 모드가 정하는 것: 아무 규칙도 없을 때 무엇이 승인 없이 실행되는가
  • 그 위에 얹는 것: permissions.allow / ask / deny 규칙 (~/.claude/settings.json)

deny 규칙은 어떤 모드에서도 우선 적용됩니다. 즉 “특정 명령은 절대 안 됨”을 확실히 보장하려면 모드가 아니라 규칙으로 막아야 합니다.

2. 4가지 모드 비교

UI에 보이는 라벨과 내부 설정값이 다르기 때문에, 문서나 설정 파일을 볼 때 혼동하기 쉽습니다.

UI 라벨 내부 설정값 승인 없이 실행되는 범위 추천 상황
Manual default 읽기 전용 작업만 민감한 코드, 초기 탐색
Edit automatically acceptEdits 읽기 + 파일 수정 + 일부 파일시스템 명령 리뷰하며 반복 수정
Plan plan 읽기 (수정은 승인 전까지 차단) 코드베이스 파악, 큰 기능 설계
Auto auto 거의 전부 (분류기 심사 통과 시) 장시간 작업, 승인 피로 감소

2-1. Manual — 모든 것을 직접 확인

읽기 작업만 자동 승인되고, 파일 수정과 대부분의 셸 명령은 매번 물어봅니다.

내부 설정값은 default이며 manual은 그 별칭입니다. 즉 settings.json에 "defaultMode": "default"와 "defaultMode": "manual"은 같은 의미입니다.

언제 쓰나: 핵심 비즈니스 로직을 건드릴 때, 또는 어시스턴트의 작업 스타일을 아직 파악하지 못한 초기 단계.

2-2. Edit automatically — 파일 수정을 묻지 않음

가장 오해가 많은 모드입니다. “계획을 건너뛰는 모드”가 아니라, 파일 수정을 자동 승인하는 모드입니다.

자동 승인되는 범위:

  • 작업 디렉터리 내 파일 생성·수정
  • 파일시스템 관련 Bash 명령: mkdir, touch, rm, rmdir, mv, cp, sed

여기서 실무에서 꼭 알아야 할 두 가지 예외가 있습니다.

첫째, 작업 디렉터리 밖은 여전히 물어봅니다. 자동 승인은 워크스페이스 또는 additionalDirectories에 등록된 경로 내부에만 적용됩니다.

둘째, 보호 경로(protected paths)는 자동 승인되지 않습니다. 아래 경로에 대한 쓰기는 이 모드에서도 승인 프롬프트가 뜹니다.

.git/  .vscode/  .idea/  .claude/  .devcontainer/  .husky/
.gitconfig  .zshrc  .bashrc  .npmrc  .pre-commit-config.yaml
.mcp.json  .claude.json  ...

git 내부 상태나 셸 설정 파일처럼 “잘못 건드리면 환경 자체가 깨지는” 파일들을 보호하기 위한 장치입니다. 참고로 settings.json에 Edit(.claude/**) 같은 allow 규칙을 넣어도 이 보호는 뚫리지 않습니다. 보호 검사가 allow 규칙 평가보다 먼저 실행되기 때문입니다.

언제 쓰나: 매 수정을 인라인으로 승인하는 대신, 작업이 끝난 뒤 git diff로 한꺼번에 검토하고 싶을 때.

2-3. Plan — 승인 전까지 수정을 실제로 차단

Plan 모드는 “계획을 먼저 보여주는” 정도가 아니라, 승인 전까지 소스 수정이 실제로 차단됩니다. 코드를 읽고 탐색용 명령을 실행해 계획을 작성할 뿐입니다.

VSCode 확장의 장점이 여기서 나옵니다. 계획이 전체 마크다운 문서로 열리고, 인라인 코멘트를 달아 피드백할 수 있습니다. 터미널에서 텍스트로 읽는 것과는 체감이 꽤 다릅니다.

계획이 완성되면 다음 선택지가 제시됩니다.

  • Yes, and use auto mode: 승인하고 Auto 모드로 실행 (Auto를 쓸 수 없는 계정은 “Yes, auto-accept edits”로 표시)
  • Yes, manually approve edits: 승인하되 수정은 하나씩 검토
  • No, keep planning: Plan 모드에 머물며 계획 수정 요청

즉 계획 승인은 곧 모드 전환입니다. 승인 순간 Plan 모드를 벗어나 선택한 모드로 실행이 시작됩니다.

언제 쓰나: 어느 파일을 건드려야 할지 모르는 버그 수정, 규모가 큰 신규 기능, 구조 리팩터링. 복잡한 작업의 기본값으로 두기 가장 좋습니다.

2-4. Auto — 분류기가 대신 판단

Auto 모드는 “안전해 보이면 통과”라는 느슨한 규칙이 아닙니다. 별도의 분류기(classifier) 모델이 실행 직전 모든 행동을 심사하는 구조입니다.

분류기는 요청 범위를 넘어서는 행동, 인식되지 않은 인프라를 건드리는 행동, 외부에서 읽어온 콘텐츠에 조종당한 듯한 행동을 차단합니다.

기본 차단 예시

  • curl | bash 같은 원격 코드 다운로드 후 실행
  • 프로덕션 배포 및 마이그레이션
  • force push, git reset --hard, git clean -fd
  • 세션 시작 전부터 존재했던 파일의 되돌릴 수 없는 삭제
  • 민감 데이터를 외부 엔드포인트로 전송
  • IAM·저장소 권한 부여, terraform destroy 계열

기본 허용 예시

  • 작업 디렉터리 내 로컬 파일 작업
  • lock 파일·매니페스트에 선언된 의존성 설치
  • 읽기 전용 HTTP 요청
  • 현재 작업 중인 저장소의 브랜치로 push

주의할 제약이 두 가지 있습니다.

모델 제약: Auto 모드는 모드 표시기에 항상 보이지 않습니다. Opus 4.6 이상, Sonnet 4.6 이상, Fable 5 등 지원 모델에서만 노출됩니다. Sonnet 4.5, Opus 4.5, Haiku 계열에서는 나타나지 않습니다.

자동 폴백: 분류기가 3회 연속 또는 누적 20회 차단하면 Auto 모드가 일시 중지되고 다시 승인 요청 방식으로 돌아옵니다. 이 임계값은 조정할 수 없습니다. 차단이 반복된다면 분류기가 우리 인프라를 모르고 있다는 신호이므로, autoMode.environment 설정으로 신뢰할 인프라를 등록하는 것이 정석입니다.

공식 문서도 명시합니다. Auto 모드는 승인 프롬프트를 줄여주지만 안전을 보장하지는 않습니다. 방향을 신뢰할 수 있는 작업에만 쓰고, 민감한 작업의 리뷰를 대체하는 수단으로 쓰지 않아야 합니다.

3. 숨은 다섯 번째 모드: Bypass permissions

기본 화면에는 보이지 않지만 모드는 하나 더 있습니다. 확장 설정에서 Allow dangerously skip permissions 토글을 켜야 목록에 나타납니다.

bypassPermissions는 승인 프롬프트와 안전 검사를 전부 생략합니다. 위에서 설명한 보호 경로 쓰기까지 그대로 실행됩니다. 프롬프트 인젝션에 대한 방어가 사실상 없습니다.

// ~/.claude/settings.json
{
  "permissions": {
    "defaultMode": "bypassPermissions"
  }
}

인터넷이 차단된 컨테이너·VM·dev container 등 완전히 격리된 환경 전용입니다. 승인 프롬프트가 귀찮아서 이 모드를 켜려는 상황이라면, 정답은 Auto 모드입니다. Auto는 백그라운드 안전 검사를 유지한 채 프롬프트를 크게 줄여줍니다.

참고로 이미 시작된 세션에서 이 모드로 전환하는 것은 불가능합니다. 실행 시점에 활성화해야 합니다.

4. Effort 설정 — 모드와는 다른 축

모드 선택 창 하단의 Effort 슬라이더는 권한과 무관합니다. 모델이 각 단계에서 얼마나 깊이 추론할지를 조절하는 별개의 축입니다.

단계 특징
low 빠르고 저렴. 단순 작업
medium 중간
high 기본값. 대부분의 개발 작업에 적합
xhigh 더 깊은 추론
max 가장 깊은 추론. 현재 세션에만 적용되고 저장되지 않음

초안 수준의 흔한 오해가 “High / Low 두 단계”인데, 실제로는 5단계입니다. 지원 단계는 모델에 따라 다릅니다. Opus 5, Sonnet 5, Fable 5는 5단계 전부를, Opus 4.6·Sonnet 4.6은 xhigh를 제외한 4단계를 지원합니다. 지원하지 않는 단계를 지정하면 그 아래 최고 단계로 자동 조정됩니다.

/effort 메뉴에는 ultracode라는 항목도 있습니다. 이는 모델의 추론 단계가 아니라 Claude Code의 설정값으로, xhigh로 요청을 보내면서 추가로 동적 워크플로 오케스트레이션까지 수행합니다. 역시 현재 세션에만 적용됩니다.

정리하면 모드와 Effort는 곱해서 쓰는 두 축입니다.

  • Plan + high → 설계 품질을 높이는 조합
  • Edit automatically + medium → 단순 반복 수정을 빠르게
  • Auto + low → 대량 기계적 작업을 저렴하게

5. 실무 워크플로우

작업 성격에 따라 모드를 바꿔가며 쓰는 것이 핵심입니다.

1) 규모 있는 신규 기능

Plan + high로 시작합니다. 계획 문서에 인라인 코멘트로 피드백하고, 만족스러우면 “Yes, and use auto mode”로 승인해 실행 속도를 확보합니다.

2) 소규모 리팩터링·오타 수정

Edit automatically + medium. 결과가 예상 가능하므로 매 수정을 승인할 이유가 없습니다. 끝나고 git diff로 한 번에 봅니다.

3) 장시간 반복 작업

Auto. 테스트 수정, 대량 마이그레이션처럼 방향은 명확하고 손이 많이 가는 작업에 적합합니다.

4) 남의 코드·신뢰할 수 없는 저장소

Manual을 유지하고, VSCode의 Restricted Mode도 함께 켭니다. 자동 수정이 허용된 상태에서는 settings.json이나 tasks.json처럼 VSCode가 자동 실행할 수 있는 설정 파일이 수정될 여지가 있기 때문입니다.

기본 모드 고정하기

VSCode 설정에서 claudeCode.initialPermissionMode로 새 대화의 시작 모드를 지정할 수 있습니다.

// VSCode settings.json
{
  "claudeCode.initialPermissionMode": "plan"
}

단 이 설정은 auto를 받지 않습니다. Auto로 시작하고 싶다면 ~/.claude/settings.json의 permissions.defaultMode에 지정해야 합니다. 프로젝트 단위 설정 파일(.claude/settings.json)에 넣은 auto는 무시되는데, 저장소가 스스로에게 Auto 권한을 부여하는 상황을 막기 위한 설계입니다.

6. 대화로 선을 긋기 (그리고 그 한계)

Auto 모드에는 알아두면 유용한 특성이 있습니다. 대화 중 말한 제약을 분류기가 차단 신호로 인식합니다.

"푸시는 하지 마"
"내가 리뷰할 때까지 배포하지 말고 기다려"

이렇게 말해두면 기본 규칙상 허용되는 행동이라도 차단됩니다. 제약은 이후 메시지에서 직접 해제할 때까지 유지되고, 어시스턴트가 스스로 “조건이 충족됐다”고 판단해도 풀리지 않습니다.

다만 한계가 있습니다. 이 제약은 규칙으로 저장되지 않고, 분류기가 매번 대화 기록에서 다시 읽어옵니다. 따라서 컨텍스트 압축(compaction)으로 해당 메시지가 사라지면 제약도 함께 사라집니다.

긴 세션에서 확실히 보장해야 하는 제약이라면 deny 규칙으로 못 박는 것이 맞습니다.

// ~/.claude/settings.json
{
  "permissions": {
    "deny": ["Bash(git push:*)"]
  }
}

핵심요약

  • 모드는 기준선, 규칙은 보증입니다. 확실히 막아야 하는 것은 모드가 아니라 deny 규칙으로 막습니다.
  • Manual(읽기만) → Edit automatically(파일 수정까지) → Plan(승인 전 수정 차단) → Auto(분류기 심사 후 거의 전부) 순으로 자율성이 커집니다.
  • Edit automatically도 안전장치가 있습니다. 작업 디렉터리 밖과 .git·.claude·셸 설정 등 보호 경로는 여전히 승인을 요구합니다.
  • Auto는 지원 모델에서만 나타나고, 차단이 3회 연속·20회 누적되면 자동으로 승인 방식으로 되돌아갑니다.
  • Bypass permissions는 격리 환경 전용입니다. 프롬프트가 귀찮은 것이 이유라면 Auto를 쓰는 것이 맞습니다.
  • Effort는 권한과 무관한 별개 축이며 low~max 5단계, 기본값은 high입니다.
  • 실무 기본값은 Plan + high로 시작 → 계획 승인 시 Auto로 전환 → 마무리는 Edit automatically입니다.