Claude Code Plan 모드 완전정리

Claude Code Plan 모드 완전정리: 코드 먼저 읽고, 계획 세우고, 그다음 실행

복잡한 리팩토링을 시작했는데 Claude가 갑자기 엉뚱한 파일을 수정하기 시작한다면? Plan 모드는 Claude에게 "아직 수정하지 마, 먼저 충분히 살펴보고 계획부터 세워"라고 지시하는 기능입니다. 읽기 전용으로 코드를 분석하고, 구현 계획을 제시한 뒤, 사용자가 승인해야만 실행에 들어갑니다. 이 글에서는 Plan 모드의 원리부터 실전 활용까지 완전 정리합니다.

Claude Code Plan 모드 완전정리

---

1. Plan 모드란?

"먼저 계획, 그다음 실행" 원칙

Plan 모드는 Claude Code의 권한 모드 중 하나로, Claude가 읽기 전용 도구만 사용하도록 제한하는 모드입니다. 파일을 수정하거나 명령어를 실행할 수 없고, 오직 코드를 읽고 분석해서 구현 계획을 세우는 것에만 집중합니다.

[Plan 모드]
  ↓ 읽기만 가능
  코드 분석 → 패턴 파악 → 의존성 확인
  ↓
  구현 계획 제시
  ↓ 사용자 승인
[일반 모드로 전환]
  ↓ 수정 가능
  계획에 따라 실행

3가지 권한 모드

Claude Code는 Shift+Tab을 눌러 3가지 권한 모드를 순환합니다.

모드	표시	설명
일반 모드	✓ ready	매번 수정 허가를 물어봄 (기본)
자동 수락 모드	⏵⏵ accept edits on	파일 수정을 자동 허가
Plan 모드	⏸ plan mode on	읽기 전용, 수정 불가

일반 모드 → (Shift+Tab) → 자동 수락 → (Shift+Tab) → Plan 모드 → (Shift+Tab) → 일반 모드

Windows에서 Shift+Tab이 작동하지 않으면 Alt+M을 사용하세요.

3가지 권한 모드

---

2. Plan 모드 진입 방법

방법 1: 키보드 단축키

Shift+Tab을 두 번 누르면 Plan 모드 진입
(일반 → 자동 수락 → Plan)

Windows: Alt+M으로 대체 가능

화면 하단에 ⏸ plan mode on이 표시됩니다.

방법 2: /plan 슬래시 커맨드

/plan

v2.1.0 이상에서 사용 가능합니다. 가장 직관적인 방법입니다.

방법 3: CLI 플래그

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

# 헤드리스 쿼리에서 Plan 모드
claude --permission-mode plan -p "인증 시스템을 분석하고 개선안을 제안해줘"

방법 4: 설정 파일에서 기본값 지정

// settings.json
{
  "permissions": {
    "defaultMode": "plan"
  }
}

현재 모드 확인

/permissions

이 명령어로 현재 어떤 권한 모드인지 확인할 수 있습니다.

Plan 모드 진입 방법

---

3. Plan 모드에서 사용 가능한 도구

읽기 전용 도구만 허용

Plan 모드에서 Claude는 코드를 분석하는 도구만 사용할 수 있습니다.

도구	기능	Plan 모드
Read	파일 내용 읽기	✅ 사용 가능
Grep	정규식으로 코드 검색	✅ 사용 가능
Glob	파일 패턴 검색	✅ 사용 가능
WebSearch	웹 검색	✅ 사용 가능
WebFetch	웹 페이지 내용 가져오기	✅ 사용 가능
AskUserQuestion	사용자에게 질문	✅ 사용 가능
Write	파일 생성	❌ 차단
Edit	파일 수정	❌ 차단
Bash	명령어 실행	❌ 차단

Plan 모드에서 수정 도구를 사용하려 하면 "이 도구는 Plan 모드에서 사용할 수 없습니다"라는 메시지가 표시됩니다.

Plan 서브에이전트

