Gemini CLI v0.1.x 기준
IT/AI
Gemini CLI Plan 모드, 무료로 쓰면 이 부분이 빠집니다
코드를 건드리기 전에 먼저 계획부터 세워주는 Plan 모드가 2026년 3월 11일 정식 출시됐습니다.
그런데 막상 써보려고 하면 놓치기 쉬운 조건이 하나 있습니다.
Plan 모드의 핵심 엔진인 Pro 모델이 2026년 3월 25일부로 무료 티어에서 제한됐습니다.
(Google 계정 기준)
사용 가능 모델
(단축키·명령어·자연어)
Plan 모드가 생긴 이유 — AI가 먼저 망가뜨리는 문제
AI 코딩 에이전트를 쓰다 보면 공통적으로 겪는 불편함이 있습니다. 무엇을 할지 물어보기도 전에 파일을 바꿔버린다는 점입니다. “DB 마이그레이션 계획을 세워줘”라고 했는데 에이전트가 실제로 파일을 수정하기 시작하는 상황, 한 번쯤 마주친 적 있을 겁니다.
(출처: Google Developers Blog, 2026.03.11)
여기서 중요한 점은 단순히 “실행 전 계획”을 세우는 수준이 아니라는 것입니다. `ask_user` 도구가 새로 추가되면서 에이전트가 가정을 세우는 대신 직접 질문을 던집니다. 아키텍처 선택지를 제시하거나 숨겨진 설정 파일 위치를 물어보는 식입니다. 계획이 완성되면 Markdown 파일로 저장되고, `Ctrl+X`로 직접 편집도 됩니다.
💡 공식 발표문과 실제 도구 제한 목록을 같이 놓고 보니, Plan 모드가 단순한 “확인 단계”가 아니라 별개의 실행 환경임을 알 수 있었습니다. 플랜 파일 저장 경로도 프로젝트 외부(~/.gemini/tmp/)로 분리됩니다.
Plan 모드 3가지 진입 방법과 실제 흐름
Plan 모드는 기본 활성화 상태로 출시됐습니다. 터미널을 열고 별도 설정 없이도 3가지 방법으로 바로 진입할 수 있습니다.
| 진입 방법 | 사용 방법 | 비고 |
|---|---|---|
| 키보드 단축키 | Shift+Tab 반복 |
Default → Auto-Edit → Plan 순 전환 |
| 명령어 | /plan 입력 |
즉시 진입 |
| 자연어 | “이 기능 계획부터 세워줘” 등 | enter_plan_mode 도구 자동 호출 |
처음부터 Plan 모드로 시작하고 싶다면 실행 시 플래그를 주면 됩니다.
gemini --approval-mode=plan
계획이 완성되면 에이전트가 Markdown 파일을 작성하고 승인을 요청합니다. 승인하면 자동으로 Plan 모드를 빠져나와 구현 단계로 전환됩니다. 마음에 안 들면 피드백을 남기거나 `Ctrl+X`로 파일을 직접 수정해 재검토를 요청할 수 있습니다. (출처: geminicli.com/docs/cli/plan-mode/, 2026.03.11)
Plan 모드에서 쓸 수 있는 도구와 쓸 수 없는 도구
Plan 모드는 정책 엔진(Policy Engine)으로 허용 도구를 엄격하게 관리합니다. 공식 문서에 명시된 허용 도구 목록은 아래와 같습니다.
(출처: geminicli.com/docs/cli/plan-mode/#tool-restrictions)
✅ 허용 도구
read_file,list_directory,globgrep_search,google_web_searchcodebase_investigator(서브에이전트)ask_user- 읽기 전용 MCP 도구 (조건부)
- 플랜 디렉토리 내
.md파일 쓰기
❌ 차단 도구
- 프로젝트 파일 쓰기·수정
- 셸 명령 실행 (기본값)
- 쓰기 권한 MCP 도구
- YOLO 모드 (
enter_plan_mode비활성)
⚠️ MCP 도구의 함정: 읽기 전용 MCP 도구(예: github_read_issue, postgres_read_schema)는 Plan 모드에서 사용 가능합니다. 그러나 기본 설정에서는 사용할 때마다 사용자 확인을 요구합니다. 자동 승인하려면 별도 정책 파일(~/.gemini/policies/)을 직접 작성해야 합니다. Reddit 커뮤니티에서 “MCP 제한이 Plan 모드의 실질적 공백”이라는 피드백이 나온 것도 이 이유입니다.
Auto Model Routing — 계획할 때와 실행할 때 모델이 달라집니다
Plan 모드에서 가장 흥미로운 설계는 자동 모델 전환(Auto Model Routing)입니다. 공식 문서에 명시된 동작 방식은 다음과 같습니다.
💡 공식 발표문과 모델 라우팅 문서를 함께 보면, 계획 단계에서 Pro를 쓰고 구현 단계에서 Flash로 내려가는 구조가 보입니다. 비용 효율과 품질을 단계별로 분리한 설계입니다.
| 단계 | 사용 모델 | 이유 |
|---|---|---|
| 계획 단계 (Plan 모드) | Pro 모델 (예: Gemini 3.1 Pro) | 높은 추론 능력 필요, 아키텍처 결정 |
| 구현 단계 (Plan 승인 후) | Flash 모델 | 속도 우선, 계획대로 실행만 하면 됨 |
Plan 모드를 승인하면 CLI가 자동으로 Flash로 전환해 구현을 처리합니다. 더 빠르게 돌아가는 이유가 여기 있습니다. (출처: geminicli.com/docs/cli/plan-mode/#automatic-model-routing) 이 전환을 원하지 않으면 settings.json에서 "modelRouting": false로 끄면 됩니다.
무료 Plan 모드의 실제 한계 — 공식 문서가 말하지 않은 것
여기가 핵심입니다. 블로그 대부분이 Plan 모드 출시 소식만 전달하고 끝냈는데, 실제로 무료로 쓰면 달라지는 조건이 있습니다.
2026년 3월 25일부터, Google은 Gemini CLI의 무료 티어에서 Pro 모델 접근을 차단했습니다. Gemini CLI 공식 GitHub Discussion(#22970, 2026.03.23 공지)에 게시된 내용입니다.
“Starting March 25, 2026, Gemini Pro models will only be accessible via paid subscriptions. Free tier users will be limited to Gemini Flash models.”
(출처: github.com/google-gemini/gemini-cli/discussions/22970, 2026.03.23)
Plan 모드가 설계 단계에서 Pro 모델을 자동으로 사용한다는 것을 앞서 확인했습니다. 즉, 무료 사용자는 Plan 모드를 켜도 고추론 Pro 모델 대신 Flash 모델로 계획을 세워야 합니다. 아키텍처 설계나 복잡한 의존성 분석에서 품질 차이가 생길 수 있는 지점입니다.
💡 출시 발표(3월 11일)와 무료 Pro 제한(3월 25일)이 불과 2주 간격으로 이어졌습니다. 두 공지를 함께 보면, Plan 모드가 처음부터 유료 전환을 염두에 두고 설계됐을 가능성이 있습니다.
무료 티어에서 Pro 모델을 쓰고 싶다면 Google AI Pro 또는 AI Ultra 요금제로 업그레이드해야 합니다.
API 키 방식을 쓸 경우 무료 티어는 Flash 모델만, 분당 10회, 일 250회로 제한됩니다.
(출처: geminicli.com/docs/resources/quota-and-pricing, 2026년 3월 기준)
Claude Code /plan과 비교했을 때 달라지는 점
(출처: kevinsimper.dk, 2025.11.27)
| 항목 | Gemini CLI Plan 모드 | Claude Code /plan |
|---|---|---|
| 진입 방법 | Shift+Tab, /plan, 자연어 | Shift+Tab (2회) |
| 플랜 저장 | Markdown 파일로 저장됨 (~/.gemini/tmp/) | 대화 내에 표시 (별도 파일 저장 없음) |
| MCP 지원 | 읽기 전용 MCP 허용 (기본 수동 확인) | MCP 외부 쿼리 가능 (유연) |
| 모델 전환 | Auto: 계획=Pro, 구현=Flash | 요금제 기반 고정 모델 |
| 무료 Plan 품질 | Flash 모델만 (2026.03.25~) | Pro 모델 (토큰 소모 방식) |
플랜 파일이 Markdown으로 저장된다는 점은 Gemini CLI만의 차이점입니다. 팀 협업이나 CI/CD 파이프라인에 계획 아카이브가 필요하다면 AfterTool 훅으로 GCS에 자동 저장하는 것도 가능합니다. Claude Code는 이런 구조가 없습니다.
반면 Reddit 커뮤니티(r/GeminiCLI, 2026.03.11)에서 실사용자들의 반응을 보면, “로그·DB 스키마 등 외부 상태를 조회해 계획에 반영하려는데 MCP 제한이 걸린다”는 의견이 나왔습니다. Claude Code의 `/plan`이 외부 쿼리에 더 유연한 이유가 바로 여기입니다.
자주 묻는 질문 5가지
마치며
솔직히 말하면, 출시 2주 만에 무료 Pro 모델 접근이 차단된 건 아쉬운 부분입니다. Plan 모드의 핵심 가치가 Pro 모델의 높은 추론 능력에 기반하는 만큼, 무료 사용자 입장에서는 Flash 기반 계획이 얼마나 신뢰할 수 있을지 직접 테스트해볼 필요가 있습니다.
MCP 도구를 DB 조회나 GitHub Issue 읽기 등에 적극적으로 쓰는 개발자라면, 기본 설정에서 매번 수동 확인을 요구한다는 점도 미리 알고 시작하는 게 좋습니다. 정책 파일 한 번만 세팅해두면 해결되는 문제이긴 하지만, 이런 내용이 공식 설명서 외에는 잘 안 알려져 있는 게 현실입니다.
본 포스팅 참고 자료
- Google Developers Blog — Plan mode 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 공식 문서 — Quota and Pricing
https://geminicli.com/docs/resources/quota-and-pricing - Google Gemini CLI GitHub — Service update discussion #22970 (2026.03.23)
https://github.com/google-gemini/gemini-cli/discussions/22970 - Kevin Simper — My experience using Claude Code vs Gemini CLI (2025.11.27)
https://www.kevinsimper.dk/posts/my-experience-using-claude-code-vs-gemini-cli
본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. Gemini CLI는 활발히 업데이트되는 오픈소스 프로젝트입니다. 최신 내용은 공식 문서(geminicli.com/docs) 및 GitHub 저장소에서 확인하는 것을 권장합니다. 본 포스팅의 수치·정책은 2026년 3월 26일 기준으로 작성됐습니다.
댓글 남기기