Claude Code Plan Mode는 AI가 코드를 실행하기 전에 "무엇을 어떤 순서로 할 것인지" 단계별 계획을 먼저 출력하고, 사용자가 검토·승인한 뒤에만 실행하는 작업 방식입니다. /plan 명령으로 진입하면 Claude는 파일을 읽고 전략을 수립한 뒤 계획을 텍스트로 제시합니다. 파일 하나도 수정하지 않은 상태에서 계획 전체를 확인할 수 있고, 수정 요청·전면 취소·바로 승인 중 하나를 선택할 수 있습니다. 대규모 리팩토링, DB 마이그레이션, 인프라 변경처럼 실수 시 되돌리기 어려운 작업에서 특히 유용합니다. Claude Code 완전 가이드에서 전체 기능 맥락을 파악한 뒤 이 가이드를 보면 더 효과적입니다.
Plan Mode란?
Plan Mode는 Claude Code의 "검토 후 실행" 모드입니다. 일반 모드에서는 Claude가 생각과 실행을 번갈아 가며 즉시 파일을 수정합니다. Plan Mode에서는 이 두 단계가 분리됩니다.
계획 단계: Claude는 관련 파일을 읽고 코드베이스를 분석한 뒤, 변경할 파일 목록·각 단계의 이유·실행할 명령어·잠재적 위험 요소를 포함한 계획서를 출력합니다. 이 시점에서는 아무 파일도 수정되지 않습니다.
승인 게이트: 계획서를 검토한 뒤 사용자가 결정을 내립니다. 승인, 수정 요청, 전면 취소 중 하나입니다.
실행 단계: 승인 후에만 Claude가 계획에 따라 파일을 수정하고 명령을 실행합니다.
이 구조는 "측정 두 번, 절단 한 번" 원칙을 AI 코딩에 적용한 것입니다. 잘못된 방향으로 20분 실행한 뒤 되돌리는 비용을 계획 검토 1~2분으로 대체합니다.
더 많은 사용 패턴은 Claude Code Plan Mode 영어 가이드에서도 확인할 수 있습니다.
활성화 방법 (/plan 명령어 사용법)
Plan Mode를 진입하는 방법은 두 가지입니다.
슬래시 명령어: 메시지 앞에 /plan을 붙입니다.
/plan auth 모듈을 NextAuth v5로 마이그레이션해줘. 현재 /lib/auth.ts에 커스텀 JWT 구현이 있어.
키보드 단축키: 메시지를 전송하기 전에 Shift+Tab을 누릅니다. 입력창에 [Plan Mode]가 표시되면 활성화된 것입니다.
두 방법 모두 동일하게 동작합니다. /plan 명령어는 CLAUDE.md 지시사항이나 팀 내 작업 가이드에 패턴으로 기록하기 편리하고, Shift+Tab은 일회성 대화에서 빠르게 전환할 때 유용합니다.
Plan Mode를 종료하고 일반 모드로 돌아가려면 Shift+Tab을 다시 누르거나, /plan 없이 일반 메시지를 전송하면 됩니다.
한 가지 주의사항: --dangerously-skip-permissions 플래그는 권한 검토 전체를 건너뜁니다. 이 플래그를 쓰면 Plan Mode 포함 모든 승인 단계가 우회됩니다. 자동화 파이프라인이 아닌 일반 개발 작업에서는 사용하지 않는 것을 권장합니다.
작동 원리
Plan Mode에서 Claude가 내부적으로 거치는 단계는 다음과 같습니다.
1단계 — 코드베이스 분석: Claude는 관련 파일을 읽고 현재 구조를 파악합니다. 파일 읽기는 이 단계에서 발생하며 토큰 비용이 발생하지만, 쓰기나 명령 실행은 없습니다.
2단계 — 계획서 작성: 분석 결과를 바탕으로 Claude가 계획서를 출력합니다. 전형적인 계획서에는 다음 항목이 포함됩니다.
## 계획: NextAuth v5 마이그레이션
### 현재 상황 파악
/lib/auth.ts에 커스텀 JWT 핸들러가 있고, /middleware.ts에서 이를 참조함.
NextAuth v5는 config 구조와 Auth() 호출 방식이 달라 전면 교체 필요.
### 먼저 읽을 파일
- /lib/auth.ts
- /middleware.ts
- /app/api/auth/ (전체)
- /types/next-auth.d.ts
### 변경 계획
1. next-auth@5 설치, jose 제거 (더 이상 불필요)
2. 루트에 /auth.ts 생성 (NextAuth v5 config 포함)
3. /middleware.ts를 NextAuth v5의 auth()로 재작성
4. 모든 /lib/auth 임포트를 /auth로 변경
5. /types/next-auth.d.ts 세션 타입 선언 업데이트
6. /lib/auth.ts 삭제
### 실행할 명령어
- npm install next-auth@5
- npm run typecheck
### 확인 필요 사항
- getServerSession()을 직접 호출하는 서버 액션이 있는지 검색 예정
이 계획을 승인하시겠습니까?
3단계 — 사용자 결정: 계획서를 보고 세 가지 중 하나를 선택합니다.
- 승인:
y또는 "좋아요", "진행해줘" 등 긍정 응답 - 수정 요청: 변경할 내용을 구체적으로 설명
- 거부 후 재지시: 태스크 자체를 다시 설명
4단계 — 실행: 승인 이후에만 파일 쓰기와 명령 실행이 시작됩니다.
실전 사용 패턴 5가지
1. 대규모 리팩토링
함수명 변경, 공유 타입 수정, 모듈 이동처럼 수십 개 파일에 영향을 주는 작업에 Plan Mode가 가장 효과적입니다. 계획 단계에서 Claude가 어떤 파일을 수정할지 목록을 출력하므로, 예상치 못한 파일이 포함되어 있거나 누락된 파일이 있는지 즉시 확인할 수 있습니다.
/plan UserProfile 컴포넌트를 전체 코드베이스에서 ProfileCard로 이름 바꿔줘. 타입 정의도 포함해서.
2. 데이터베이스 마이그레이션
스키마 변경, 데이터 변환, 롤백 불가 작업은 반드시 Plan Mode로 진입하세요. 마이그레이션 파일이 어떤 순서로 생성되고 어떤 컬럼/테이블이 영향받는지 사전에 검토할 수 있습니다.
/plan users 테이블에 subscription_tier 컬럼 추가하고, 기존 is_premium boolean 데이터를 마이그레이션해줘. Prisma 스키마와 마이그레이션 파일 모두 포함.
3. 크로스-레포·멀티 서비스 변경
API 인터페이스가 바뀌거나 공유 라이브러리가 업데이트될 때, 여러 서비스에 걸친 변경이 필요합니다. Plan Mode로 각 서비스별 변경 범위를 먼저 파악하고 순서를 검토합니다.
/plan payments 서비스의 charge 함수 시그니처가 바뀌었어. api-gateway, billing-worker, admin-dashboard 세 서비스 모두 업데이트해줘.
4. 인프라·설정 변경
환경 변수 리네이밍, CI/CD 파이프라인 수정, Docker 설정 변경은 실수 시 전체 배포가 깨집니다. 계획서에서 변경될 파일과 적용 순서를 확인한 뒤 실행합니다.
/plan REACT_APP_ 접두사 환경변수를 모두 NEXT_PUBLIC_로 마이그레이션해줘. .env.example, vercel.json, CI 설정 모두 포함.
5. 멀티스텝 테스트 사이클
테스트 실패 → 코드 수정 → 재실행의 루프를 여러 단계로 나눠야 할 때, Plan Mode로 전체 플로를 먼저 합의하면 중간에 방향이 틀어지는 것을 막을 수 있습니다.
/plan 현재 실패 중인 통합 테스트 12개를 분석하고 원인별로 그룹화한 다음, 각 그룹을 순서대로 수정해줘. 테스트 코드 자체는 수정하지 않고 구현만 고쳐.
Claude Code Hooks 가이드와 함께 사용하면, Plan Mode 완료 후 특정 명령을 자동 실행하는 워크플로를 구성할 수 있습니다.
계획 수정 및 취소 방법
계획서를 받은 뒤 그대로 승인하지 않아도 됩니다. 세 가지 응답 패턴이 있습니다.
부분 수정 요청: 특정 단계만 바꾸거나 추가합니다.
좋은 계획인데, 3단계 이후 npm run test:integration을 추가해줘.
그리고 /lib/auth.ts는 지우지 말고 compatibility shim으로 남겨둬.
Claude가 계획을 업데이트한 뒤 수정된 버전을 다시 제시합니다. 두 번째 승인 후 실행됩니다.
질문 후 결정: 특정 단계가 이해되지 않으면 승인 대신 질문합니다.
5단계에서 세션 타입을 어떻게 바꾸는 거야? 기존 Session 인터페이스가 깨지면 다른 곳도 영향받지 않아?
Claude가 답변한 뒤 계획을 다시 제시합니다.
전면 취소 후 재지시: 계획이 처음부터 방향이 잘못됐다면 거부하고 태스크를 다시 설명합니다.
아니야, 이 방향이 아니야. 마이그레이션을 한 번에 하지 말고, 기존 코드를 유지하면서 신규 기능만 NextAuth v5로 작성하는 점진적 접근으로 다시 계획해줘.
Claude가 처음부터 다시 계획을 수립합니다.
계획을 아예 무시하고 싶다면 Ctrl+C로 세션을 중단하거나, /clear로 컨텍스트를 비우면 됩니다.
Plan Mode vs 일반 모드 비교
| 항목 | Plan Mode | 일반 모드 |
|---|---|---|
| 파일 수정 시점 | 승인 후 | 즉시 |
| 계획 가시성 | 전체 단계 사전 확인 | 실행 중 단계별 확인 |
| 잘못된 방향 수정 | 계획 단계에서 0비용 | 실행 후 되돌리기 필요 |
| 추가 토큰 비용 | 계획 출력 200~600 토큰 | 없음 |
| 속도 | 1 왕복 추가 | 바로 실행 |
| 권장 상황 | 3개 파일 이상, 비가역 작업 | 단일 파일, 소소한 수정 |
| CLAUDE.md 자동 적용 | 가능 (지시문으로 설정) | 기본값 |
언제 Plan Mode를 선택할까? 영향받는 파일이 3개를 넘거나, 데이터베이스·환경 변수·배포 설정이 포함되거나, 처음 들어가는 낯선 코드베이스라면 Plan Mode를 기본으로 씁니다. 단일 함수 수정, 빠른 반복 루프, 탐색·분석 전용 작업은 일반 모드가 효율적입니다.
Frequently Asked Questions
Plan Mode는 어떻게 진입하나요?
Claude Code 세션에서 /plan 명령어를 메시지 앞에 붙이거나, 메시지 전송 전 Shift+Tab을 누릅니다. [Plan Mode] 표시가 나타나면 활성화된 것입니다. 계획서를 받은 뒤 y 또는 "진행해줘"로 승인하면 실행이 시작됩니다.
Plan Mode에서도 파일 읽기는 발생하나요?
네, 발생합니다. 계획 단계에서 Claude는 전략 수립을 위해 파일을 자유롭게 읽습니다. 읽기에 대한 토큰 비용은 그대로 청구됩니다. Plan Mode가 차단하는 것은 파일 쓰기와 명령 실행뿐입니다.
CLAUDE.md에 Plan Mode를 기본값으로 설정할 수 있나요?
가능합니다. CLAUDE.md에 "멀티 파일 변경이 포함된 복잡한 작업은 반드시 /plan으로 시작할 것"이라고 명시하면 됩니다. Claude가 태스크 복잡도를 판단해 적용합니다. Claude Code 한국어 가이드에서 CLAUDE.md 작성 패턴을 더 자세히 다룹니다.
계획서에서 언급되지 않은 파일을 추가하려면?
승인 응답에 직접 언급합니다. 예: "승인. 단, /lib/utils.ts도 포함해줘 — 거기 helper 함수도 업데이트가 필요해." Claude가 계획에 추가 파일을 반영한 뒤 실행합니다.
--dangerously-skip-permissions와 Plan Mode는 충돌하나요?
--dangerously-skip-permissions 플래그를 사용하면 Plan Mode를 포함한 모든 승인 게이트가 건너뛰어집니다. 이 플래그는 자동화 파이프라인 전용으로, 사람이 직접 작업하는 환경에서는 사용하지 않는 것이 원칙입니다.
계획서 중간에 마음이 바뀌었을 때 어떻게 하나요?
계획서를 받은 상태에서 거부 의사를 명확히 전달하거나 Ctrl+C로 중단합니다. 이미 실행이 시작된 뒤라면 Ctrl+C로 즉시 중단하고, git diff로 변경된 파일을 확인한 뒤 git checkout -- .으로 되돌립니다. 실행 전 계획을 검토하는 것이 이런 상황 자체를 예방하는 가장 좋은 방법입니다.
Claude Code를 처음 접한다면 Claude Code 한국어 가이드에서 기본 설치와 설정을 먼저 확인하세요. 이미 익숙하다면 Claude Code Hooks 가이드로 Plan Mode 이후 자동 실행 워크플로를 구성해보세요.
→ Claude Code Power Prompts 300 구매하기 ($29)
Plan Mode 전용 프롬프트 패턴 40개 포함 — 대규모 리팩토링, DB 마이그레이션, 크로스-레포 변경에 즉시 적용 가능한 승인 스크립트와 수정 요청 템플릿을 제공합니다.