Plan 모드에서 Claude는 내부적으로 Plan 서브에이전트를 사용합니다. 이 서브에이전트는:

• 메인 대화의 모델을 상속합니다
• 읽기 전용 도구만 사용합니다
• 탐색 결과를 메인 컨텍스트에 요약해서 전달합니다
• 메인 컨텍스트를 깨끗하게 유지하면서 심층 분석을 수행합니다

Plan 모드에서 사용 가능한 도구

---

4. Plan 모드 워크플로우

4단계 프로세스

Plan 모드의 핵심은 리서치 → 계획 → 승인 → 실행의 명확한 단계 분리입니다.

1단계: 리서치 (Research)

Claude가 읽기 전용 도구로:
- 현재 코드베이스 구조 분석
- 관련 파일과 패턴 검색
- 기존 구현 방식 이해
- 필요하면 사용자에게 질문 (AskUserQuestion)

2단계: 계획 수립 (Plan)

Claude가 리서치 결과를 종합해서:
- 문제 정의
- 수정할 파일 목록
- 단계별 구현 방법
- 잠재적 위험 요소
- 대안 접근법
- 선택한 접근법의 근거

3단계: 승인 (Approve)

사용자가 계획을 검토하고:
- 그대로 승인
- 추가 질문
- 수정 요청
- 계획 거부 후 재시작

Ctrl+G를 눌러 텍스트 에디터에서 계획을 직접 편집할 수도 있습니다.

4단계: 실행 (Execute)

승인 후:
- Shift+Tab으로 일반 모드 전환
- Claude가 승인된 계획에 따라 실행
- 모든 변경이 계획을 따름

실전 예시

claude --permission-mode plan

React 17 프로젝트를 React 19로 업그레이드하는 계획을 세워줘.
기존 API는 전환 기간 동안 깨지면 안 돼.

Claude의 Plan 출력:

[계획] React 17 → 19 업그레이드

수정 대상 파일:
1. package.json - 의존성 버전 업데이트
2. src/components/*.tsx - 14개 컴포넌트 API 변경
3. src/hooks/useEffect*.ts - Strict Mode 대응
4. tsconfig.json - 타입 설정 변경
5. tests/**/*.test.tsx - 테스트 업데이트

단계별 접근:
  1단계: 의존성 업데이트 (package.json)
  2단계: React.FC 제거 → 함수 선언 전환
  3단계: useEffect 클린업 패턴 수정
  4단계: 테스트 업데이트
  5단계: Strict Mode 활성화 확인

위험 요소:
- useEffect 실행 순서 변경
- 서드파티 라이브러리 호환성
- TypeScript 타입 변경

→ 사용자가 검토 후 승인 → Shift+Tab으로 일반 모드 전환 → 실행

Plan 모드 워크플로우

---

5. Plan 모드의 안전 장치

의도하지 않은 변경을 방지하는 메커니즘

Plan 모드는 여러 겹의 안전 장치로 코드를 보호합니다.

안전 장치	설명
읽기 전용 강제	수정 도구가 "차단"됨 (권한 요청 아님)
명시적 승인 게이트	사용자가 검토하고 승인해야 실행
계획/실행 분리	계획 단계와 실행 단계가 완전히 분리됨
질문 우선	Claude가 먼저 질문으로 요구사항 확인
계획 가시성	무엇을 변경할지 사전에 전부 공개
직접 편집	Ctrl+G로 계획을 텍스트 에디터에서 수정 가능
되돌리기	실행 후 /rewind로 되돌리기 가능

일반 모드와의 비교

일반 모드:
  사용자: "인증 시스템 리팩토링해줘"
  Claude: (바로 파일 수정 시작) → 허가 팝업 → 수정 → 허가 → 수정...

Plan 모드:
  사용자: "인증 시스템 리팩토링해줘"
  Claude: (코드 분석) → (계획 제시) → 사용자 검토 → 승인 → (모드 전환) → 실행

일반 모드는 "하면서 확인"이고, Plan 모드는 "확인 후 실행"입니다.

 

Plan 모드의 안전 장치

