plan mode

어떻게 동작하나

플랜 모드는 Claude가 변경을 조사하고 제안하되 실제로 적용하지 않는 권한 모드입니다. Claude는 파일을 읽고 탐색용 셸 명령을 실행할 수 있고, 계획을 작성합니다. 소스 수정은 계획을 승인하기 전까지 막혀 있습니다.

계획 모드에서 실행되는 셸 명령은 세션 설정에 따라 달라서, 읽기 전용 범위를 벗어난 명령은 승인 프롬프트가 뜰 수 있습니다. 계획이 길어질수록 압축에 걸릴 수 있는데, 플랜 모드에서 쓴 계획은 압축 후 디스크에서 다시 주입됩니다.

진입 방법

• Shift+Tab: 권한 모드를 순환합니다. 상태 표시줄에 plan mode on이 나타날 때까지 누릅니다.
• /plan: 프롬프트에서 바로 플랜 모드로 들어갑니다. 설명을 붙이면 들어가면서 바로 그 작업을 시작합니다.
• claude --permission-mode plan: 플랜 모드로 세션을 시작합니다.
• .claude/settings.json의 permissions.defaultMode를 plan으로 두면 그 프로젝트의 터미널 세션은 플랜 모드로 시작합니다.

/plan 인증 버그 수정

claude --permission-mode plan

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

계획 승인과 수정

계획이 준비되면 Claude가 진행 방식을 묻습니다. 선택지는 자동 모드로 승인(auto mode를 쓸 수 없으면 편집 자동 수락), 편집을 하나씩 직접 승인, 계속 계획하기 세 가지입니다. showClearContextOnPlanAccept가 켜져 있으면 계획 컨텍스트를 비우고 승인하는 선택지가 맨 앞에 추가됩니다. 승인하면 플랜 모드를 벗어나 선택한 모드로 바뀝니다.

승인 전에 Ctrl+G를 누르면 제안된 계획을 기본 텍스트 편집기에서 직접 고칠 수 있습니다. 승인 없이 빠져나오려면 Shift+Tab을 다시 누릅니다. 계획을 승인하면 세션에 계획 기반의 제목이 붙습니다.

이웃 기능과의 관계

Shift+Tab은 권한 모드 순환 수단이고, 플랜 모드는 그 순환 중 하나입니다. 순환은 default, acceptEdits, plan 순입니다. auto에서 시작하면 첫 Shift+Tab이 default로 갑니다. 선택 모드는 plan 뒤에 붙습니다. /plan은 같은 모드로 들어가는 바로가기입니다.

/model opusplan은 플랜 모드에서는 opus를, 실행에서는 sonnet을 쓰는 별칭이라 둘이 잘 맞습니다. 비용 문서도 복잡한 작업은 플랜 모드를 먼저 쓰라고 권합니다. 방향이 틀렸을 때 생기는 재작업을 줄이기 위해서입니다.

실제 예시

/plan 세션 쿠키 인증을 JWT로 교체하는 계획을 세워줘

계획 화면에서 Ctrl+G

Shift+Tab (계획 승인 없이)

흔한 실수와 쓰지 말아야 할 때

• 간단한 수정에도 항상 플랜 모드를 쓰는 것. 한 줄 고치는 일에는 승인 절차가 오히려 느립니다. 여러 파일, 설계 선택이 있는 일에 씁니다.
• 승인하면 플랜 모드가 유지된다고 생각하는 것. 승인하면 그 모드에서 벗어나 선택한 권한 모드로 바뀝니다.
• 플랜 모드가 완전한 보호 장치라고 믿는 것. 소스 수정을 막을 뿐이고, 탐색용 셸 명령은 실행될 수 있습니다. 어떤 명령이 프롬프트 없이 돌지는 세션 설정에 달려 있습니다.
• 계획에 적힌 것을 검증 없이 승인하는 것. 계획은 제안입니다. 관련 파일 목록과 순서를 읽고 맞는지 확인한 뒤 승인하세요.

자주 묻는 질문