Claude Code Plan Mode는 Claude가 프로젝트 파일을 읽고 소스를 수정하지 않은 채 계획을 제안하도록 하는 권한 모드입니다. 그 계획을 검토한 뒤 구현할지 결정합니다. bypass permissions를 사용할 수 있는 대화형 터미널 세션을 제외하면 편집은 승인할 때까지 차단된 상태로 유지되며, 그 세션에서는 plan mode의 차단이 적용되지 않습니다. 아래 예시 프롬프트는 파일, 각 파일을 바꾸는 이유, 순서, 확인 방법을 요청합니다.
예를 들어 할 일 목록에 마감일을 추가하려면 화면만 바꾸면 될까요? 날짜를 저장하는 곳과 날짜를 표시하는 방식도 살펴봐야 할 수 있습니다. 이런 작업에서 Plan Mode를 쓰면, Claude가 코드를 고치기 전에 고려한 범위를 확인할 수 있습니다.
언제 쓰면 좋을까요?
여러 파일을 함께 수정해야 하거나, 처음 보는 프로젝트여서 구조를 파악해야 할 때 유용합니다. 구현 방법이 두 가지 이상이라 먼저 장단점을 비교하고 싶을 때도 쓸 수 있습니다.
반대로 버튼 문구의 오타처럼 바꿀 내용과 위치가 분명한 작업은 곧바로 수정을 요청해도 됩니다. 모든 작업에 계획 단계가 필요한 것은 아닙니다.
1. Plan Mode로 시작하기
터미널에서 프로젝트 폴더로 이동한 뒤 다음 명령으로 Claude Code를 실행합니다.
claude --permission-mode plan이미 Claude Code 세션에 있다면 Shift+Tab으로 권한 모드를 순환해 상태 표시줄에 plan mode on이 나올 때까지 누릅니다. 거기서 멈춥니다. 한 번 더 누르면 계획을 승인하지 않은 채 plan mode에서 나갑니다. 프롬프트에서는 /plan으로도 plan mode에 들어갈 수 있으며, 뒤에 설명을 붙일 수 있습니다. 예를 들어 /plan fix the auth bug입니다.
2. 원하는 결과와 지켜야 할 범위를 알려주기
아래는 할 일 관리 앱에 마감일을 추가한다고 가정한 요청입니다. 그대로 사용하거나 자신의 작업에 맞게 바꿔 보세요.
할 일 목록에 마감일 기능을 추가하고 싶습니다.
아직 파일을 수정하지 말고, 현재 코드를 살펴본 뒤 계획을 세워 주세요.
원하는 결과:
- 각 할 일에 마감일을 입력하고 목록에서 확인할 수 있어야 합니다.
- 날짜를 입력하지 않은 기존 할 일도 정상적으로 표시되어야 합니다.
로그인과 목록의 전체 디자인은 그대로 둡니다.
계획에 포함할 것:
1. 수정할 파일과 각 파일을 수정해야 하는 이유
2. 구현할 순서
3. 완료 후 실행할 테스트와 확인할 화면
날짜 표시 형식을 정해야 한다면 구현 전에 질문해 주세요.“마감일을 넣어 줘”라는 짧은 요청에 결과와 범위를 더한 예시입니다. 특히 기존 할 일도 정상적으로 보여야 한다는 조건을 적으면, 새 기능뿐 아니라 기존 동작을 유지할 방법도 계획에 포함하도록 요청할 수 있습니다.
3. 계획을 읽고, 필요한 부분을 고친 뒤 승인하기
Claude가 계획을 제안하면 다음 세 가지를 확인하세요.
- 수정 범위: 마감일과 관계없는 로그인 기능이나 전체 디자인까지 바꾸려고 하지는 않나요?
- 빠진 경우: 날짜가 없는 할 일도 처리하나요? 저장한 날짜를 다시 열었을 때 제대로 보여줄 방법이 있나요?
- 확인 방법: 구현 후 어떤 테스트를 실행하고, 어떤 화면을 확인할지 적혀 있나요?
부족한 부분이 있으면 바로 승인하지 말고 “날짜가 없는 기존 항목을 처리하는 방법도 계획에 넣어 줘”처럼 보완을 요청하세요. 계획을 더 다듬으려면 승인 화면에서 No, keep planning을 선택합니다. Ctrl+G를 눌러 제안된 계획을 기본 텍스트 편집기에서 열고, 계속하기 전에 수정합니다.
계획이 적절하면 구현을 어떻게 시작할지 선택합니다. Yes, manually approve edits는 계획을 승인하고 각 편집을 개별적으로 검토합니다. Yes, and use auto mode는 계획을 승인하고 auto mode로 시작합니다. auto mode를 사용할 수 없으면 그 항목은 Yes, auto-accept edits라고 표시됩니다. bypass permissions가 이미 활성화되어 있으면 Yes, and switch to BYPASS PERMISSIONS (no further prompts) for this session이라고 표시됩니다. 승인하면 plan mode에서 나가며, 세션은 그 항목이 설명하는 권한 모드로 전환됩니다. 구현이 끝난 뒤에는 실제 변경 내용과 테스트 결과를 확인하세요. 계획을 잘 세웠다는 사실만으로 코드가 올바르게 동작하는 것은 아닙니다.
Plan Mode에서는 저장소를 살펴보는 명령을 여전히 실행할 수 있습니다. 읽기 전용 집합 밖의 명령은 승인을 물을 수 있거나, 계획 중에 auto mode를 사용할 수 있을 때 분류기의 검토를 받을 수 있습니다. Claude는 계획을 세우는 동안 소스를 수정하지 않습니다. bypass permissions를 사용할 수 있는 대화형 터미널 세션을 제외하면 편집은 승인할 때까지 차단된 상태로 유지되며, 그 세션에서는 plan mode의 차단이 적용되지 않습니다.