Plan Mode Workflow

쉽게 이해하기

요리사가 복잡한 요리를 만들기 전에 레시피를 먼저 검토하고 재료를 준비하듯이, AI 코딩 에이전트도 코드를 작성하기 전에 계획을 먼저 세우는 모드가 있습니다. 이것이 Plan Mode입니다.

Claude Code에서 Shift+Tab을 누르면 Plan Mode로 전환됩니다. 이 모드에서는 AI가 실제로 파일을 수정하거나 명령어를 실행하지 않고, 오직 어떤 단계로 작업할지 계획만 보여줍니다.

왜 필요할까요?

• 복잡한 리팩토링 작업을 시작하기 전에 전체 영향 범위 파악
• 예상치 못한 파일 수정 방지
• 사용자가 검토하고 방향을 수정할 기회 제공

실제 시나리오: "모든 API 엔드포인트에 인증 미들웨어 추가해줘"라고 요청했을 때, Plan Mode는 "1) routes/index.ts 파악 2) 미들웨어 파일 생성 3) 각 라우터에 미들웨어 적용 4) 테스트 코드 업데이트"처럼 단계별 계획을 먼저 보여줍니다.

기술 심층 분석

핵심 아키텍처

Plan Mode는 에이전트 루프의 **사전 계획 단계(Pre-execution Planning)**를 분리한 것입니다:

일반 모드 (Act Mode):
사용자 요청 → [계획 + 실행] → 결과
              (내부에서 동시 진행, 사용자 개입 불가)

Plan Mode:
사용자 요청 → [계획 생성] → 사용자 검토/승인 → [실행] → 결과
              Shift+Tab 활성화    ↑ 이 단계에서 방향 수정 가능

내부 프롬프트 차이 (의사코드):

# Plan Mode 핵심 제약
SYSTEM: You are in PLANNING mode.
DO NOT execute any tools. DO NOT write any files.
Create a detailed step-by-step plan showing:
  1. What files you will read/analyze
  2. What changes you will make to each file
  3. What commands you will run
  4. Potential risks and edge cases
Wait for user approval before proceeding.

Plan Mode의 상태 전환:

[PLAN MODE - Shift+Tab 활성]
    │
    ▼
계획 생성 (도구 실행 없음)
    │
    ├─ 사용자: "좋아, 실행해" → Shift+Tab 해제 → [ACT MODE]
    ├─ 사용자: "3번 단계 수정해" → 재계획
    └─ 사용자: "취소" → /clear

성능 및 비교

Plan Mode 사용 시 원치 않는 파일 수정 사고가 약 80% 감소한다는 Claude Code 사용자 커뮤니티 보고가 있습니다.¹

장점과 한계

장점:

• 대규모 변경 전 '미리 보기' 기능
• 계획 단계에서 논리적 오류 발견 가능
• 팀 환경에서 다른 개발자에게 작업 계획 공유 가능
• 비가역적 작업(DB 마이그레이션, 파일 삭제)에서 안전망 역할

한계:

• 계획과 실제 실행이 다를 수 있음 (실행 중 새로운 파일 발견 등)
• 단순 작업에는 불필요한 오버헤드
• 매우 복잡한 작업은 계획 자체가 너무 길어질 수 있음

실무 적용 가이드

Plan Mode를 반드시 사용해야 하는 상황:

✅ 5개 이상의 파일을 동시에 수정하는 경우
✅ 데이터베이스 스키마 변경이 포함된 경우
✅ API 인터페이스 변경 (Breaking change)
✅ 빌드 시스템, CI/CD 설정 수정
✅ 처음 작업하는 낯선 코드베이스

Plan Mode가 불필요한 상황:

❌ 단일 파일의 작은 버그 수정
❌ 코드 포맷팅, 주석 추가
❌ 반복적인 간단한 작업