Ch8. Plan 모드 활용

코드를 수정하지 않고 분석·계획만 하는 Plan 모드의 진입(Shift+Tab·/plan·--permission-mode)과 계획 승인 옵션, 실행 모드 전환 워크플로우를 다룹니다

핵심 요약

Plan 모드는 파일 읽기와 탐색용 셸 명령은 허용하되 소스 파일은 건드리지 않는 읽기 전용 퍼미션 모드입니다.
진입은 Shift+Tab 순환(default→acceptEdits→plan), /plan [설명], --permission-mode plan 세 가지로 합니다.
.claude/settings.json의 permissions.defaultMode: "plan"으로 기본 모드를 지정하고 --permission-mode가 세션 단위로 덮어씁니다.
계획 승인 시 auto 모드 시작·편집 자동 수락·수동 검토·계속 계획·Ultraplan 리뷰 중 선택하면 해당 퍼미션 모드로 전환됩니다.
Ctrl+G로 제안된 계획을 에디터에서 직접 수정할 수 있고, 승인 시 계획 내용으로 세션 이름이 자동 생성됩니다.

Plan 모드는 Claude Code에게 코드를 수정하지 말고 변경안을 조사·제안만 하도록 지시하는 퍼미션 모드입니다. Claude는 파일을 읽고 탐색용 셸 명령을 실행하며 계획을 작성하지만, 소스 코드는 건드리지 않습니다.

왜 Plan 모드인가

복잡한 작업에서 곧바로 코드를 손대면 방향이 틀어질 위험이 큽니다. Plan 모드로 먼저 계획을 세우고 승인한 뒤 진행하면 재작업이 줄어듭니다.

Plan 모드의 정확한 동작

Plan 모드는 "읽기 전용(Reads only)" 모드라 소스 파일을 편집하지 않습니다. 다만 Claude는 코드베이스를 파악하려고 파일을 읽고 탐색용 셸 명령을 실행합니다. 권한 프롬프트(permission prompt)는 기본(default) 모드와 똑같이 적용됩니다.

모드 전환

Shift+Tab로 순환

세션 도중 Shift+Tab을 누르면 퍼미션 모드가 순환합니다. 기본 순서는 default → acceptEdits → plan이고, 현재 모드는 상태 표시줄에 나타납니다. Plan 모드에서 Shift+Tab을 한 번 더 누르면 계획을 승인하지 않은 채 Plan 모드를 빠져나갑니다.

CLI 플래그

# Plan 모드로 시작
claude --permission-mode plan

# 헤드리스 + Plan 모드 (-p와 함께 사용 가능)
claude --permission-mode plan -p "아키텍처를 분석해줘"

--permission-mode 플래그는 해당 세션에 한해 설정(settings)의 기본 모드를 덮어씁니다.

/plan 명령으로 진입 (v2.1.72)

세션 중 /plan [description] 형태로 설명 인자를 넘기면 플랜 모드로 들어가면서 그 작업을 곧바로 시작합니다. 설명을 빼고 /plan만 입력하면 Plan 모드로 전환만 합니다.

/plan src/auth 모듈의 인증 흐름을 분석하고 개선안을 정리해줘

기본값 설정

프로젝트에서 Plan 모드를 기본으로 쓰려면 .claude/settings.json에 permissions.defaultMode를 설정합니다.

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

defaultMode의 유효 값은 default, acceptEdits, plan, auto, dontAsk, bypassPermissions입니다. --permission-mode CLI 플래그가 이 설정을 단일 세션 단위로 덮어씁니다.

/permissions로 변경

/permissions

/permissions는 allow·ask·deny 규칙을 관리하는 인터랙티브 다이얼로그를 엽니다. 스코프별 규칙 확인, 규칙 추가·삭제, 작업 디렉토리 관리, 최근 거부 항목 검토를 할 수 있습니다. (별칭: /allowed-tools)

Plan 모드에서 가능한 일