---

6. 에이전트 팀과의 연동

팀원에게 계획 승인 요구하기

Plan 모드는 에이전트 팀과 결합하면 더 강력해집니다. 팀원이 계획을 먼저 세우고 리드의 승인을 받아야 실행할 수 있게 할 수 있습니다.

아키텍트 팀원을 만들어서 인증 모듈을 리팩토링해줘.
변경하기 전에 계획 승인을 받도록 해.

동작 흐름

[리드] → 팀원 생성 (Plan 모드 활성)
         ↓
[팀원] → 코드 분석 (읽기 전용)
         ↓
[팀원] → 계획 작성 → 리드에게 전달
         ↓
[리드] → 계획 검토 → 승인 또는 거부+피드백
         ↓
[팀원] → (승인 시) Plan 모드 해제 → 실행
         (거부 시) 피드백 반영 → 계획 수정 → 재제출

팀에서의 Plan 모드 이점

이점	설명
사전 정렬	구현 전에 리드와 방향 일치 확인
중복 방지	여러 팀원이 같은 것을 다르게 수정하는 것 방지
의사결정 기록	계획이 곧 문서화
안전망	잘못된 방향으로 구현 시작 전에 차단

에이전트 팀과의 연동

---

7. 확장 사고(Extended Thinking)와의 관계

별개이지만 함께 쓰면 강력한 두 기능

기능	Plan 모드	확장 사고
역할	권한 경계 (읽기 전용)	추론 깊이 (깊은 사고)
토글	Shift+Tab / Alt+M	Alt+T / Option+T
효과	수정 도구 차단	더 깊은 분석과 추론
독립성	서로 독립적	서로 독립적

함께 사용하기

claude --permission-mode plan

ultrathink
모놀리식 애플리케이션을 마이크로서비스로 분해하는 아키텍처를 설계해줘.

• ultrathink 키워드로 확장 사고 최대 활성화
• Plan 모드로 읽기 전용 안전 보장
• 결과: 코드를 건드리지 않으면서 가장 깊은 수준의 분석과 설계를 받을 수 있습니다

복잡한 아키텍처 결정이 필요할 때 Plan 모드 + 확장 사고 조합이 가장 효과적입니다.

 

확장 사고(Extended Thinking)와의 관계

---

8. CLI 플래그와 설정

Plan 모드 관련 CLI 플래그

# 기본: Plan 모드로 세션 시작
claude --permission-mode plan

# 헤드리스 쿼리
claude --permission-mode plan -p "분석 결과를 알려줘"

# JSON 출력과 결합
claude --permission-mode plan -p "계획을 세워줘" --output-format json

# 예산 제한과 결합
claude --permission-mode plan -p "분석해줘" --max-budget-usd 10.00

# 모델 지정과 결합
claude --permission-mode plan --model opus

# 최대 턴 수 제한
claude --permission-mode plan -p "계획" --max-turns 5

# 시스템 프롬프트 추가
claude --permission-mode plan --append-system-prompt "보안 중심으로 분석"

# 추가 디렉토리 포함
claude --permission-mode plan --add-dir ../other-project

# 상세 모드 (분석 과정 표시)
claude --permission-mode plan --verbose

설정 파일

// .claude/settings.json 또는 ~/.claude/settings.json
{
  "permissions": {
    "defaultMode": "plan"
  }
}

환경 변수

# 에이전트 팀 팀원에게 Plan 모드 강제
CLAUDE_CODE_PLAN_MODE_REQUIRED=true

CLI 플래그와 설정

---

9. 실전 활용 시나리오

시나리오 1: 프레임워크 대규모 업그레이드

claude --permission-mode plan

React 17을 React 19로 업그레이드하는 종합 계획을 세워줘.
기존 API는 전환 기간에 깨지면 안 돼.

Claude가 모든 컴포넌트와 의존성을 분석 → 단계별 마이그레이션 계획 제시 → 사용자 승인 후 실행

시나리오 2: 보안 감사 후 구현

