Gemini CLI Plan 모드
Gemini CLI Plan 모드, 기본값이라고요? 이 조건부터 보세요
구글이 2026년 3월 11일 Gemini CLI v0.33.0 업데이트에서 Plan 모드를 전체 사용자 기본값으로 적용했습니다. 그런데 “기본값 = 무조건 좋다”는 건 아닙니다. YOLO 모드를 쓰면 Plan 모드 진입 도구 자체가 비활성화되고, 플래닝 단계에서 자동으로 Pro 모델이 붙기 때문에 요금이 달라집니다. 공식 문서에 딱 이렇게 나옵니다.
Plan 모드가 뭔지, 한 문장으로
Gemini CLI Plan 모드는 AI가 코드를 수정하기 전에 먼저 코드베이스를 읽고 계획서를 작성하도록 강제하는 읽기 전용(read-only) 실행 환경입니다. 2026년 3월 11일 v0.33.0에서 정식 출시되어, 전체 사용자에게 기본값으로 적용됐습니다. (출처: Google Developers Blog, 2026.03.11)
쉽게 말하면, AI가 무작정 파일을 고치는 걸 막는 “제동 장치”입니다. Plan 모드가 활성화된 상태에서 AI는 read_file, grep_search, glob 같은 읽기 툴만 사용할 수 있고, 파일 수정은 플래닝 디렉토리 내 .md 파일에만 허용됩니다. (출처: Gemini CLI 공식 문서)
계획이 확정되고 사용자가 승인하면 그때부터 편집 모드로 전환되어 실제 코드 수정이 시작됩니다. 이 흐름이 핵심입니다.
기본값인데 왜 안 켜진 것처럼 느껴지나
Plan 모드는 기본값이긴 하지만, 처음 Gemini CLI를 실행하면 즉시 Plan 모드로 진입하진 않습니다. “Default 승인 모드”가 Plan이 아니라 그냥 ‘Default’로 설정되어 있기 때문입니다. 이 부분이 헷갈립니다.
💡 공식 문서를 같이 놓고 보니 이런 차이가 보였습니다. “기본값 적용(enabled by default)”은 Shift+Tab 단축키 순환에 Plan 모드가 포함되어 있다는 뜻이지, 처음 실행부터 Plan 모드로 시작한다는 뜻이 아닙니다. 기본 시작 모드를 Plan으로 바꾸려면 /settings에서 Default Approval Mode를 직접 변경해야 합니다. (출처: Gemini CLI 공식 문서)
그래서 실제로는 /plan 명령어를 입력하거나, Shift+Tab을 눌러 모드를 전환하거나, 자연어로 “plan for…”를 말해야 Plan 모드가 작동합니다.
“기본값이니까 그냥 쓰면 되겠지”라고 생각하고 설정을 안 건드렸다면, 지금까지 Plan 모드 없이 쓴 겁니다.
Pro 모델이 자동 배정된다는 말의 의미
이게 가장 중요한 부분입니다. Plan 모드에서 Gemini CLI는 플래닝 단계에 자동으로 Gemini 3.1 Pro를 배정합니다. 구현 단계로 넘어가면 더 빠른 Flash 모델로 전환됩니다. (출처: Gemini CLI 공식 문서 – Automatic Model Routing)
💡 “Auto 모델”을 쓸 때만 이 자동 라우팅이 작동합니다. 수동으로 Flash 모델을 고정해두면 Plan 모드에서도 Flash만 씁니다. 전략적 판단은 Pro가, 빠른 실행은 Flash가 담당한다는 설계지만, API 비용을 직접 내는 경우라면 Pro 모델 호출 빈도가 올라가는 만큼 비용 계산을 다시 해봐야 합니다.
Gemini 3.1 Pro의 API 가격은 입력 토큰 기준 100만 토큰당 $2.00, 출력 기준 $12.00입니다. Flash 대비 입력은 약 3.2배, 출력은 약 3배 비쌉니다. (출처: Google Cloud Vertex AI 가격 페이지 / Gemini API 가격 문서)
복잡한 DB 마이그레이션이나 아키텍처 설계처럼 신중함이 필요한 작업엔 Pro 자동 배정이 유리합니다. 하지만 단순 파일 정리나 간단한 리팩토링이라면 Pro를 쓸 이유가 없으니, 이런 경우엔 Auto 모델 대신 Flash를 직접 지정하는 게 비용 측면에서 낫습니다.
YOLO 모드와 Plan 모드는 함께 못 씁니다
많은 개발자가 자동 승인을 선호해서 YOLO 모드를 씁니다. 그런데 공식 문서에는 이렇게 나옵니다. “YOLO 모드에서는 enter_plan_mode 툴이 비활성화됩니다.” (출처: Gemini CLI 공식 문서 – How to enter Plan Mode)
⚠️ YOLO 모드 = Plan 모드 진입 불가
YOLO 모드는 모든 툴 호출을 자동 승인합니다. Plan 모드의 설계 철학(“먼저 읽고, 나중에 수정”)과 정면으로 충돌하기 때문에 구글이 의도적으로 차단한 것입니다. CI/CD 파이프라인이나 headless 스크립트처럼 비대화형 환경에서 Plan 모드를 쓰면, 오히려 자동으로 YOLO 모드로 전환되어 실행됩니다.
이 제약 때문에 “Plan 모드로 설계하고, YOLO로 빠르게 실행”이라는 흐름은 단일 세션 내에서는 안 됩니다. 플래닝을 마치고 승인하면 그 순간 Plan 모드가 자동 종료되고 Default 편집 모드로 전환됩니다.
자동화 파이프라인을 돌리는 분들이 Plan 모드에 기대했던 “사전 리서치 후 안전 실행”은 비대화형 환경에서는 YOLO 자동전환이 되므로, 애초에 설계된 방향과 다르게 돌아갑니다.
MCP 연동하면 달라지는 점
Plan 모드는 로컬 파일시스템에만 머무르지 않습니다. 읽기 전용 MCP(Model Context Protocol) 툴과 연동해서 GitHub 이슈 읽기, Postgres 스키마 조회, Google Docs 검색까지 Plan 단계에서 할 수 있습니다. (출처: Google Developers Blog, 2026.03.11)
💡 공식 발표문과 실제 정책 파일을 같이 보면 한 가지가 보입니다. 읽기 전용 MCP 툴은 Plan 모드에서 기본적으로 사용자 확인(confirm)을 요구합니다. 매번 누르기 귀찮으면 ~/.gemini/policies/에 정책 파일을 추가해서 자동 승인으로 바꿀 수 있습니다.
예를 들어 DB 마이그레이션을 계획할 때, AI가 GitHub에서 관련 이슈를 읽고, Postgres에서 현재 스키마를 조회한 뒤 계획서를 작성합니다. 코드베이스는 물론 외부 시스템까지 건드리지 않으면서요. 공식 문서에서 이 흐름을 직접 예시로 들고 있습니다.
단, MCP 서버가 자체적으로 쓰기 작업을 허용하더라도, Plan 모드 정책이 읽기 전용 힌트(readOnlyHint = true)가 붙은 툴만 허용합니다. 쓰기 가능한 MCP 툴을 Plan 모드에서 쓰려면 별도 정책 파일을 작성해야 합니다.
실제로 겪는 문제 — 용량 오류
Plan 모드에서 Pro 모델이 자동 배정되면서 한 가지 문제가 현실적으로 생깁니다. 서버 용량 오류입니다. 유료 구독(Google AI Pro)을 사용 중인데도 “API Error: No capacity available for model gemini-3-flash-preview on the server“가 하루 종일 뜨는 케이스가 실제로 보고되고 있습니다. (출처: Gemini CLI GitHub Issues #20008, 2026.02.23)
구글 개발팀이 이 이슈에 공식 답변을 내놓지 않은 상태입니다. 웹에서는 정상 접속되는데 CLI에서만 용량 오류가 나는 경우도 포함됩니다.
| 증상 | 임시 해결 방법 |
|---|---|
| API 용량 오류 반복 | 모델을 Flash로 수동 고정 후 재시도 |
| Pro 모델 지속 실패 | Auto 모델 라우팅 비활성화 (modelRouting: false) |
| Plan 모드 진입 후 멈춤 | CLI 재시작, /settings에서 Session Retention 확인 |
용량 오류가 잦으면 Plan 모드의 장점인 Pro 모델 자동 배정이 오히려 걸림돌이 됩니다. 이 경우 settings.json에서 "modelRouting": false로 설정해두고 직접 모델을 고정하는 게 현실적입니다.
Claude Code·Cursor와 뭐가 다른가
비슷한 AI 코딩 툴과 비교할 때, Plan 모드의 가장 큰 차이는 “계획 단계와 실행 단계의 모델을 시스템이 자동으로 분리”한다는 점입니다. 다른 툴들은 하나의 모델을 처음부터 끝까지 씁니다.
| 도구 | 계획 모드 | 모델 전환 | 읽기 전용 강제 |
|---|---|---|---|
| Gemini CLI | 기본값 ON (v0.33.0~) | 자동 (Pro→Flash) | ✅ 정책 엔진 |
| Claude Code | 수동 (–think 플래그) | 없음 | 없음 |
| Cursor | Ask 모드 별도 | 수동 | 없음 |
DevOps 전문 분석 기관 The Futurum Group의 Mitch Ashley VP는 “Plan 모드는 AI 코딩 에이전트의 거버넌스 방식을 자율 실행에서 인간 확인 선행 워크플로우로 이동시켰다”며 “구축 리스크 허용치가 낮고 감사 요건이 엄격한 기업 도입에서 Google이 경쟁 우위를 확보하는 구조”라고 평했습니다. (출처: DevOps.com, 2026.03.11)
Enterprise 환경에서 AI 코딩 툴 도입을 검토하는 팀이라면, Plan 모드의 읽기 전용 강제와 정책 엔진 기반 커스터마이징이 다른 도구에는 없는 분명한 차이입니다.
자주 묻는 질문 5가지
Q1. Plan 모드를 비활성화하고 싶으면 어떻게 하나요?
/settings 명령어에서 “Plan”으로 검색한 뒤 토글을 끄면 됩니다. 이렇게 하면 Shift+Tab 순환에서 Plan 모드가 제거되고, enter_plan_mode·exit_plan_mode 툴도 등록 해제됩니다. (출처: Gemini CLI 공식 문서)
Q2. Plan 모드에서 만든 계획서 파일은 어디에 저장되나요?
기본 저장 경로는 ~/.gemini/tmp/<project>/<session-id>/plans/입니다. 30일 후 자동 삭제됩니다. 커스텀 경로로 바꾸려면 settings.json에 "plan": { "directory": ".gemini/plans" }를 추가하면 되지만, 커스텀 경로는 프로젝트 루트 내부에만 지정 가능합니다. (출처: Gemini CLI 공식 문서)
Q3. Plan 모드에서 git 명령어는 쓸 수 있나요?
기본적으로는 안 됩니다. 하지만 ~/.gemini/policies/git-research.toml을 만들어 git status, git diff를 허용하는 정책을 추가하면 Plan 모드에서도 사용 가능합니다. 정책 파일 예시는 공식 문서에 그대로 나와 있습니다. (출처: Gemini CLI 공식 문서)
Q4. Conductor는 무료로 쓸 수 있나요?
Conductor는 오픈소스 확장으로 GitHub에서 무료로 받을 수 있습니다. gemini extensions install https://github.com/gemini-cli-extensions/conductor 명령어로 설치합니다. 구글이 향후 Conductor를 Gemini CLI 빌트인 모드로 통합할 계획이라고 공식 발표했지만, 정확한 일정은 아직 공개되지 않았습니다. (출처: Google Developers Blog, 2026.03.11)
Q5. 무료 계정으로도 Plan 모드를 쓸 수 있나요?
Gemini CLI는 Google 계정으로 OAuth 로그인해서 사용하며, 무료 API 한도 내에서도 Plan 모드를 쓸 수 있습니다. 다만 무료 계정에서 Pro 모델 한도는 매우 제한적입니다. Gemini 2.5 Pro 기준 무료 계정은 하루 프롬프트 5개 한도가 있고, Plan 모드에서 Pro가 자동 배정되면 그 한도를 빠르게 소진합니다. (출처: Google Gemini 공식 지원 문서)
마치며 — 써볼 만한가, 아닌가
솔직히 말하면, Plan 모드는 “코드 몇 줄 빠르게 고치는 용도”에는 오히려 번거롭습니다. 플래닝 단계가 하나 더 생기고, 그 과정에서 Pro 모델이 호출되니까요. 단순 작업엔 Plan 모드를 끄거나 Flash를 직접 지정하는 게 낫습니다.
반면 DB 마이그레이션, 대규모 리팩토링, 멀티 서비스 연동처럼 “잘못되면 되돌리기 힘든” 작업에는 Plan 모드가 실질적인 안전망이 됩니다. AI가 먼저 코드베이스를 읽고 계획서를 작성하고 물어보기까지 한 뒤 실행하니까, 틀린 방향으로 코드를 잔뜩 고쳐놓는 실수가 확연히 줄어듭니다.
YOLO 모드를 주로 쓰거나, 용량 오류를 자주 겪는다면 Plan 모드의 효과를 제대로 보기 어렵습니다. 이 두 조건을 먼저 확인하고 나서 Plan 모드를 평가하는 게 순서입니다.
본 포스팅 참고 자료
- Google Developers Blog — Plan mode is now available in Gemini CLI (2026.03.11) https://developers.googleblog.com/plan-mode-now-available-in-gemini-cli/
- Gemini CLI 공식 문서 — Plan Mode https://geminicli.com/docs/cli/plan-mode/
- Gemini CLI GitHub Discussions — v0.33.0 주간 업데이트 https://github.com/google-gemini/gemini-cli/discussions/22078
- DevOps.com — Gemini CLI Plan Mode Separates Thinking From Doing (2026.03.11) https://devops.com/gemini-cli-plan-mode-separates-thinking-from-doing-and-makes-read-only-the-default/
- Google Cloud Vertex AI 가격 문서 https://cloud.google.com/vertex-ai/generative-ai/pricing?hl=ko
- Gemini CLI GitHub Issues #20008 — 용량 오류 (2026.02.23) https://github.com/google-gemini/gemini-cli/issues/20008
본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 모든 수치와 기능 설명은 2026년 3월 30일 기준 공식 문서 및 발표 자료를 근거로 작성되었습니다. Gemini CLI v0.33.0 기준.
댓글 남기기