Claude Code plan 모드 사용법: 들어가는 법 3가지와 건너뛸 기준

Claude Code 2.1.283에서 claude --help를 열고 plan을 찾아봤습니다. 나오는 곳은 --permission-mode 옵션의 선택지 하나뿐이더라고요.

/plan도, 받은 계획을 편집기에서 고치는 Ctrl+G도 도움말에는 없습니다. plan 모드에서 정작 자주 쓰게 되는 조작은 대부분 세션 안에 있는 셈이에요.

그보다 더 자주 고민되는 건 언제 쓰느냐입니다. 제 기준은 이렇습니다. 바뀔 코드를 한 문장으로 설명할 수 있으면 계획 없이 바로 시키고, 접근이 불확실하거나 여러 파일을 고치거나 낯선 코드라면 plan 모드로 계획부터 받습니다.

그리고 계획 승인은 곧 실행 시작이라, 계획만 받아 두고 싶을 때는 승인하지 말고 Shift+Tab으로 나와야 합니다.

2026년 9월 27일 공식 문서(모범 사례, 권한 모드, 자주 쓰는 작업 흐름, 모델 설정, 설정 레퍼런스, 명령 목록) 기준입니다. 명령줄 부분은 Ubuntu 24.04 · Claude Code 2.1.283 테스트 환경에서 직접 확인했고, 대화형 화면(Shift+Tab, 승인 메뉴, Ctrl+G)은 공식 문서와 공개 보고를 근거로 적었습니다.

10월 12일에는 Windows 11 · PowerShell 5.1 · Claude Code 2.1.296에서 plan 모드가 편집을 막는지, defaultMode, opusplan의 모델 전환을 다시 확인했습니다.

모드마다 무엇을 묻지 않고 하는지는 권한 모드 고르기: 수동·plan·auto·dontAsk는 언제 쓰나에서 따로 정리했습니다.

계획을 건너뛰어도 되는 작업

변수 이름 하나 바꾸는데 plan 모드로 들어가면, Claude는 파일을 읽고 계획서를 쓰고 승인을 기다립니다. 바로 시켰으면 몇 초면 끝났을 일이죠. plan 모드는 도움이 되지만 그만큼 부담도 더하기 때문에, 저는 계획을 세울지를 작업 크기가 아니라 아래 기준으로 고릅니다.

상황	계획	이유
접근 방법이 불확실	세움	틀려도 버리는 게 계획 한 장
여러 파일을 고침	세움	파일 목록이 먼저 보여야 빠진 곳이 보임
고칠 코드가 낯섦	세움	계획이 곧 그 코드를 읽은 보고
diff를 한 문장으로 설명 가능	건너뜀	지시를 되풀이하는 데 그침

위 세 경우는 계획이 가장 도움이 되는 경우일 뿐, 그 밖에서 쓸모없다는 뜻은 아닙니다. 오타 수정·로그 한 줄 추가·변수 이름 바꾸기도 작은 작업의 예시이지 그 셋만 해당한다는 뜻이 아니고요.

항상 계획부터 받으면 안전하지 않냐고 물을 수도 있습니다. 하지만 계획 단계도 모델을 돌리고 컨텍스트를 채우니 공짜가 아니에요.

계획 대신 일단 시도해 보고 안 되면 되감는 방법도 있는데, 어느 쪽이 싼지는 되돌리기 비용에 달려 있습니다. 되감기가 무엇을 복원하고 무엇을 못 하는지는 체크포인트와 되감기가 실제로 되돌리는 것에 있습니다.

들어가는 세 가지 방법

세 방법은 계획을 받는 범위가 다릅니다.

방법	범위	언제
Shift+Tab	다시 누르거나 승인할 때까지	한동안 계획만 할 때
/plan <할 일>	그 프롬프트부터 바로	한 번만 계획을 받을 때
claude --permission-mode plan	세션 처음부터	시작부터 훑을 때

/plan fix the auth bug처럼 설명을 붙이면 plan 모드로 들어가 그 작업부터 시작합니다. plan 모드가 켜져 있는 동안은 상태 표시줄에 ⏸ plan mode on이 보여요.