현재 인증 시스템의 보안 취약점을 분석하고,
OAuth2로 전환하는 계획을 세워줘.
보안 고려사항도 포함해.

Plan 모드에서 안전하게 전체 인증 로직을 분석 → 취약점 목록과 수정 계획 → 승인 후 구현

시나리오 3: 레거시 코드 리팩토링

결제 처리 모듈을 새로운 에러 핸들링과
로깅 표준에 맞춰 리팩토링하는 계획을 세워줘.
현재 코드가 복잡하니 충분히 분석해줘.

복잡한 레거시 코드를 먼저 이해 → 리스크 최소화 리팩토링 계획 → 단계별 실행

시나리오 4: 낯선 코드베이스 학습

claude --permission-mode plan

이 코드베이스의 아키텍처를 분석해줘.
핵심 모듈, 데이터 흐름, 모듈 간 상호작용을 정리해줘.

코드를 수정하지 않고 안전하게 탐색 → 아키텍처 문서화 → 이해한 내용을 기반으로 작업 시작

시나리오 5: 위험한 변경 사전 검토

데이터베이스 스키마를 변경해야 하는데,
영향 범위를 먼저 분석하고 마이그레이션 계획을 세워줘.

DB 스키마를 참조하는 모든 코드를 분석 → 영향 범위 파악 → 안전한 마이그레이션 순서 결정

Plan 모드가 빛나는 순간

상황	이유
다중 파일 리팩토링	어떤 파일이 영향받는지 먼저 파악
프레임워크 업그레이드	호환성 문제를 사전에 식별
보안 관련 변경	실수 없이 신중하게 접근
DB 스키마 변경	영향 범위를 완전히 파악한 뒤 실행
낯선 코드베이스	안전하게 탐색하고 이해
팀 코드 리뷰	변경 계획을 팀과 공유 후 합의

실전 활용 시나리오

---

10. 자주 묻는 질문 (FAQ)

Q: Plan 모드에서 실수로 파일을 수정할 수 있나요?
A: 아닙니다. Plan 모드에서는 Write, Edit, Bash 도구가 완전히 차단됩니다. 권한 요청이 뜨는 게 아니라 도구 자체를 사용할 수 없습니다.

Q: Plan 모드에서 계획을 세운 뒤 어떻게 실행하나요?
A: Shift+Tab(또는 Alt+M)을 눌러 일반 모드로 전환한 뒤, Claude에게 "계획대로 실행해줘"라고 말하면 됩니다.

Q: Plan 모드에서 웹 검색도 가능한가요?
A: 네. WebSearch와 WebFetch는 읽기 전용 도구이므로 Plan 모드에서 사용 가능합니다. 라이브러리 문서나 마이그레이션 가이드를 검색할 수 있습니다.

Q: Plan 모드를 기본 모드로 설정할 수 있나요?
A: 네. settings.json에서 "defaultMode": "plan"으로 설정하면 항상 Plan 모드로 시작합니다.

Q: 에이전트 팀에서 모든 팀원을 Plan 모드로 시작하게 할 수 있나요?
A: 네. 팀원 생성 시 "계획 승인을 받도록 해"라고 지시하면, 팀원이 Plan 모드로 시작하고 리드의 승인 후에만 실행합니다.

Q: Plan 모드와 자동 수락 모드를 오가며 사용할 수 있나요?
A: 네. Shift+Tab으로 세 모드를 자유롭게 순환할 수 있습니다. 계획 단계에서는 Plan 모드, 실행 단계에서는 자동 수락 모드를 쓰면 효율적입니다.

Q: Plan 모드에서 비용이 절약되나요?
A: 읽기 전용 도구는 일반적으로 비용이 낮습니다. 또한 잘못된 실행을 방지해서 재작업 비용을 절약할 수 있습니다.

---

면책 조항: 이 글은 정보 제공 목적으로 작성되었습니다. Claude Code의 기능과 요금은 Anthropic의 정책에 따라 변경될 수 있으며, 최신 정보는 공식 문서를 확인해 주세요.