Gemini 3.1 Pro 기준
Gemini CLI Plan 모드, 기본 켜진 게 함정입니다
2026년 3월 17일, Gemini CLI v0.34.0 업데이트와 함께 Plan 모드가 모든 사용자의 기본값으로 바뀌었습니다. 그런데 대부분 개발자들이 그냥 지나쳤습니다. Plan 모드가 켜진 동안 실제로 어떤 모델이 돌아가고, 무료 할당은 어떻게 소모되는지 — 공식 문서와 릴리스 노트를 직접 뜯어봤습니다.
Plan 모드가 뭔지, 한 줄로 정리하면
Gemini CLI Plan 모드는 코드를 건드리기 전에 읽기 전용 상태에서 먼저 코드베이스를 분석하고, 실행 계획서(Markdown 파일)를 작성한 뒤 사용자 승인을 받아야만 실제 파일을 수정하는 모드입니다. 공식 발표는 2026년 3월 11일(v0.33.0)이었고, v0.34.0(2026.03.17)부터 기본값이 됐습니다.
작동 흐름을 단순하게 보면 이렇습니다. AI가 먼저 코드베이스를 읽고, 필요한 게 있으면 ask_user 도구로 질문한 뒤, 계획서를 만들고, 개발자가 승인하면 그때부터 파일 수정에 들어갑니다. Plan 단계에서는 파일을 읽기만 합니다. 단, 계획서 자체는 ~/.gemini/tmp/<project>/<session-id>/plans/ 경로에 .md 파일로 저장됩니다.
💡 공식 발표문과 실제 사용 흐름을 같이 놓고 보니, Plan 모드는 단순한 “확인 창”이 아니라 AI가 작업 착수 전에 직접 코드를 탐색하고 설계를 검증하는 별도의 연구 단계입니다. 파일을 잘못 덮어쓰는 흔한 실수를 이 단계에서 막습니다.
진입 방법은 세 가지입니다. 입력창에 /plan을 입력하거나, Shift+Tab으로 모드를 순환하거나, 자연어로 “이 작업 계획 세워줘”라고 말하면 됩니다. 기본값이 된 지금은 아무것도 하지 않아도 이미 Plan 모드로 시작합니다.
v0.34.0부터 기본값이 바뀐 이유가 있습니다
공식 릴리스 노트를 보면 v0.34.0 변경 이유로 딱 한 줄이 나옵니다: “Plan Mode is now enabled by default to help you break down complex tasks and execute them systematically.” (출처: Gemini CLI 공식 변경 로그, 2026.03.17) 즉 복잡한 작업을 체계적으로 나누기 위해서라는 게 공식 설명입니다.
그런데 실제 맥락을 보면 다른 이유도 있습니다. 커뮤니티에서 Gemini CLI가 복잡한 다중 파일 작업에서 도구 호출 오류와 재시도 루프로 파일을 덮어쓰는 문제가 계속 보고됐고, DataCamp의 비교 테스트에서는 동일한 작업에 Gemini CLI가 Claude Code의 432K 대 261K, 약 1.66배의 토큰을 소모했습니다. (출처: DataCamp ‘Gemini CLI vs. Claude Code’ 비교, 2026.03.26) 이 수치는 AI가 계획 없이 실행에 바로 뛰어들면 얼마나 비효율적인지를 보여줍니다.
Plan 모드 자체는 2월 17일 도입됐지만, 기본값이 된 건 약 한 달 뒤인 3월 17일입니다. 그 사이 두 번의 업데이트(v0.32.0, v0.33.0)를 통해 외부 편집기 지원, 멀티셀렉트 옵션, 연구 서브에이전트를 붙이고 나서야 기본으로 켰습니다. 준비를 충분히 한 뒤에 기본화한 셈입니다.
플래닝 중엔 Pro, 구현 중엔 Flash — 이게 왜 중요한가
여기서 많은 사람이 놓치는 부분이 있습니다. Plan 모드가 활성화된 상태에서 Gemini CLI는 모델 라우팅을 자동으로 분리합니다. 공식 문서에는 이렇게 나옵니다: “플래닝 단계에서는 Pro 모델로 라우팅하여 견고한 아키텍처 결정을 보장하고, 계획이 승인되면 구현 단계에서는 Flash 모델로 자동 전환한다.” (출처: geminicli.com/docs/cli/plan-mode, 2026.03 기준)
💡 Plan 모드에서 계획서를 승인하는 순간 모델이 Flash로 내려갑니다. 그러니까 복잡한 판단은 Pro가 하고, 반복적인 코드 작성은 Flash가 처리하는 구조입니다. 이게 내장된 토큰 최적화입니다.
이 자동 전환을 끄고 싶다면 settings.json에서 "modelRouting": false로 설정하면 됩니다. 단, 이렇게 하면 구현 단계에서도 계속 Pro를 쓰게 돼 Pro 할당이 더 빠르게 소모됩니다.
여기서 생각해 볼 점이 하나 있습니다. v0.12.0(2025.10.27) 때 이미 모델 라우팅 기능이 도입됐는데, 당시에는 “단순 질문은 Flash, 복잡한 분석은 Pro”로 세션 단위로 나눴습니다. Plan 모드와 결합하면 이제 단순 질문/복잡 분석의 구분이 아니라 플래닝 단계/구현 단계라는 더 정밀한 기준으로 모델이 나뉩니다. 같은 작업 안에서도 단계별로 최적 모델을 자동 선택하는 구조로 진화한 것입니다.
무료 사용자가 놓치는 Pro 할당 소모 문제
여기가 실제로 가장 주의해야 할 부분입니다. Plan 모드가 기본으로 켜진 지금, Plan 단계에서 사용되는 모델은 Pro입니다. 그런데 2026년 3월 25일부터 무료 티어에서 Pro 모델이 제거됐습니다. DataCamp의 비교 자료에는 이렇게 나옵니다: “As of late March 2026, free users are limited to Flash models, with Pro models behind a paid subscription.” (출처: DataCamp ‘Gemini CLI vs. Claude Code’, 2026.03.26)
즉, 지금 무료 계정으로 Gemini CLI를 쓰면 Plan 모드가 기본으로 켜져 있지만, Pro 모델 접근이 막혀 있어 Plan 단계에서 Flash를 사용하거나 오류가 날 수 있습니다. 무료 사용자는 결국 Plan 모드의 핵심인 “Pro 모델 기반 아키텍처 분석”을 제대로 활용하지 못합니다.
⚠️ 무료 사용자 주의
3월 25일 이후 무료 티어는 Flash 모델로만 제한됩니다. Plan 모드가 기본값이지만 Pro 라우팅이 없어 동작 방식이 유료 사용자와 다릅니다. Google AI Pro(약 $20/월) 구독이 없다면 Plan 모드는 Flash 기반으로만 작동합니다.
한 가지 더 있습니다. OAuth(구글 계정 로그인) 방식으로 사용하는 경우, 토큰 캐싱이 지원되지 않습니다. 공식 문서에는 “Token caching is not available for OAuth users — the Code Assist API does not support cached content creation at this time”라고 나옵니다. (출처: geminicli.com/docs/cli/token-caching, 2026.03 기준) API 키 방식으로 접속하는 사용자는 이전 컨텍스트를 재사용해 토큰을 아낄 수 있지만, 구글 계정으로 로그인한 사용자는 매 요청마다 전체 컨텍스트를 새로 전송합니다. 같은 작업에 더 많은 토큰을 씁니다.
Plan 모드가 코드베이스 전체를 읽는 특성상 컨텍스트 길이가 길어지는데, 이 상황에서 토큰 캐싱 없이 OAuth 로그인으로 사용하면 일일 Pro 할당이 생각보다 빠르게 소진됩니다. GitHub 이슈 #22271(2026.03.12)에서는 이미 사용자들이 “컨텍스트 80% 도달 경고가 없어서 조용히 잘려나갔다”고 보고했습니다.
Claude Code Auto 모드와 비교하면 어떤 차이가 있나
Claude Code도 Plan 모드가 있고, 2026년 3월에 Auto 모드를 추가 공개했습니다. 두 도구를 나란히 놓고 보면 접근 방식이 다릅니다.
출처: DataCamp ‘Gemini CLI vs. Claude Code: Differences and Use Cases (2026)’, 2026.03.26 / emergent.sh ‘Gemini CLI vs Claude Code’ 비교, 2026.03.05
토큰 소모량 차이(432K 대 261K, 약 66% 더 소모)는 주목할 만합니다. 단순히 “Gemini가 덜 효율적이다”가 아니라, Gemini CLI는 더 광범위하게 코드베이스를 탐색하는 방식을 씁니다. Plan 모드가 이 탐색을 구조화하고 불필요한 반복을 줄이기 위해 도입됐지만, 여전히 탐색 자체에 많은 토큰을 씁니다. 유료 사용자라면 Plan 모드가 실질적인 개선이지만, Flash 한도만 있는 무료 사용자라면 다른 이야기가 됩니다.
반면 Gemini CLI가 명확히 유리한 점은 오픈소스(Apache 2.0)라는 사실입니다. 기업 환경에서 코드를 직접 검토하거나 포크해서 쓸 수 있다는 건 Claude Code로는 불가능합니다.
Plan 모드를 실제로 잘 쓰는 방법
공식 문서와 실제 사용 패턴을 종합하면 효과적으로 Plan 모드를 활용하는 방법이 몇 가지 나옵니다.
계획서를 승인 전에 직접 편집하세요
Plan이 제시되면 Ctrl+X로 외부 편집기(VS Code, Vim 등)에서 계획서를 열 수 있습니다. 원하지 않는 단계를 지우거나, “이 부분은 기존 Logger 클래스를 써야 해”처럼 주석을 달면 AI가 그 피드백을 반영해 계획을 수정합니다. 자연어로 설명하는 것보다 이 방법이 더 빠르고 정확합니다.
API 키 방식으로 인증하면 토큰 캐싱이 됩니다
구글 계정(OAuth) 방식 대신 Gemini API 키를 직접 입력하면 토큰 캐싱이 활성화됩니다. 장시간 세션에서는 이 차이가 꽤 납니다. /stats 명령으로 캐시된 토큰 절감량을 직접 확인할 수 있습니다.
간단한 작업엔 Plan 모드를 꺼도 됩니다
/settings에서 “Plan”을 검색하면 토글로 끌 수 있습니다. 파일 하나 수정하거나 간단한 스크립트 생성할 때는 Plan 모드를 거치면 오히려 시간이 더 걸립니다. Shift+Tab으로 순간적으로 Auto-Edit 모드로 전환하는 것도 방법입니다.
read-only MCP 도구를 Plan 모드에서 쓰면 외부 데이터도 안전하게 읽습니다
Plan 모드는 로컬 파일뿐 아니라 github_read_issue, postgres_read_schema 같은 읽기 전용 MCP 도구도 허용합니다. GitHub 이슈를 읽어서 코드 변경 계획에 반영하는 것도 이 단계에서 가능합니다. 쓰기 작업이 없으니 실수가 없습니다.
CI/CD 파이프라인에서 비대화형으로 실행할 수 있습니다
gemini --approval-mode plan -p "텔레메트리 분석 후 개선점 제안" 형태로 실행하면 비대화형 환경에서 자동으로 계획을 세우고 YOLO 모드로 구현까지 이어집니다. GitHub Actions 등에서 활용할 수 있습니다.
자주 나오는 질문 5가지
마치며 — Plan 모드는 누구에게 진짜 쓸모 있나
Gemini CLI Plan 모드를 공식 문서 기준으로 뜯어보면 솔직히 두 가지 평가가 나옵니다.
좋은 쪽: 코드베이스를 망가뜨리는 흔한 실수를 줄이고, Pro→Flash 자동 전환으로 토큰을 아끼며, CI/CD에서도 쓸 수 있는 구조로 만들어졌습니다. 오픈소스라서 정책 엔진을 직접 커스터마이즈할 수 있다는 것도 진짜 장점입니다.
아쉬운 쪽: 2026년 3월 25일 이후 무료 사용자는 Flash 모델로만 돌아가고, OAuth 로그인으로 쓰면 토큰 캐싱도 안 됩니다. 같은 작업에서 Claude Code보다 66% 더 많은 토큰을 쓴다는 수치도 무시하기 어렵습니다. Plan 모드가 기본으로 켜졌다고 해서 무조건 좋아진 건 아닙니다.
결론적으로, Google AI Pro 이상 구독 + API 키 인증 조합이라면 Plan 모드는 실질적으로 도움이 됩니다. 무료 계정이거나 OAuth로만 쓴다면 아직 절반짜리 경험입니다. Plan 모드를 껐다 켜는 게 나쁜 게 아니라, 상황에 맞게 쓰는 게 맞습니다.
본 포스팅 참고 자료
- Google Developers Blog — Plan mode is now available in Gemini CLI (2026.03.11) 링크
- Gemini CLI 공식 문서 — Plan Mode (geminicli.com/docs/cli/plan-mode)
- Gemini CLI 공식 변경 로그 (geminicli.com/docs/changelogs)
- DataCamp — Gemini CLI vs. Claude Code: Differences and Use Cases (2026.03.26) (링크)
- emergent.sh — Gemini CLI vs Claude Code (2026.03.05) (링크)
- Gemini CLI GitHub Issue #22271 — Token Budget Warning at 80% Context Usage (2026.03.12) (링크)
본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 모든 수치와 기능은 2026년 3월 28일 기준이며, Gemini CLI는 지속적으로 업데이트되고 있습니다. 최신 정보는 공식 문서에서 확인하세요.
댓글 남기기