코드/문서 읽기
탐색용(읽기 전용) 셸 명령 실행으로 구조/아키텍처 분석
계획 수립 및 리뷰

Plan 모드에서는 소스 파일을 수정하지 않습니다. 권한 프롬프트는 기본 모드와 똑같이 동작하므로, 권한이 필요한 작업은 그대로 승인을 요청합니다.

계획 검토 및 승인

계획이 준비되면 Claude가 계획을 보여주고 어떻게 진행할지 묻습니다. 이 프롬프트에서 고를 수 있는 옵션은 다음과 같습니다.

승인하고 auto 모드로 시작 (Approve and start in auto mode)
승인하고 편집 자동 수락 (Approve and accept edits)
승인하고 각 편집을 수동 검토 (Approve and review each edit manually)
피드백을 주며 계속 계획 (Keep planning with feedback)
Ultraplan으로 브라우저 기반 리뷰 진행

계획을 승인하면 Plan 모드가 끝나고, 고른 승인 옵션에 해당하는 퍼미션 모드로 세션이 바뀌면서 Claude가 편집을 시작합니다. 다시 계획을 세우려면 Shift+Tab으로 Plan 모드까지 순환하거나, 다음 프롬프트 앞에 /plan을 붙입니다.

계획을 직접 편집하기

Ctrl+G를 누르면 제안된 계획을 기본 텍스트 에디터에서 열어, Claude가 진행하기 전에 직접 손볼 수 있습니다. 계획을 승인하면 (--name이나 /rename으로 이름을 이미 지정하지 않았다면) 계획 내용에 맞춰 세션 이름이 자동으로 붙습니다.

플랜 모드 UX 개선

multi-line 피드백 입력 (v2.1.69)

플랜 모드 피드백 입력에서 여러 줄을 입력할 수 있습니다. backslash+Enter(\ + Enter, 모든 터미널에서 동작) 또는 Shift+Enter(iTerm2, WezTerm, Ghostty, Kitty, Warp, Apple Terminal, Windows Terminal에서 기본 지원)로 줄바꿈합니다.

숫자 키 동작 변경 (v2.1.72)

플랜 모드에서 숫자 키가 메뉴 선택 대신 텍스트 입력으로 동작합니다. 피드백을 작성할 때 숫자가 포함된 내용을 자연스럽게 입력할 수 있습니다.

컨텍스트 compaction 후 모드 유지 (v2.1.47)

예전에는 컨텍스트 compaction이 일어나면 플랜 모드가 풀렸지만, 이제는 compaction 이후에도 플랜 모드가 그대로 유지됩니다.

VS Code 플랜 프리뷰 개선 (v2.1.47)

플랜이 자동 업데이트됩니다
리뷰 준비가 완료된 시점에서만 코멘트를 달 수 있습니다
플랜 거부 시에도 프리뷰가 유지되어 참고할 수 있습니다

"clear context" 옵션 기본 숨김 (v2.1.81)

Plan 모드의 계획 승인 화면에서 "clear context" 옵션이 기본으로 숨겨집니다. 불필요하게 컨텍스트를 초기화하는 일을 막아 플랜 워크플로우가 더 안정적으로 돌아갑니다. 이 옵션을 다시 보이게 하려면 설정에서 showClearContextOnPlanAccept를 true로 지정합니다 (기본값 false).

{
  "showClearContextOnPlanAccept": true
}

이 옵션을 켜면 각 승인 옵션마다 진행하기 전에 계획 컨텍스트를 비울지 함께 물어봅니다.

퍼미션 모드 선택 (Plan 모드 포함): https://code.claude.com/docs/en/permission-modes (영어)
settings.json에서 기본 모드 설정: https://code.claude.com/docs/en/settings (영어)
/permissions·/plan 명령: https://code.claude.com/docs/en/commands (영어)
인터랙티브 모드 단축키 (Shift+Tab 등): https://code.claude.com/docs/en/interactive-mode (영어)