세 번째 방법만 명령줄 도움말에서 볼 수 있습니다. 도입에서 말한 2.1.283의 claude --help 해당 부분입니다.

  --permission-mode <mode>              Permission mode to use for the session
                                        (choices: "acceptEdits", "auto",
                                        "bypassPermissions", "manual",
                                        "dontAsk", "plan")

Windows의 2.1.296에서 다시 열어 봐도 선택지는 글자까지 같았습니다. /plan이나 Ctrl+G처럼 세션 안에서 쓰는 조작은 --help에 없으니, 도움말만 보고 기능을 다 봤다고 여기지 마세요.

프로젝트를 열 때마다 plan으로 시작하려면 .claude/settings.json의 permissions.defaultMode를 "plan"으로 둡니다. Windows에서 이 값을 넣고 플래그 없이 claude -p로 “readme.txt에 한 줄 추가해 줘”를 시켜 보니, plan으로 시작해서 파일이 그대로였어요. 다만 VS Code 확장이 여는 대화는 시작 모드를 프로젝트 설정에서 읽지 않아서, VS Code 사용자 설정의 claudeCode.initialPermissionMode를 plan으로 둬야 합니다.

설정 파일 사이에서 어느 값이 이기는지는 설정 파일 우선순위: settings.json 네 곳 중 어디에 둘까에 있습니다.

탐색에서 커밋까지

Claude가 곧바로 코딩에 들어가면 엉뚱한 문제를 푸는 코드가 나올 수 있습니다. 조사와 계획을 실행에서 떼어 놓는 게 plan 모드의 쓰임이고, 흐름은 탐색 → 계획 → 실행 → 커밋으로 갑니다.

1. 탐색: 읽고 질문에 답하게 하기

plan 모드에서 Claude는 파일을 읽고 질문에 답하며 소스는 고치지 않습니다. 예를 들어 “인증 폴더를 읽고 세션과 로그인을 어떻게 처리하는지 파악해 줘. 비밀값 환경 변수를 어떻게 관리하는지도 봐 줘”처럼 시키면 됩니다.

대놓고 고치라고 해도 마찬가지였습니다. Windows에서 claude -p --permission-mode plan으로 파일 한 줄 추가를 시키니, “계획 모드라서 아직 수정하지 않았다”며 계획만 내놓고 파일은 그대로 두더라고요.

-p로 plan을 돌렸을 때는 승인하는 단계가 없었다는 것도 알아 두세요. 계획은 %USERPROFILE%\.claude\plans\ 아래에 .md 파일로 남고, 실행하려면 모드를 바꿔 다시 시켜야 합니다.

예외가 하나 있습니다. bypass permissions를 쓸 수 있는 대화형 터미널 세션에서는 plan 모드의 편집 차단이 강제되지 않습니다.

승인하지 않았는데 소스 파일이 고쳐진다면, bypass를 켜거나 --allow-dangerously-skip-permissions로 순환에 넣어 시작한 세션이 아닌지 먼저 보세요. 조건과 그 조건에서 무엇이 통하는지는 권한 모드 글의 plan 절에 정리했습니다.

2. 계획: 바뀔 파일과 흐름을 묻기

“Google OAuth를 붙이려 해. 어느 파일이 바뀌어야 하고 세션 흐름은 어떻게 돼? 계획을 만들어 줘”처럼 바뀔 파일과 흐름을 함께 묻습니다.

계획이 충분히 자세한지는 분량이 아니라 이 둘이 적혀 있느냐로 보면 돼요.

받은 계획은 승인 아니면 거절이 아닙니다. 승인 메뉴에는 세 항목(auto로 시작, 편집을 하나씩 승인, 계획 더 다듬기)이 있고, No, keep planning을 고르면 plan에 남아 무엇을 바꿀지 말하게 됩니다. auto를 쓸 수 없는 세션에서는 첫 항목 문구가 달라집니다.

계획을 손으로 고치는 편이 빠를 때도 있습니다. Ctrl+G를 누르면 제안된 계획이 기본 편집기에서 열려, Claude가 진행하기 전에 직접 고칠 수 있어요. 방향은 맞는데 한 단계가 빠졌거나 범위가 넓을 때는, 대화로 다시 설명하는 것보다 그 줄을 지우는 편이 짧습니다.

3. 승인하고 실행하기

