Claude Code로 코드를 고치다가 갑자기 파일이 엉뚱하게 바뀐 경험, 한 번쯤 있으실 거예요. 저도 처음엔 그냥 프롬프트만 잘 쓰면 되는 줄 알았는데, 여러 파일에 걸친 작업을 시킬 때마다 결과물이 매번 달라지는 걸 보고 나서야 Plan Mode를 진지하게 들여다봤습니다. Claude Code Plan Mode는 Claude가 파일을 고치기 전에 먼저 계획만 세우게 만드는 권한 모드인데, 언제 켜고 언제 꺼야 하는지 감이 안 잡히면 오히려 작업 속도만 늦출 수 있어요. 이 글에서는 진입 방법부터 승인 흐름, 실전 판단 기준, 그리고 실제 써보면서 걸리는 버그까지 정리했습니다.
Claude Code Plan Mode란 무엇인가
공식 문서 기준으로 Claude Code의 권한 모드는 총 6가지입니다. default(읽기만 자동 승인), acceptEdits(읽기+파일 편집 자동 승인), plan, auto(백그라운드 안전 검사와 함께 전부 자동 승인), dontAsk(사전 승인된 도구만), bypassPermissions(격리된 컨테이너 전용, 전부 무승인 실행)입니다. 그중 plan 모드는 "Claude reads files, runs shell commands to explore, and writes a plan, but does not edit your source"라고 문서에 명시되어 있어요. 쉽게 말해 파일을 읽고 탐색은 하지만 실제로 뭘 고치지는 않는 상태입니다.
재밌는 건 이 정체성에 대한 시선이 하나만 있는 게 아니라는 점이에요. 공식 문서는 Plan Mode를 도구 호출 자체를 막는 권한 모드로 설명합니다. 반면 개발자 Armin Ronacher는 2025년 12월 블로그에서 다른 각도로 분석했어요. 그의 표현을 빌리면 "a plan in Claude Code is effectively a markdown file written into Claude's plans folder by Claude in plan mode"입니다. 즉 도구 수준의 하드 제약이라기보다, "읽기 전용으로 행동하라"는 반복적인 프롬프트 지시와 계획 마크다운 파일을 다루는 상태 머신에 가깝다는 주장이죠. 어느 쪽이 완전히 맞다고 단정하기는 어렵지만, 실제로 써보면 최소한 편집 도구가 막혀 있다는 체감은 확실히 있습니다.
Plan Mode 진입하는 세 가지 방법
진입 방법은 세 가지예요.
- CLI 세션 중
Shift+Tab을 반복 입력합니다. 기본 순환 순서는default → acceptEdits → plan이고, 현재 모드는 상태 표시줄에 나타납니다. - 프롬프트 앞에
/plan을 붙입니다. 해당 턴 한 번만 Plan Mode로 들어가요. - 시작 시
claude --permission-mode plan플래그를 씁니다.
나가고 싶으면 Shift+Tab을 한 번 더 누르면 그만입니다. VS Code는 프롬프트 박스 하단 모드 표시기를 클릭하고, JetBrains 플러그인은 터미널에서 CLI와 동일하게 Shift+Tab을 씁니다. 프로젝트 전체에서 항상 Plan Mode로 시작하게 강제하고 싶으면 .claude/settings.json에 "permissions": { "defaultMode": "plan" }을 추가하면 됩니다.
계획 승인부터 실행 전환까지
계획이 다 만들어지면 Claude가 계획 내용을 보여주고 다음 중 하나를 고르라고 물어요.
- auto 모드로 승인 후 바로 시작
- accept-edits 모드로 승인
- 편집을 하나씩 수동으로 검토하며 승인
- 피드백을 주고 계획을 계속 다듬기
- Ultraplan으로 넘겨서 브라우저 기반 검토로 정교화
승인하는 순간 Plan Mode는 종료되고, 고른 권한 모드로 세션이 전환되면서 실제 편집이 시작됩니다. 계획 내용을 텍스트로 직접 손보고 싶으면 Ctrl+G로 기본 에디터에서 열어 수정할 수도 있어요.
Plan Mode, 언제 진짜 효과가 있을까
"diff를 한 문장으로 설명할 수 있으면 Plan Mode를 건너뛰어라"는 게 공식 문서와 커뮤니티에서 공통으로 나오는 실전 기준입니다. 오타 수정, 로그 한 줄 추가, 변수 이름 바꾸기처럼 범위가 뻔한 작업에는 계획 단계 자체가 오버헤드예요. 반대로 여러 파일을 건드리거나, 익숙하지 않은 코드 영역이거나, 접근 방식 자체가 확실하지 않을 때는 얘기가 달라집니다.
Claude Code 팀의 Boris Cherny는 Hacker News에서 이렇게 말했어요. "Use Plan mode (press shift-tab 2x). Go back and forth with Claude until you like the plan before you let Claude execute. This easily 2-3x's results for harder tasks." 어려운 작업일수록 계획을 한 번에 승인하지 말고 마음에 들 때까지 주고받으라는 조언인데, 저도 큰 리팩터링 작업에서는 계획 단계에서 두세 번 더 물어보고 나서야 실행 버튼을 누르는 편입니다.
규모가 큰 작업은 Ultraplan으로
/ultraplan 명령을 쓰면 로컬 CLI의 계획 작업을 Claude Code on the web 세션으로 넘길 수 있어요. 여러 에이전트가 병렬로 계획을 짜기 때문에, 표준 모드로 4분 넘게 걸리던 계획 수립이 약 1분 만에 끝난다고 소개됩니다. 계획이 준비되면 브라우저에서 특정 구간에 인라인 댓글을 달아 수정 요청을 할 수 있고, 마음에 들면 브라우저에서 바로 실행할지 로컬 터미널로 돌려보낼지 고를 수 있습니다. 다만 Git 저장소, Pro나 Max 구독, GitHub 연동 저장소가 필요해요. GitLab이나 Bitbucket, 로컬 전용 저장소는 아직 지원되지 않습니다.
실전에서 마주치는 버그도 알아두기
Plan Mode를 쓰다 보면 최근에 고쳐진 버그들도 눈에 띕니다. v2.1.198(2026-07-01)에서는 plan 모드에서 상태를 변경하는 브라우저 도구 호출에 프롬프트가 뜨지 않던 문제가 수정됐고, v2.1.172(2026-06-10)에서는 세션이 plan 모드로 시작될 때 읽기 전용 호출이 자동 승인되지 않던 문제가 고쳐졌어요.
근데 아직 공식적으로 해결됐다고 보기 어려운 이슈도 있습니다. Hacker News 댓글에서 한 사용자는 Claude Code가 계획을 ~/.claude/plans에 동물 이름으로 저장하는데, 같은 세션에서 완전히 다른 작업을 새로 계획시켜도 이전에 저장된 첫 계획을 계속 참조하는 현상을 겪었다고 보고했어요. 임시 해결책으로는 명시적으로 "새 계획을 세워달라"고 요청하거나, 작업 단위마다 세션을 새로 시작하는 방법이 제시됐습니다. 공식 문서에는 이 부분이 따로 언급돼 있지 않으니, 반복적으로 계획을 여러 번 새로 짜는 작업 흐름이라면 한 번쯤 의심해볼 만한 지점입니다.
Plan Mode 하나만 켜놓는다고 모든 게 해결되지는 않아요. 지금 하려는 작업이 diff 한 문장짜리인지 먼저 따져보고, 애매하면 일단 켜서 계획부터 받아보는 쪽을 권합니다. 계획이 마음에 안 들면 승인하지 말고 피드백부터 주고받아 보세요.
'AI활용' 카테고리의 다른 글
| Claude Code sandbox.credentials 설정, 기본값만 믿으면 안 되는 이유 (0) | 2026.07.11 |
|---|---|
| HWP-MCP 완벽 가이드 2026, Claude로 한글 문서 자동화하기 (0) | 2026.07.06 |
| Claude Code Task Budgets, 왜 안 될까 — API 비용 폭주 진짜로 막는 법 (2026) (0) | 2026.07.05 |
| Claude Code ultrareview 써보니, 아무 커밋에나 쓸 건 아니었다 (0) | 2026.07.05 |
| AGENTS.md 완전 가이드: AI 코딩 도구 28개가 함께 읽는 단 하나의 파일 (1) | 2026.07.05 |