Gemini CLI v0.33.0 기준
IT/AI
2026년 3월 11일, Google이 Gemini CLI에 Plan 모드(v0.33.0)를 정식 출시했습니다. 기본값으로 켜져 있는 이 모드, 막상 써보면 무료 한도가 생각보다 빠르게 닳습니다. 인증 방식 하나 차이로 하루 쓸 수 있는 요청이 4배까지 벌어집니다.
Plan 모드가 뭔데 이렇게 빠르게 화제가 됐을까요
(출처: Google Developers Blog, 2026.03.11)
기존 Gemini CLI는 명령을 받으면 바로 파일을 수정했습니다. 잘 동작할 때는 빠르고 편한데, 잘못되면 코드베이스가 의도치 않게 바뀌어 있었습니다. Plan 모드는 이 문제를 겨냥해 만든 기능입니다. 에이전트가 먼저 읽기 전용 상태로 코드베이스를 분석하고, 작업 계획을 Markdown 파일로 작성한 뒤, 사람이 승인해야 실제 편집에 들어갑니다.
현재 모든 사용자에게 기본값으로 활성화돼 있습니다. 의식하지 않아도 이미 Plan 모드 안에서 작업하고 있는 겁니다.
읽기 전용인데 왜 한도를 빠르게 쓸까요 — 모델 전환의 진실
💡 공식 문서와 실제 사용 흐름을 같이 놓고 보니 이런 구조가 보였습니다 — Plan 모드는 무료지만, 그 안에서 더 비싼 모델을 씁니다.
많은 사람들이 “읽기 전용이면 처리 부담이 적겠지”라고 생각합니다. 실제로는 반대입니다. Plan 모드 공식 문서에는 이렇게 적혀 있습니다.
“Planning Phase: While in Plan Mode, the CLI routes requests to a high-reasoning Pro model — specifically Gemini 3.1 Pro — for robust architectural decisions.”
(출처: geminicli.com/docs/cli/plan-mode, 2026.03.22 기준)
Plan 모드가 켜지는 순간, Gemini CLI는 자동으로 Gemini 3.1 Pro 모델로 라우팅을 전환합니다. 그리고 계획 승인 후 실행 단계에서는 속도 우선의 Flash 모델로 다시 내려옵니다. Plan → Pro, 실행 → Flash. 이 구조가 핵심입니다.
왜 중요하냐면, Pro 모델 요청도 같은 무료 한도 풀에서 차감되기 때문입니다. 코드베이스 분석 한 번에 여러 번의 모델 요청이 발생하는데, 그 요청들이 전부 하루 한도에서 빠져나갑니다. “읽기만 하는데 왜 한도가 줄었지?”라는 현상의 원인이 바로 여기 있습니다.
| 모드 | 사용 모델 | 파일 수정 | 한도 소진 속도 |
|---|---|---|---|
| Plan 모드 | Gemini 3.1 Pro | ❌ (계획 파일만) | 빠름 ↑ |
| 실행 단계 | Gemini 3 Flash | ✅ | 상대적으로 느림 |
| Auto-Edit 모드 | Auto (Flash 우선) | ✅ (즉시) | 중간 |
출처: geminicli.com/docs/cli/plan-mode#automatic-model-routing
인증 방식에 따라 하루 한도가 4배 벌어집니다
💡 공식 요금 문서와 실제 인증 구조를 교차해 보면 — 같은 무료 티어라도 선택에 따라 하루에 쓸 수 있는 양이 4배까지 차이 납니다.
공식 Quota 문서(geminicli.com/docs/resources/quota-and-pricing)에 명시된 수치는 이렇습니다.
| 인증 방식 | 일일 요청 한도 | 분당 요청 | 사용 가능 모델 |
|---|---|---|---|
| 구글 계정 로그인 (Gemini Code Assist) |
1,000회 | 60회 | 전체 Gemini 모델 패밀리 |
| API 키 (무료) | 250회 | 10회 | Flash 모델만 |
출처: geminicli.com/docs/resources/quota-and-pricing, 2026.03.22 기준
1,000회 대 250회, 딱 4배 차이입니다. Plan 모드가 Pro 모델로 라우팅되면 요청 건수가 여러 번 발생한다는 점을 감안하면, API 키 무료 방식은 실제 작업 세션 1~2개로 하루 한도가 소진될 수 있습니다. 그리고 API 키 무료 방식은 Flash 모델만 쓸 수 있어서, Plan 모드의 Pro 모델 라우팅 기능 자체가 제대로 작동하지 않습니다.
구글 계정으로 로그인하는 쪽이 모든 면에서 유리합니다. API 키 방식은 나중에 유료로 전환해 토큰당 과금하는 구조로 쓸 때 의미가 있습니다.
Plan 모드 3가지 진입 방법과 실제 흐름
Plan 모드에 들어가는 방법은 세 가지입니다. 터미널에서 /plan을 입력하거나, Shift+Tab으로 모드를 순환하거나 (Default → Auto-Edit → Plan 순서), 자연어로 “~에 대한 계획을 세워줘”라고 요청하는 방식입니다.
(출처: geminicli.com/docs/cli/plan-mode#how-to-enter-plan-mode)
Plan 모드가 켜진 상태에서 작업 흐름은 이렇습니다.
- 목표 제시 — “데이터베이스 마이그레이션 방법 조사해줘”처럼 목표를 입력합니다.
- 에이전트 조사 — 읽기 전용 도구(
read_file,grep_search,glob)로 코드베이스를 탐색합니다. - ask_user 질문 — 애매한 부분이 있으면 에이전트가 먼저 물어봅니다. 가정으로 진행하지 않습니다.
- 계획 파일 생성 —
~/.gemini/tmp/<project>/<session-id>/plans/경로에 Markdown 파일로 저장됩니다. - 검토·수정·승인 — Ctrl+X로 계획 파일을 직접 편집하거나, 대화창에 피드백을 입력합니다.
- 실행 — 승인하면 Plan 모드를 벗어나 실행 모드(Flash 모델)로 전환됩니다.
새로 도입된 ask_user 도구가 실용적입니다. 기존 AI 코딩 도구의 가장 흔한 실패 패턴은 에이전트가 의도를 추측해서 틀린 방향으로 구현하는 것이었습니다. ask_user는 에이전트가 추측 대신 먼저 물어보는 구조를 만들어줍니다. 설계 선택지나 설정 파일 위치처럼 에이전트가 확신할 수 없는 정보를 사람에게 물어보고 진행합니다.
Plan 모드를 끄고 싶다면 /settings에서 “Plan”을 검색해 토글 해제하면 됩니다. 끄면 Shift+Tab 순환에서도 제거됩니다.
CI/CD에서 Plan 모드를 쓰면 YOLO가 켜집니다
⚠️ 주의: 비대화형 환경(CI/CD, headless 스크립트)에서 Plan 모드를 실행하면 구현 단계에서 자동으로 YOLO 모드로 전환됩니다. 모든 도구 승인이 자동 처리됩니다.
공식 문서에 이 내용이 명시돼 있습니다.
“When exiting Plan Mode to execute the plan, Gemini CLI automatically switches to YOLO mode instead of the standard Default mode. This allows the CLI to execute the implementation steps automatically without hanging on interactive tool approvals.”
(출처: geminicli.com/docs/cli/plan-mode#non-interactive-execution)
대화형 터미널에서는 계획 승인 → 실행이 사람의 확인을 거칩니다. 그런데 GitHub Actions나 스크립트처럼 입력을 받을 수 없는 환경에서는 Plan 모드가 계획을 만든 뒤 자동으로 YOLO 모드로 전환해 실행합니다. 사람이 중간에 멈출 수 없습니다.
CI 환경에서 테스트 목적으로 Plan 모드를 돌리다가 실제 파일이 변경되는 상황이 생길 수 있습니다. 특히 다음 시나리오에서 주의가 필요합니다.
- 분석 단계만 원하는데 CI 파이프라인 안에서 Plan 모드를 실행한 경우
- 헤드리스 스크립트에서
gemini --approval-mode plan -p "..."를 호출한 경우
비대화형 환경에서 분석 결과만 원한다면 Plan 모드 종료 시점을 훅(AfterTool)으로 가로채거나, 계획 파일을 GCS에 저장하는 방식으로 제어하는 구조를 따로 만들어야 합니다. 공식 문서에 AfterTool 훅 예시가 있습니다.
Claude Code와 뭐가 다른가요 — 직접 비교
| 항목 | Gemini CLI (Plan 모드) | Claude Code |
|---|---|---|
| 무료 한도 | 1,000회/일 (구글 계정) | Pro 플랜 필요 (월 $20~) |
| 계획 모드 | Plan 모드 (별도 단계) | 대화 중 자연스럽게 설계 포함 |
| 코딩 정확도 | 들여쓰기·루프 오류 사례 보고 있음 | 복잡한 작업에서 더 안정적 |
| 응답 속도 | 빠름 (Flash 기반 실행) | 추론 중엔 다소 느림 |
| 생태계 통합 | Google Cloud·GitHub MCP 연동 | 범용 환경 |
| 성능 이슈 | 중간 작업도 13~14분 지연 보고 | 상대적으로 안정 |
출처: emergent.sh/learn/gemini-cli-vs-claude-code, github.com/google-gemini/gemini-cli/issues/22141, r/GeminiCLI
GitHub 이슈 #22141에는 React 폼 유효성 검사 수정처럼 작은 작업(파일 13개 수정)에서 단순 질문 하나에 13~14분이 걸렸다는 보고가 2026년 3월 12일 등록됐습니다. Google이 공식 답변을 내놓지 않은 부분입니다. 무거운 작업이 아니어도 느려지는 경우가 있어서, 속도에 민감한 개발 세션이라면 사전에 테스트해보는 편이 좋습니다.
솔직히 말하면, 지금 시점에서 Gemini CLI Plan 모드의 가장 큰 강점은 무료라는 점입니다. 설계·탐색용으로 무료 한도를 쓰고, 중요한 구현은 다른 도구로 넘기는 방식이 현실적입니다.
자주 나오는 질문 5가지
마치며 — 이 기능의 진짜 가치
다만 지금 당장 도입한다면 몇 가지를 미리 정리해두는 편이 좋습니다. 구글 계정으로 로그인할 것(API 키 무료 방식은 한도가 4분의 1), Plan 모드가 Pro 모델을 써서 한도를 빠르게 소진한다는 점, CI/CD 환경에서 Plan 모드를 켜면 실행 단계가 자동으로 YOLO로 전환된다는 점입니다.
무료 한도 안에서 설계·탐색용으로 쓰는 전략이 현실적입니다. 중요한 구현은 Claude Code 같은 다른 도구와 함께 쓰는 방식으로 각 도구의 강점을 조합하는 사람들이 많아지고 있습니다. 지금은 그런 과도기입니다.
📌 본 포스팅 참고 자료
- 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 공식 문서 — Quotas and Pricing
https://geminicli.com/docs/resources/quota-and-pricing/ - DevOps.com — Gemini CLI Plan Mode Separates Thinking From Doing (2026.03.12)
https://devops.com/gemini-cli-plan-mode-separates-thinking-from-doing-and-makes-read-only-the-default/ - GitHub — Gemini CLI Issue #22141 (성능 지연 보고, 2026.03.12)
https://github.com/google-gemini/gemini-cli/issues/22141
※ 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. Gemini CLI는 활발히 업데이트되는 오픈소스 프로젝트로, 버전 업데이트에 따라 한도·기능·모델 라우팅 구조가 달라질 수 있습니다. 최신 정보는 공식 문서(geminicli.com/docs)에서 확인하시기 바랍니다.
댓글 남기기