계획을 승인하면 plan 모드에서 나와 고른 승인 항목이 말하는 권한 모드로 바뀌고, Claude가 계획과 맞대 가며 코드를 고치기 시작합니다. 그러니 승인은 “계획이 좋다”는 표시가 아니라 실행 개시 신호예요.

오늘은 계획만 받고 멈추려면 승인하지 말고 Shift+Tab으로 나오세요. 계획을 파일로 저장해 두면 나중에 다시 맞대 볼 수 있습니다.

승인할 때 대화를 비우는 방법도 있습니다. 설정에서 showClearContextOnPlanAccept를 켜면 승인 메뉴 맨 앞에 Yes, clear context and … 항목이 생기고, 고르면 대화 컨텍스트를 비운 뒤 계획만 들고 구현을 시작합니다. 라벨 뒷부분에는 이어서 쓸 권한 모드와 계획에 쓴 컨텍스트 양이 보여요.

탐색에서 파일을 잔뜩 읽었다면 그 기록을 실행까지 끌고 갈 이유가 없으니, 저라면 이 옵션을 켜 두겠습니다. 컨텍스트가 왜 실행 품질에 영향을 주는지는 컨텍스트가 차면 생기는 일에 있습니다.

계획을 수락하면 세션에 계획에서 딴 제목도 붙습니다(이미 이름을 지었으면 그대로).

4. 계획과 맞대 보고 커밋하기

Claude는 일이 다 된 것처럼 보일 때 멈춥니다. 돌릴 수 있는 검사가 없으면 “다 된 것 같다”가 유일한 신호라서 사람이 검증 루프가 되죠. 그래서 테스트, 빌드 종료 코드, 린터처럼 Claude가 읽을 수 있는 검사를 주고, 성공했다고 말하는 대신 테스트 출력·돌린 명령과 결과·화면 캡처 같은 증거를 보여 달라고 하세요.

정확성 점검에는 번들 /code-review 스킬을 쓰고, 계획과 맞대 보려면 검토 프롬프트를 직접 씁니다. 아래는 공식 문서의 예시를 그대로 옮긴 것입니다.

Use a subagent to review the rate limiter diff against PLAN.md. Check that
every requirement is implemented, the listed edge cases have tests, and
nothing outside the task's scope changed. Report gaps, not style preferences.

요구사항이 모두 구현됐는지, 적힌 예외 경우에 테스트가 있는지, 작업 범위 밖이 바뀌지 않았는지를 보는 게 계획 대조입니다. 빈틈을 찾으라는 검토자는 작업이 멀쩡해도 보통 무언가를 보고하니, 정확성이나 요구사항에 영향을 주는 빈틈만 표시하게 하고 나머지는 선택 사항으로 둡니다.

검토를 별도 컨텍스트에서 돌리는 이유는 서브에이전트로 조사와 검토를 분리하기에 있습니다. 검토가 끝나면 설명이 담긴 메시지로 커밋하고 PR을 열어 달라고 하면 됩니다.

opusplan은 세션에서 확인하기

opusplan은 plan 모드에서는 복잡한 추론과 설계 판단을 위해 opus를, 실행에서는 코드 생성을 위해 자동으로 sonnet을 쓰는 특수 모델 설정입니다. 계획에는 Opus의 추론, 실행에는 Sonnet의 효율을 짝지은 거예요.

단계	모델	컨텍스트 창	바꾸는 환경 변수
plan 모드	opus	opus 설정과 같음	ANTHROPIC_DEFAULT_OPUS_MODEL
실행	sonnet	sonnet 설정과 같음	ANTHROPIC_DEFAULT_SONNET_MODEL

opus와 sonnet이 기본으로 100만 토큰 창을 쓰는 모델로 풀리면(지금 Anthropic API의 모델이 그렇습니다) 두 단계 모두 그 창으로 돕니다. 그렇지 않은 환경에서 두 단계에 100만 창을 쓰려면 opusplan[1m]으로 지정하고, /model로 지정하는 것은 v2.1.265 이상에서 됩니다(그 전에는 --model이나 model 설정).

그런데 이 전환이 기대대로 안 됐다는 보고가 최근에도 있습니다(아래 공개 사례 절). 허용 모델 목록(availableModels)이 최신 Opus를 빼 두었을 때의 대체 규칙도 제공자마다 달라요.

그래서 opusplan을 쓴다면 지금 어느 모델인지를 문서가 아니라 세션에서 확인하길 권합니다.

