Gemini 3.1 Pro 라우팅
공식 문서 크로스체크
Gemini CLI Plan 모드, 읽기 전용인데 쿼터가 줄까요?
2026년 3월 11일, 구글이 Gemini CLI v0.33.0에 Plan 모드를 공식 도입했습니다. “코드를 건드리지 않으니 안전하다”는 말은 반만 맞습니다. 파일은 그렇지만, 쿼터는 다른 얘기입니다. 모델 라우팅 구조를 보면 이유가 바로 나옵니다.
Plan 모드란 무엇인가 — 3월 11일 무슨 일이 있었나
Gemini CLI Plan 모드는 2026년 3월 11일, v0.33.0 업데이트를 통해 처음 공개됐습니다. 핵심 개념은 단순합니다. 코드를 수정하기 전에 먼저 읽고, 분석하고, 계획을 짠 뒤 승인을 받는 구조입니다. (출처: Google Developers Blog, 2026.03.11)
Plan 모드가 켜지면 CLI는 read_file, grep_search, glob 같은 읽기 전용 도구만 씁니다. 파일 수정은 딱 한 곳에서만 가능합니다. ~/.gemini/tmp/<project>/<session-id>/plans/ 경로 안의 .md 파일뿐입니다. 실제 소스 코드는 단 한 글자도 건드리지 않습니다.
진입 방법은 세 가지입니다. /plan 명령어 입력, Shift+Tab 키로 모드 순환(Default → Auto-Edit → Plan), 또는 자연어로 “이 기능에 대한 계획을 세워줘”라고 말하면 됩니다. 기본값은 Plan 모드가 켜진 상태입니다.
💡 공식 발표문과 실제 설정 흐름을 같이 놓고 보니 이런 차이가 보였습니다 — Plan 모드는 기본값으로 켜져 있지만, Shift+Tab을 두 번 눌러야 진입합니다. 첫 번째 탭은 Auto-Edit 모드로, 두 번째가 Plan입니다. 누르는 순서를 착각하면 코드 자동 수정 모드(Auto-Edit)로 진입하는 상황이 생깁니다.
읽기 전용인데 쿼터가 왜 줄까 — 모델 라우팅의 구조
여기서 많은 사람이 오해하는 지점이 나옵니다. “파일을 수정 안 하니까 API 호출도 적겠지”라는 생각입니다. 실제로는 반대입니다.
공식 문서에 이렇게 나와 있습니다. “Planning Phase: While in Plan Mode, the CLI routes requests to a high-reasoning Pro model to ensure robust architectural decisions and high-quality plans.” 계획 단계에서는 Gemini 3.1 Pro 모델을 씁니다. 구현 단계로 넘어가면 속도 우선의 Flash 모델로 전환됩니다. (출처: geminicli.com 공식 문서) 코드를 안 건드리는 대신, 더 무거운 모델을 씁니다.
⚠️ 실제 쿼터 소비 구조
하나의 Plan 모드 프롬프트는 내부적으로 여러 차례 API를 호출합니다. Termdock 분석 기준으로, 프롬프트 1개당 평균 5~15회의 모델 요청이 발생합니다. 무료 구글 계정의 일일 한도는 1,000 요청이지만, 실제로 체감하는 프롬프트 수는 80~150개 수준입니다. (출처: Termdock, 2026.03.16) Plan 모드에서는 Pro 모델 호출이 늘어나므로 이 수치가 더 줄 수 있습니다.
이 구조를 알면 활용 전략이 달라집니다. Plan 모드를 쓸 때는 프롬프트를 최대한 구체적으로 작성해야 쿼터 낭비를 줄일 수 있습니다. “이 프로젝트 개선해줘”처럼 범위가 불명확한 요청은 에이전트가 여러 파일을 탐색하느라 Pro 모델 요청을 쌓아올립니다.
요금제별 실제 한도 — AI Plus는 지원 안 됩니다
구글의 AI 요금제는 이름이 여러 개라 헷갈립니다. 중요한 사실 하나를 먼저 짚고 갑니다. 2026년 1월 말에 출시된 Google AI Plus(월 11,000원)는 Gemini CLI에서 지원되지 않습니다. (출처: geminicli.com 공식 쿼터 문서) 플러스 요금제는 웹 기반 Gemini 앱 전용입니다.
| 인증 방식 / 요금제 | 일일 최대 요청 수 | CLI 지원 여부 |
|---|---|---|
| 구글 계정 (무료) | 1,000 요청/일 | ✓ 지원 |
| Google AI Plus (월 11,000원) | — | ✗ 미지원 |
| Google AI Pro (월 29,000원) | 1,500 요청/일 | ✓ 지원 |
| Google AI Ultra | 2,000 요청/일 | ✓ 지원 |
| Gemini API 키 (무료) | 250 요청/일 (Flash만) | △ 제한적 |
| Gemini Code Assist Enterprise | 2,000 요청/일 | ✓ 지원 |
(출처: geminicli.com 공식 쿼터 페이지, 2026.03.28 기준)
Gemini API 키 무료 버전은 일일 250 요청이고 Flash 모델만 씁니다. Plan 모드가 Pro 모델을 자동 라우팅하므로, API 키 무료 버전에서는 Plan 모드의 모델 라우팅 혜택을 제대로 받지 못합니다. 구글 계정 로그인 방식(무료)이 API 키 무료보다 4배 더 많은 일일 한도를 줍니다. CLI를 처음 설치한다면 구글 계정 로그인을 선택하는 게 맞습니다.
Claude Code Plan 모드와 진짜 다른 점
개발자 커뮤니티에서 자주 보이는 비교 지점입니다. 2025년 11월, 한 개발자는 자신의 블로그에 이렇게 적었습니다. “It is weird that Gemini CLI has no plan mode.” Gemini CLI에 Plan 모드가 없다는 것이 이상했다는 말입니다. (출처: kevinsimper.dk, 2025.11.27) 실제로 그랬습니다. Plan 모드는 2026년 3월 11일에야 처음 생겼습니다.
💡 두 도구의 Plan 모드를 나란히 놓고 보면 설계 철학이 다릅니다 — Claude Code의 Plan 모드는 모델이 알아서 판단해 플래그를 세우는 방식이고, Gemini CLI의 Plan 모드는 공식 정책 엔진(plan.toml)으로 허용 도구 목록을 강제 잠근 구조입니다. 기업 감사 요건이나 보안 정책을 코드로 명문화하기 쉬운 구조는 Gemini CLI 쪽입니다.
구체적으로 어떻게 다른가
Claude Code는 Shift+Tab 두 번으로 Plan 모드에 진입합니다. Gemini CLI는 동일한 단축키를 쓰지만, 순서가 Default → Auto-Edit → Plan이라 두 번 눌러야 합니다. 두 도구 모두 Shift+Tab을 쓰는 것처럼 보이지만 동작은 다릅니다.
Gemini CLI Plan 모드의 가장 눈에 띄는 차별점은 MCP 읽기 전용 도구 연동입니다. 계획 단계에서 GitHub 이슈를 읽거나 Postgres 스키마를 확인하는 것이 공식 지원됩니다. Claude Code에서는 MCP 연동이 실행 단계와 계획 단계를 명확히 나누지 않습니다. 데이터베이스 마이그레이션처럼 외부 시스템 상태를 먼저 파악해야 하는 작업에서는 Gemini CLI의 구조가 유리합니다.
Plan 모드가 실제로 유리한 작업 vs 쿼터 낭비인 상황
모든 작업에 Plan 모드를 쓰는 건 쿼터 낭비입니다. 구조적으로 Pro 모델이 더 많이 돌기 때문입니다. 작업 성격에 따라 구분하는 게 중요합니다.
✅ Plan 모드가 효과적인 상황
데이터베이스 마이그레이션, 여러 파일에 걸친 대규모 리팩토링, 새로운 기능 아키텍처 설계, 외부 스키마나 문서를 먼저 파악해야 하는 작업에서 제 역할을 합니다. 구글 공식 블로그도 “database migration research” 또는 “plan a new feature”를 대표 사례로 명시했습니다. (출처: Google Developers Blog, 2026.03.11)
❌ Plan 모드가 쿼터를 낭비하는 상황
파일 3개 이하의 소규모 버그 수정, 단위 테스트 작성, 문서 생성, 특정 함수 리네이밍처럼 범위가 명확한 작업에는 Plan 모드를 끄는 게 낫습니다. Pro 모델을 계획 단계에서 태우고 Flash로 넘기는 구조인데, 단순 작업은 처음부터 Flash로 처리하는 것이 더 효율적입니다. Termdock 분석에서 “scope is clear and a wrong answer wastes minutes” 유형 작업에는 Gemini CLI를 기본 모드로 쓰라고 권고합니다.
💡 공식 발표 내용과 실제 쿼터 데이터를 같이 보면 이 차이가 보입니다 — Plan 모드는 기본으로 켜져 있습니다. 아무 생각 없이 쓰다 보면, 간단한 요청에도 Pro 모델이 돌아 쿼터가 예상보다 빨리 줄 수 있습니다. 단순 작업 전에는 /settings에서 Default Approval Mode를 확인하는 습관이 필요합니다.
쿼터 아끼면서 Plan 모드 제대로 쓰는 법
공식 문서와 실사용 데이터를 교차해서 보면, 쿼터 관리에서 지키면 좋은 패턴이 나옵니다.
프롬프트를 범위 단위로 쪼개세요
넓은 범위의 프롬프트는 에이전트가 여러 파일을 탐색하며 API 호출을 쌓습니다. “인증 모듈의 진입점, 세션 관리 방식, 토큰 갱신 로직, 에러 처리 패턴을 한 번에 설명해줘”처럼 질문 하나에 여러 항목을 묶으면 API 호출 횟수를 줄입니다.
/stats model로 현재 사용량을 수시로 확인하세요
Gemini CLI는 쿼터 잔량을 자동 알림으로 보여주지 않습니다. /stats model 명령어로 현재 세션의 토큰 사용량과 한도를 직접 확인해야 합니다. (출처: geminicli.com 공식 쿼터 문서)
모델 라우팅 자동 설정은 건드리지 마세요
공식 문서에 “This behavior is enabled by default to provide the best balance of quality and performance”라고 나옵니다. Plan 단계에서 Pro, 구현 단계에서 Flash로 자동 전환하는 로직입니다. 이걸 수동으로 끄면 오히려 전체 과정에서 Pro 모델이 계속 돌 수 있습니다.
GEMINI.md 파일로 컨텍스트를 미리 주입하세요
프로젝트 루트에 GEMINI.md 파일을 만들고 아키텍처 개요, 코딩 컨벤션, 사용 중인 라이브러리를 200~500자 이내로 정리해 두면, Plan 모드가 코드베이스 탐색에 쓰는 초기 API 호출을 줄일 수 있습니다.
자주 묻는 것들
마치며
Gemini CLI Plan 모드는 “코드를 건드리지 않는다”는 점에서 안전하지만, “쿼터를 아낄 수 있다”는 의미는 아닙니다. Plan 단계에서 Gemini 3.1 Pro가 돌기 때문입니다. 기본값으로 켜져 있다는 것도 꼭 기억해야 합니다.
요금제 선택도 중요합니다. Google AI Plus(월 11,000원)로는 CLI 쿼터가 늘지 않습니다. CLI 한도를 늘리려면 AI Pro 이상이 필요하고, 무료 구글 계정 로그인이 API 키 무료보다 4배 더 많은 일일 한도를 줍니다.
Claude Code와의 비교에서 실용적인 관점은 이렇습니다. 대규모 리팩토링이나 DB 마이그레이션처럼 외부 컨텍스트를 먼저 파악해야 할 때는 Gemini CLI Plan 모드가 구조적으로 잘 맞습니다. 파일 3개 이하의 단순 작업은 굳이 Plan 모드를 쓸 이유가 없습니다. 도구를 작업 성격에 맞게 라우팅하는 것, 그것만으로 한 달 쿼터가 꽤 달라집니다.
본 포스팅 참고 자료
- Google Developers Blog — Plan mode is now available in Gemini CLI (2026.03.11)
- geminicli.com 공식 Plan Mode 문서
- geminicli.com 공식 Quota & Pricing 문서
- DevOps.com — Gemini CLI Plan Mode Separates Thinking From Doing (2026.03.16)
- Termdock — Claude Code + Gemini CLI 비용 구조 분석 (2026.03.16)
- GitHub — Gemini CLI v0.33.0 릴리스노트 (2026.03.11)
본 포스팅은 2026년 3월 28일 기준으로 작성됐습니다. 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 쿼터 수치·요금제·지원 범위는 구글 공식 문서에서 최신 정보를 직접 확인하시기 바랍니다.
댓글 남기기