Gemini CLI 최신 버전
Gemini CLI Plan 모드, 무료로 3.1 Pro가 됩니다
Plan 모드를 켜는 순간 모델이 바뀝니다. 기획 단계에서 Gemini 3.1 Pro로 자동 전환되는 구조인데, 이걸 모르고 쓰면 절반만 쓰는 겁니다. 공식 문서에서 직접 확인한 내용입니다.
Plan 모드가 생기기 전 Gemini CLI의 구조적 약점
Claude Code는 Shift+Tab 두 번으로 Plan 모드에 진입하고, 코드에 손대기 전에 전략을 먼저 짜는 방식을 지원해 왔습니다. 반면 Gemini CLI는 요청이 들어오면 바로 코드를 건드리는 경향이 있어서 대형 리팩토링이나 DB 마이그레이션 같은 작업에서 실수 가능성이 높았습니다. 생각 없이 실행부터 하는 구조였다고 보면 됩니다.
2026년 3월 11일, Google이 Gemini CLI에 Plan 모드를 공식 추가했습니다. (출처: Google Developers Blog, 2026.03.11) 이제 이 공백이 메워졌는데, 단순히 Claude Code를 따라간 게 아니라 구조가 조금 다릅니다.
Plan 모드 작동 방식 — 공식 문서 기준
Plan 모드는 읽기 전용(read-only) 환경입니다. 이 모드에서 Gemini CLI는 파일을 탐색하고, 코드베이스를 분석하고, 의존성을 추적할 수 있지만, 실제 파일을 수정하거나 명령을 실행할 수 없습니다. 딱 하나 예외가 있는데, 계획서 자체는 Markdown 파일로 저장합니다. 기본 저장 경로는 ~/.gemini/tmp/<project>/<session-id>/plans/입니다. (출처: geminicli.com 공식 문서)
💡 공식 발표문과 실제 허용 도구를 같이 놓고 보니 이런 차이가 보였습니다
Plan 모드에서 사용 가능한 도구는 딱 정해져 있습니다. read_file, grep_search, glob 같은 읽기 전용 파일시스템 도구, 웹 검색, 서브에이전트 두 개(codebase_investigator, cli_help), 그리고 ask_user 도구입니다. 이 목록에 없는 도구는 정책 파일(plan.toml)을 직접 수정하지 않는 한 Plan 모드에서 실행되지 않습니다.
진입 방법은 세 가지입니다. 터미널에서 Shift+Tab을 눌러 모드를 순환하거나, 입력창에 /plan을 입력하거나, 자연어로 “이 기능에 대한 계획을 세워줘”라고 요청하면 됩니다. 기본값으로 이미 활성화되어 있어서 따로 설치나 설정을 건드릴 필요는 없습니다. (출처: geminicli.com/docs/cli/plan-mode, 2026.03.11)
계획이 완성되면 Ctrl+X로 외부 편집기를 열어 직접 수정하거나, 댓글을 달아 “Wait, 여기서는 기존 Logger 클래스를 써야 하지 않나?”같은 피드백을 남길 수 있습니다. Gemini CLI가 이 내용을 자동으로 읽고 계획을 수정합니다.
모델이 자동으로 바뀌는 구조, 이게 핵심입니다
Plan 모드의 가장 중요한 특징인데, 많은 글이 이 부분을 그냥 지나칩니다. Plan 모드에 진입하면 Gemini CLI가 자동으로 고추론 Pro 모델로 라우팅을 전환합니다. 공식 발표문에 이렇게 나옵니다. “With higher reasoning Pro models like the new Gemini 3.1 Pro model being used during planning to ensure robust architectural decisions and high-quality plans.” (출처: Google Developers Blog, 2026.03.11)
그리고 계획을 승인하고 구현 단계로 넘어가면, 이번엔 자동으로 고속 Flash 모델로 전환됩니다. 기획 품질은 Pro로, 구현 속도는 Flash로 — 이 두 가지를 사용자가 직접 설정하지 않아도 자동으로 분리해서 처리하는 구조입니다.
💡 “무료인데 Pro 모델?”이라고 생각했다면, 조건이 있습니다
자동 모델 라우팅은 auto 모델 설정을 사용할 때만 적용됩니다. 모델을 gemini-3.1-flash처럼 직접 지정해 두면 Plan 모드에서도 Flash가 그대로 사용됩니다. 모델을 고정해서 쓰는 경우 이 기능이 비활성화되므로 주의가 필요합니다. (출처: geminicli.com/docs/cli/plan-mode#automatic-model-routing)
이 라우팅 자동 전환을 끄고 싶다면 settings.json에서 "modelRouting": false로 설정하면 됩니다. 비용 통제가 중요한 환경이라면 이 옵션을 알아두는 게 좋습니다. Plan 단계에서 Pro 모델 요청이 늘어나면 유료 API 키 사용 시 청구 금액에 영향을 줍니다.
무료로 쓸 수 있는 한도 — 직접 계산했습니다
Plan 모드가 생기면서 Gemini CLI의 요청 소비 방식이 달라집니다. 계획 단계에서 Pro 모델 요청이 추가되기 때문에, 기존보다 하루 한도를 더 빨리 소진할 수 있습니다. 인증 방법별로 실제 한도를 정리하면 아래와 같습니다.
| 인증 방법 | 일일 한도 | 분당 한도 | 사용 모델 |
|---|---|---|---|
| 구글 계정 로그인 | 1,000회 | 60회 | Gemini 전 모델 |
| Gemini API 키 (무료) | 250회 | 10회 | Flash 전용 |
| AI Pro 구독 | 1,500회 | 120회 | Gemini 전 모델 |
| AI Ultra 구독 | 2,000회 | 120회 | Gemini 전 모델 |
(출처: geminicli.com/docs/resources/quota-and-pricing, developers.google.com/gemini-code-assist/resources/quotas)
여기서 주목할 부분이 있습니다. Gemini API 키로 인증하면 무료라도 Flash 모델만 사용됩니다. 즉, API 키 방식으로 Plan 모드를 쓰면 자동 모델 라우팅이 실질적으로 작동하지 않습니다. Pro 모델 접근이 가능한 자동 라우팅의 혜택을 받으려면 반드시 구글 계정으로 직접 로그인해야 합니다.
Reddit 실사용 데이터에서는 AI Pro 구독 사용자 기준으로 Gemini 3 Pro 메시지 한도가 24시간에 약 250회로 측정됐습니다. (출처: reddit.com/r/GeminiAI, 2025.11.30) 중간 규모 기능 추가 작업 하나에 약 20회 메시지가 사용된다고 할 때, 하루에 10~12개 작업이 상한선인 셈입니다.
Claude Code와 실제로 다른 점
Plan 모드 자체는 두 툴 모두 Shift+Tab으로 진입하는 방식이 비슷합니다. 그런데 내부 작동 방식에 차이가 있습니다. Claude Code의 Plan 모드는 모델 전환 없이 동일한 모델이 계획과 구현을 모두 담당합니다. 반면 Gemini CLI는 이번 업데이트에서 계획 단계에 Pro, 구현 단계에 Flash를 자동 분리하는 방식을 택했습니다.
💡 속도 비교에서 보통 Claude Code가 앞선다고 나오는 이유가 이것 때문일 수 있습니다
실측 비교(Composio, 2025.07)에서 Claude Code는 동일 프로젝트 완료에 1시간 17분, Gemini CLI는 2시간 2분이 걸렸습니다. 이 차이가 단순히 모델 성능 문제가 아니라, 당시 Gemini CLI에 Plan 모드가 없어 구조 파악 없이 바로 실행하다가 수정을 반복했기 때문일 수 있습니다. Plan 모드가 추가된 지금은 이 격차가 다를 가능성이 있습니다. (출처: composio.dev, 2025.07.02)
또 하나 다른 점은 read-only MCP 도구 지원입니다. Plan 모드 안에서 GitHub 이슈를 읽거나, Postgres 스키마를 조회하거나, Google Docs를 참고하는 게 가능합니다. Claude Code도 MCP를 지원하지만, Gemini CLI는 Plan 모드 전용 정책에서 read-only MCP만 허용하는 구분을 명시적으로 둔 게 특징입니다. 계획 단계에서 외부 데이터를 건드릴 수 없도록 막아놓은 셈입니다.
무료 한도 면에서는 Gemini CLI가 유리합니다. Claude Code의 무료 Pro 플랜은 Claude Opus 4.5 접근이 제한적인 반면, Gemini CLI 구글 계정 로그인 사용자는 하루 1,000회 요청에 Gemini 전 모델을 사용할 수 있습니다. (출처: shipyard.build/blog, 2026.01.15)
써보니 이 부분이 좀 아쉬웠습니다
Plan 모드 자체의 완성도는 높지만, 실사용에서 걸리는 부분이 몇 가지 있습니다.
⚠️ 실사용에서 주의할 점
- Google AI Plus는 지원 안 됩니다. 공식 문서에 “Tiers not listed above, including Google AI Plus, are not supported.”라고 적혀 있습니다. AI Pro와 AI Ultra만 지원합니다. (출처: geminicli.com/docs/resources/quota-and-pricing)
- 커스텀 plans 디렉토리 설정 시 수동 관리가 필요합니다. 기본 임시 경로에 저장된 계획서는 30일 후 자동 삭제되지만, 커스텀 경로를 지정했다면 직접 삭제해야 합니다.
- YOLO 모드에서는 자연어로 Plan 모드 진입이 안 됩니다.
enter_plan_mode도구 자체가 YOLO 모드에서 비활성화됩니다. - Conductor 확장은 아직 외부 설치 방식입니다. 복잡한 멀티스텝 워크플로를 원한다면 Conductor GitHub에서 별도로 설치해야 하며, 기본 내장은 “추후 예정”으로만 나와 있습니다.
Workspace 계정(구글 기업 계정)의 경우 Gemini 3 Pro가 아직 활성화되지 않은 경우가 있습니다. 실제 Reddit에서도 “개인 계정은 되는데 업무 계정은 안 된다”는 후기가 나옵니다. 공식 문서에서 별도 이유를 밝히지 않았습니다. 기업 환경에서 쓴다면 이 부분을 먼저 확인하는 게 좋습니다.
Q&A
마치며
다만 솔직히 말하면, 한국어 개발 커뮤니티에서 Gemini CLI 자체가 아직 Claude Code만큼 널리 쓰이지 않습니다. Plan 모드 출시 소식도 영어권에서 먼저 퍼졌습니다. 구글 계정 하나로 무료로 쓸 수 있고, Plan 단계에서 3.1 Pro까지 들어온다는 건 분명 쓸 이유가 생긴 겁니다.
Google Workspace 계정 사용자는 Gemini 3 Pro 접근이 안 될 수 있으니 먼저 확인이 필요합니다. 개인 구글 계정이라면 지금 바로 /plan을 입력해 볼 수 있습니다.
본 포스팅 참고 자료
- Google Developers Blog — Plan mode is now available in Gemini CLI (2026.03.11) 🔗 바로가기
- Gemini CLI 공식 문서 — Plan Mode 🔗 바로가기
- Gemini CLI 공식 문서 — Quotas and Pricing 🔗 바로가기
- Google for Developers Korea Blog — 3월 둘째 주 위클리 업데이트 (2026.03.13) 🔗 바로가기
- Composio — Gemini CLI vs Claude Code 실측 비교 (2025.07.02) 🔗 바로가기
본 포스팅은 2026년 3월 26일 기준으로 작성됐습니다. Gemini CLI Plan 모드는 Google이 지속적으로 업데이트하는 기능이며, 본 포스팅 작성 이후 서비스 정책·UI·기능·요금제가 변경될 수 있습니다. 최신 정보는 공식 문서에서 확인하세요.
댓글 남기기