3.4플랜 모드와 실행

Claude Code에는 도구 실행을 어떻게 승인할지 결정하는 권한 모드(permission mode)가 있습니다.

모드	동작	적합한 상황
default	민감한 도구 실행마다 확인 요청	일반 작업 기본값
acceptEdits	파일 편집을 자동 승인	신뢰하는 반복 편집 작업
plan	읽기 전용 — 분석·계획만 가능, 수정·실행 불가	착수 전 조사와 설계
bypassPermissions	모든 확인 생략	격리된 샌드박스 환경 한정

모드는 세션 중 Shift+Tab으로 순환 전환하거나, 시작 시 --permission-mode plan 같은 플래그로 지정합니다. settings.json의 defaultMode로 기본값을 바꿀 수도 있습니다.

# 플랜 모드로 시작
claude --permission-mode plan

# 위험: 모든 확인 생략 — 인터넷이 차단된 컨테이너 등에서만
claude --dangerously-skip-permissions

bypassPermissions는 편리하지만 프롬프트 인젝션(prompt injection)이나 잘못된 명령이 그대로 실행되는 위험을 감수하는 것이므로, 공식 문서도 네트워크가 격리된 컨테이너 같은 안전한 환경에서만 쓰도록 권고합니다. 시험에서도 "로컬 개발기에서 bypassPermissions로 속도를 높인다" 같은 선택지는 오답으로 출제됩니다.

플랜 모드에서 Claude는 파일 읽기, 검색, 분석 같은 읽기 전용 도구만 사용할 수 있습니다. 편집·명령 실행·커밋은 차단됩니다. Claude는 조사를 마치면 계획을 제시하고, 사용자가 승인하면 그때 실행 모드로 전환되어 작업을 시작합니다.

전형적인 흐름은 다음과 같습니다.

1. 플랜 모드 진입 (Shift+Tab 또는 --permission-mode plan)
2. "이 기능을 구현하려면 어떤 변경이 필요한지 조사해줘" — Claude가 코드베이스를 읽고 분석
3. Claude가 구현 계획 제시 (수정할 파일, 접근 방법, 리스크)
4. 사용자가 계획을 검토·수정 요청 또는 승인
5. 승인 시 일반 모드로 전환되어 계획대로 실행

플랜 모드의 가치는 되돌리기 비용이 큰 작업의 방향을 실행 전에 교정할 수 있다는 데 있습니다. 대규모 리팩터링, 여러 파일에 걸친 기능 추가, 익숙하지 않은 코드베이스 파악에 특히 유용합니다. 반대로 오타 수정 같은 소소한 작업에 플랜 모드를 쓰면 승인 단계만 늘어납니다.

계획 품질을 높이는 요령은 계획 단계에서 "구현하지 말고 먼저 계획만 세워라", "대안 두 가지를 비교하라"처럼 사고를 요구하는 지시를 명확히 주는 것입니다. 좋은 계획이 나오면 그 계획을 문서(예: 이슈, 마크다운 파일)로 저장해 두고 실행 세션에서 참조하게 하는 패턴도 널리 쓰입니다.

실무에서 모드를 고르는 기준은 "이 작업이 잘못됐을 때 복구 비용"과 "작업의 불확실성"입니다.

탐색·설계 단계 → plan. 요구사항이 모호하거나 코드베이스가 낯설면 플랜 모드로 시작합니다. 읽기 전용이므로 어떤 실수도 파일을 건드리지 않습니다.

정형 반복 작업 → acceptEdits. 테스트 수정, 문자열 치환처럼 편집 내용이 예측 가능하고 git으로 쉽게 되돌릴 수 있는 작업은 편집 승인을 생략해 속도를 높입니다.

일반 작업 → default. 대부분의 개발 작업은 기본 모드에서 필요한 것만 승인하며 진행합니다. 자주 승인하는 안전한 명령은 permissions.allow에 추가해 프롬프트 횟수를 줄입니다(3.3 수업).

무인 자동화 → 격리 환경 + bypassPermissions. CI 컨테이너처럼 격리된 환경에서 무인 실행할 때만 사용합니다(3.6 수업).

// settings.json — 기본 모드 변경 예
{
  "permissions": {
    "defaultMode": "plan"
  }
}

한 세션 안에서도 단계별로 모드를 바꾸는 것이 자연스럽습니다. 플랜 모드로 계획을 승인받고, acceptEdits로 구현을 진행한 뒤, 커밋·푸시 같은 민감 작업은 default 승인 흐름으로 처리하는 조합이 대표적입니다.