상태 표시줄이나 /model로 지금 모델을 보고, 조직이 허용 모델을 제한했는지도 확인하세요. 문서와 다르면 그 상태를 기록해 두면 좋습니다.

스크립트로 확인하려면 --output-format json의 modelUsage를 보면 됩니다. Windows의 2.1.296에서 --model opusplan으로 짧은 질문을 두 번 돌려 봤어요.

시작 모드	modelUsage에 찍힌 모델
--permission-mode plan	claude-opus-5-5
플래그 없음	claude-sonnet-5-5

이 버전·환경에서는 문서대로 바뀌었습니다. 다만 아래 보고처럼 버전과 컨텍스트 크기에 따라 달랐다는 기록이 있으니, 버전을 올린 뒤에는 한 번씩 다시 보는 게 안전합니다.

다른 사람들이 겪은 문제

opusplan 두 건은 확인한 날 기준으로 열려 있었고, 나머지 두 건은 닫힌 보고입니다.

opusplan이 기대대로 바뀌지 않음

• rmclaughlin-nelnet(2026-09-09, #93177)은 2.1.236 · macOS에서 사용자 설정에 "model": "opusplan"을 두었는데, 계획을 승인하고 나온 뒤에도 실행이 계속 Opus였다고 했습니다. 세션 기록(JSONL)의 모든 턴이 claude-opus-5였고, 이틀간 다른 세션 다섯 개에서도 claude-sonnet-5가 없었다고 적었습니다.
• andrealufino(2026-09-17, #95206)는 2.1.274 · Anthropic API에서 처음에는 전환이 되다가, 컨텍스트가 약 20만 토큰을 넘자 plan 모드가 경고 없이 Sonnet에 머물렀다고 했습니다. 세션이 보고한 창 크기는 1,000,000이었고, 앞선 이슈 #65512의 재발로 봤습니다.

두 보고는 방향이 정반대라 원인을 하나로 확정할 수 없습니다. 둘 다 상태 표시줄이나 세션 기록의 모델 이름을 근거로 삼았다는 점은 같고요.

계획을 승인했는데 아무것도 바뀌지 않음

BobbyWang0120(2025-06-17, #2184)은 1.0.25 · macOS에서 계획에 “yes”로 동의한 뒤 Claude가 가끔 텍스트로만 답하며 작업을 했다고 주장했지만 실제로는 코드를 쓰지 않았다고 보고했습니다. 원인도 우회법도 적혀 있지 않은 오래된 보고예요.

가장 짧은 확인은 git status나 git diff로 실제 변경을 보는 것이고, 검사를 함께 돌리고 출력을 보여 달라고 시키면 이런 경우가 테스트·빌드 결과로 드러납니다.

Ctrl+G로 고친 계획이 반영되지 않음

mimkorn(2025-11-02, #10861)은 2.0.31 · macOS·iTerm에서 Ctrl+G로 계획을 고쳤는데, 녹색 체크로 저장 표시가 보였음에도 Claude에게는 고치기 전 계획이 전달됐다고 보고했습니다. 서로 다른 작업에서 두 번 확인했다고 했고, 원인은 적혀 있지 않은 채 닫혔습니다.

같은 일이 걱정된다면 실행이 시작된 뒤 첫 몇 단계가 고친 계획을 따르는지 보고, 어긋나면 Shift+Tab으로 plan에 돌아가 계획을 다시 받거나 고친 내용을 대화로 다시 지시하세요.

마치며

plan 모드에서 제일 헷갈리기 쉬운 건 승인 버튼의 의미입니다. “계획이 괜찮네” 정도로 눌렀는데 그 순간 실행이 시작되니까요.

그래서 저는 계획은 필요할 때만 받고, 승인은 정말 실행할 준비가 됐을 때만 누르길 권합니다. 실행이 계획을 따랐는지는 Claude의 말보다 테스트 출력과 계획 대조 검토로 확인하는 게 확실하고요.

다음에 여러 파일을 고칠 일이 생기면 /plan <할 일>로 시작해서, 받은 계획에 바뀔 파일 목록이 있는지부터 보세요. 승인 메뉴에서 어느 모드로 넘길지 고르는 기준은 권한 모드 고르기로 이어집니다.