Gemini CLI v0.29.0+
Gemini CLI Plan 모드: “일단 써보면 된다” 믿으면 무료 한도 소진 폭탄 그대로 맞는 이유
2026년 3월 11일 구글이 기본 활성화(enabled by default)로 배포한 Plan 모드 — 무료 사용자가 모르면 손해 보는 3가지 구조적 함정과 실제 활용 전략을 공식 문서 기반으로 파헤칩니다.
Plan 모드란 무엇인가 — 핵심부터 먼저
Gemini CLI Plan 모드는 2026년 3월 11일 구글이 공식 발표한 기능으로, 코드베이스에 어떤 변경도 가하지 않는 읽기 전용(read-only) 분석 환경입니다. AI가 먼저 충분히 조사하고, 전략을 수립하고, 그 계획을 사람이 검토한 뒤에야 실제 코드 수정을 진행하는 구조입니다. (출처: Google Developers Blog, 2026.03.11)
기존 터미널 AI 도구의 가장 큰 문제는 “일단 수정하고 보는” 방식이었습니다. 복잡한 마이그레이션이나 신규 기능 추가를 명령하면 AI가 의도를 잘못 파악한 채로 파일을 덮어쓰거나 의존성을 망가뜨리는 사고가 빈번했습니다. Plan 모드는 이 고질적인 문제를 해결하기 위해 AI의 행동 범위 자체를 구조적으로 제한합니다.
💡 공식 문서 기반 분석 — Plan 모드에서 허용되는 도구 목록
읽기 전용 파일 접근(read_file, list_directory, glob), 검색(grep_search, google_web_search), 질의(ask_user), 읽기 전용 MCP 도구(예: github_read_issue, postgres_read_schema)만 허용됩니다. 쓰기 도구는 ~/.gemini/tmp/ 내부의 .md 계획 파일에만 예외적으로 허용됩니다. (출처: geminicli.com/docs/cli/plan-mode, 2026.03.16 기준)
진입 방법은 세 가지입니다. 입력창에 /plan을 입력하거나, Shift+Tab으로 승인 모드를 순환하거나, 자연어로 “이 기능을 위한 계획을 세워줘”라고 말하면 됩니다. 기본 승인 모드를 항상 Plan으로 고정하려면 /settings에서 Default Approval Mode를 Plan으로 설정하면 됩니다.
무료 사용자가 절대 모르는 한도 소진 구조
많은 사람이 Gemini CLI를 “구글 계정 하나로 무료”라고 알고 있습니다. 실제로 공식 문서에 따르면 개인 구글 계정 OAuth 로그인 기준으로 하루 1,000회, 분당 60회 요청이 제공됩니다. (출처: geminicli.com/docs/resources/quota-and-pricing, 2026.03.16 기준) 이 숫자만 보면 넉넉해 보입니다.
그런데 Plan 모드에서 실제로 일어나는 일을 공식 문서에서 확인해보면 이야기가 달라집니다. Plan 모드가 활성화되면 Gemini CLI는 Gemini 3.1 Pro 수준의 고추론 모델을 자동으로 라우팅합니다. 고추론 모델은 단일 요청에서 내부적으로 여러 번의 추론 단계를 실행하기 때문에 일반 대화형 요청보다 토큰 소모가 몇 배 많습니다. 즉, 외형상 요청 1회처럼 보여도 실제 내부 연산 부하는 3~5배에 달할 수 있습니다.
💡 직접 계산해보는 시나리오
데이터베이스 마이그레이션처럼 복잡한 Plan 1회를 완성하는 과정에서 Gemini CLI는 codebase_investigator 서브에이전트를 포함해 내부적으로 10~20회의 분석 루프를 돌립니다. 공식 문서는 이를 “복잡한 시스템 의존성과 워크플로를 파악하기 위한 전문 서브에이전트 사용”이라고 명시합니다. 이 경우 Plan 1개 작업이 표면상 요청 카운터를 10회 이상 차감할 수 있습니다. 1,000회의 하루 한도는 이러한 고강도 Plan 작업 약 50~100회분에 불과합니다. 가볍게 여기면 오후 중에 한도가 소진됩니다.
| 인증 방식 | 일일 한도 | 분당 한도 | 사용 모델 |
|---|---|---|---|
| 구글 계정 OAuth (무료) | 1,000회 | 60회 | Gemini 전 모델 자동 |
| Gemini API 키 (무료) | 250회 | 10회 | Flash 모델만 |
| Google AI Pro (유료 구독) | 1,500회 | 120회 | Gemini 전 모델 자동 |
| Gemini Code Assist 기업용 | 2,000회 | 120회 | Gemini 전 모델 자동 |
(출처: geminicli.com/docs/resources/quota-and-pricing, 2026.03.16 기준 / API 키 무료 등급은 Plan 모드에서 Flash 모델 고정으로 Pro 라우팅 혜택 없음)
특히 주목할 함정은 Gemini API 키 무료 등급입니다. 이 방식으로 인증하면 Flash 모델만 사용 가능하고 하루 한도도 250회에 불과합니다. Plan 모드에서 고추론 Pro 모델 자동 라우팅의 혜택을 전혀 누릴 수 없습니다. 이 차이를 모르고 API 키로만 쓰면 Plan 모드를 쓰는 의미 자체가 크게 줄어드는 것입니다.
YOLO 모드에서 Plan 모드가 왜 안 되는가
Gemini CLI의 승인 모드는 크게 세 가지입니다. 일반 기본 모드(Default), 모든 편집을 자동 승인하는 Auto-Edit(YOLO) 모드, 그리고 이번에 추가된 Plan 모드입니다. 많은 개발자가 CI/CD 자동화나 빠른 프로토타이핑을 위해 YOLO 모드를 주로 씁니다.
그런데 공식 문서에는 다음과 같이 명시되어 있습니다. “이 도구(enter_plan_mode)는 Gemini CLI가 YOLO 모드에 있을 때는 사용할 수 없습니다.” (출처: geminicli.com/docs/cli/plan-mode, 2026.03.16 기준) YOLO 모드는 사용자 확인을 생략하고 즉시 실행하는 것이 목적이므로, 검토와 승인을 본질로 하는 Plan 모드와 구조적으로 충돌합니다.
⚠️ 실무에서 마주치는 충돌 시나리오
자동화 스크립트나 CI 파이프라인에서 Gemini CLI를 YOLO 모드(--approval-mode=autoEdit)로 실행하고 있다면, /plan 커맨드를 입력하거나 enter_plan_mode 도구를 호출해도 Plan 모드로 전환되지 않습니다. 자동화 환경에서 Plan 모드의 사전 분석을 활용하고 싶다면 별도의 분석 단계를 Plan 모드(--approval-mode=plan)로 먼저 실행하고, 그 출력 계획 파일(.md)을 검토한 뒤 두 번째 단계에서 Auto-Edit로 구현 단계를 진행하는 2단계 파이프라인이 필요합니다.
또 한 가지 놓치기 쉬운 제약이 있습니다. Plan 모드는 Gemini CLI가 요청을 처리 중이거나 확인 다이얼로그를 표시하는 동안에는 Shift+Tab 순환 목록에서 자동으로 제외됩니다. 즉, 한창 분석이 진행되는 도중에는 Plan 모드로의 전환이 불가능합니다. 처음 세션을 시작할 때 승인 모드를 미리 설정해두는 것이 가장 안전한 방법입니다.
Pro→Flash 자동 전환, 이게 왜 중요한가
여기가 Plan 모드에서 가장 많이 오해받는 지점입니다. 많은 사람이 “Plan 모드를 쓰면 항상 느린 Pro 모델을 써서 속도가 느리다”고 생각합니다. 하지만 공식 문서는 정반대의 원리를 설명합니다.
💡 공식 문서와 실사용 비교를 교차 분석한 결과입니다
구체적으로 의미하는 바는 이렇습니다. Plan 없이 바로 Auto-Edit 모드로 실행하면 AI가 처음부터 끝까지 같은 모델을 사용합니다. 하지만 Plan 모드를 거치면 분석/설계는 Pro가 정밀하게 수행하고, 반복적인 코드 수정 실행은 Flash가 빠르게 처리합니다. 결과적으로 Plan 모드를 거친 세션이 오히려 총 처리 속도가 빠를 수 있고, 유료 API 키 사용자라면 토큰 비용도 절감됩니다.
다만 이 자동 라우팅이 작동하려면 “auto 모델” 설정을 사용해야 합니다. Gemini API 키 무료 등급처럼 특정 모델이 고정된 경우에는 이 최적화가 동작하지 않습니다. 또한 자동 라우팅을 원하지 않을 경우 settings.json에서 "modelRouting": false로 비활성화할 수 있습니다.
Claude Code와 비교했을 때 진짜 차이
AI 코딩 CLI 도구 중에서 Gemini CLI와 가장 많이 비교되는 것은 앤트로픽의 Claude Code입니다. 두 도구 모두 2026년 현재 Plan 모드(또는 계획 기능)를 갖추고 있지만, 접근 방식에서 중요한 차이가 있습니다.
| 구분 | Gemini CLI | Claude Code |
|---|---|---|
| 진입 비용 | 무료 (구글 계정) | Claude Pro/Max 구독 필요 |
| Plan 모드 기본 활성화 | ✅ 기본 ON | 선택적 활성화 |
| 모델 라우팅 최적화 | Plan→Pro, 구현→Flash 자동 | 구독 플랜 내 고정 모델 |
| 컨텍스트 창 | 100만 토큰 | 100만 토큰 (베타) |
| 오픈소스 여부 | Apache 2.0 | 비공개 |
| 자율 추론 깊이 | 강함 (Gemini 3.1 Pro) | 매우 강함 (Opus 4.6) |
(출처: sanj.dev, 2026.02.25 비교 리뷰 / geminicli.com/docs, 2026.03.16 기준)
실제 현장 비교 리뷰에 따르면 Claude Code는 다중 파일에 걸친 복잡한 디버깅 추론에서 여전히 한 단계 앞섭니다. (출처: sanj.dev 비교 리뷰, 2026.02.25) 반면 Gemini CLI는 신용카드 없이 30초 안에 시작할 수 있고, 무료 일일 1,000회라는 넉넉한 한도, 구글 검색 그라운딩을 통한 실시간 정보 연동이라는 고유한 강점이 있습니다. 무엇을 쓸지가 아니라 어떤 작업에 쓸지가 핵심입니다.
실전 사용법 — Plan 모드를 제대로 써먹는 순서
지금까지 함정을 알았으면, 이제 올바른 사용 순서를 정리할 차례입니다. 다음은 공식 문서 기반의 권장 워크플로입니다.
npm install -g @google/gemini-cli 후 gemini 실행. OAuth 로그인 선택. API 키 무료 등급으로 인증하면 Plan 모드에서 Pro 라우팅이 작동하지 않으므로 반드시 구글 계정 OAuth를 권장합니다.
단순한 파일 수정 한두 개는 일반 모드가 더 경제적입니다. 의존성 분석이 필요한 마이그레이션, 신규 모듈 설계, 보안 취약점 탐색 같은 복잡한 작업에서만
/plan을 입력하거나 자연어로 요청합니다.
Plan 모드 진행 중 Gemini CLI가
ask_user 도구로 질문을 던집니다. 이 질문에 모호하게 답하면 계획의 품질이 낮아집니다. 아키텍처 선택지, 설정 파일 위치, 우선순위 등을 가능한 구체적으로 응답하는 것이 핵심입니다.
계획을 승인하면 Gemini CLI가 자동으로 Flash 모델로 전환하여 구현을 시작합니다.
/stats model 명령으로 현재 모델 사용 현황과 잔여 한도를 언제든 확인할 수 있습니다.
한도 관리 팁도 빠뜨릴 수 없습니다. 기본적으로 세션 데이터와 계획 파일은 30일간 보관됩니다. /settings의 Session Retention 항목에서 이 기간을 조정할 수 있습니다. 오래된 세션을 정리하지 않으면 임시 디렉토리가 쌓이므로 주기적인 관리를 권장합니다.
자주 묻는 질문 5가지
마치며 — Plan 모드가 AI 코딩 워크플로에 의미하는 것
Gemini CLI Plan 모드는 단순히 “먼저 계획하고 나중에 실행하는” 기능이 아닙니다. 설계 단계에 고추론 모델을, 구현 단계에 고속 모델을 자동으로 배분하는 이 구조는 AI 에이전트가 비용과 성능을 스스로 최적화하는 방향으로 진화하고 있음을 보여주는 구체적인 사례입니다.
무료 사용자 입장에서 중요한 것은 딱 두 가지입니다. 첫째, 반드시 API 키가 아닌 구글 계정 OAuth로 로그인해서 Pro 라우팅 혜택을 받을 것. 둘째, 단순 작업에 Plan 모드를 남발하지 않아야 하루 1,000회 한도를 정말 중요한 작업에 아낄 수 있다는 점입니다.
Claude Code가 깊은 추론과 완전한 자율성에서 앞선다면, Gemini CLI는 무료 진입 장벽과 구글 생태계 연동에서 독보적입니다. 이 두 도구는 경쟁보다 상호 보완에 가깝습니다. Plan 모드라는 새로운 레이어를 얼마나 잘 활용하느냐가 2026년 개발자 생산성의 핵심 변수가 될 것입니다.
📚 본 포스팅 참고 자료
- 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 (2026.03.16 기준) https://geminicli.com/docs/cli/plan-mode/
- Gemini CLI 공식 문서 — Quotas and Pricing (2026.03.16 기준) https://geminicli.com/docs/resources/quota-and-pricing/
- ADTmag — “Google Adds ‘Plan Mode’ to Gemini CLI” (2026.03.12) https://adtmag.com/articles/…
- sanj.dev — “Claude Code vs Gemini CLI vs OpenCode vs Goose vs Aider in 2026” (2026.02.25) https://sanj.dev/post/comparing-ai-cli-coding-assistants
- InfoWorld — “Gemini CLI introduces plan mode” (2026.03.13) https://www.infoworld.com/article/4144594/…
본 포스팅은 2026년 3월 16일 기준 Gemini CLI v0.29.0+ 및 공식 문서를 바탕으로 작성되었습니다. 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 모든 수치(한도, 가격, 모델명)는 구글의 업데이트에 따라 달라질 수 있으므로 최신 정보는 공식 문서(geminicli.com/docs)를 반드시 확인하시기 바랍니다.
댓글 남기기