Gemini CLI Plan 모드: “안전하다”더니
토큰 터지는 진짜 이유
읽기 전용으로 안전하게 계획만 짠다더니, 막상 쓰다 보면 쿼터가 예상보다 훨씬 빨리 사라집니다.
무료 티어 일 1,000회 (구글 계정 기준)
API Key 사용 시 일 250회
Plan 모드가 뭔지, 1분 만에 이해하기
2026년 3월 11일, 구글은 Gemini CLI에 Plan 모드(v0.33.0)를 공식 출시했습니다. 한 줄로 설명하면, “AI가 코드를 건드리기 전에 먼저 계획을 세우도록 가두는 읽기 전용 구역”입니다. 터미널에서 Shift+Tab을 누르거나 /plan을 입력하면 즉시 활성화됩니다.
기존 Gemini CLI는 명령을 내리면 AI가 바로 파일을 수정하거나 코드를 실행할 수 있었습니다. 그래서 “DB 마이그레이션 해줘”라고 했다가 예상치 못한 변경이 실행되는 사고가 잦았죠. Plan 모드는 이를 원천 차단합니다. read_file, grep_search, glob 같은 읽기 전용 도구만 허용하고, 자체 내부 계획 파일 외에는 어떤 파일도 수정할 수 없습니다.
그리고 이 모드에서는 AI가 단순히 혼자 탐색하는 것이 아니라, ask_user 도구를 통해 사용자에게 역으로 질문을 던집니다. “어떤 DB를 쓰나요?”, “설정 파일 위치가 어디인가요?” 같은 질문이 먼저 오는 구조입니다. 구현에 들어가기 전 요구사항을 확정하는 과정이 자동화된 셈입니다.
💡 이 분석은 공식 구글 개발자 블로그와 Gemini CLI 공식 changelog를 교차한 결과입니다.
Plan 모드의 실제 출시 시점은 2026년 2월 17일(v0.29.0) 프리뷰에서 시작해, 2026년 3월 11일(v0.33.0)에 기본 활성화 상태로 정식 전환됐습니다. 단순 “신기능 출시”가 아니라, 기본값이 바뀐 것이 핵심입니다.
Shift+Tab으로 켜는 법 — 설치부터 첫 실행까지
Gemini CLI가 처음이라면 먼저 npm으로 설치합니다. Node.js 18 이상이 필요합니다.
npm install -g @google/gemini-cli
설치 후 처음 실행하면 구글 계정 로그인 창이 열립니다. 여기서 반드시 구글 계정으로 로그인해야 일 1,000회 무료 쿼터를 받을 수 있습니다 (API Key 방식은 250회, 자세한 내용은 4번 섹션에서). 로그인 완료 후 터미널 안에서 아래와 같이 Plan 모드를 진입할 수 있습니다.
# 방법 1: 슬래시 명령어
/plan
# 방법 2: Shift+Tab으로 모드 순환 (Auto-Edit → Plan → Default)
# 방법 3: 자연어로
"이 프로젝트 마이그레이션 계획 세워줘"
# 항상 Plan 모드로 시작하고 싶다면
/settings → Default Approval Mode → Plan
Plan 모드에 진입하면 터미널 헤더 표시가 변경되고 AI가 먼저 코드베이스를 탐색하기 시작합니다. 계획이 완성되면 사용자가 승인한 뒤 일반 모드(Edit 모드)로 전환해 실제 구현으로 넘어가는 흐름입니다.
Plan 모드가 필요 없다면 /settings에서 "Plan"을 검색해 비활성화할 수 있습니다. 비활성화하면 Shift+Tab 순환에서 제거되고 enter_plan_mode 도구도 해제됩니다.
실제로 써보면 당황하는 이유: MCP 함정
구글 공식 발표에는 "Plan 모드가 읽기 전용 MCP 도구를 지원한다"고 나옵니다. 덕분에 GitHub 이슈를 읽거나 Postgres 스키마를 조회하거나 Google Docs를 참조해서 더 풍부한 계획을 세울 수 있다는 것이죠. 여기까지는 좋습니다.
문제는 실제로 MCP 서버를 연결해보면 "내가 붙인 MCP 서버가 읽기 전용으로 취급되지 않는다"는 상황이 발생한다는 점입니다. Reddit r/GeminiCLI에서 사용자 germanheller는 이렇게 지적했습니다: "MCP 제한이 진짜 문제다. 계획의 절반은 외부 상태(로그, DB 스키마, API 응답)를 조회해서 인폼드 플랜을 만드는 건데, 그게 안 된다."
이는 Gemini CLI의 Policy Engine을 통해 특정 MCP 도구를 명시적으로 읽기 전용으로 등록해야 해결됩니다. 기본 상태에서는 연결된 MCP 서버의 전체 도구가 Plan 모드에서 차단됩니다. 즉, 외부 서비스(Slack, Notion, GitHub 등)를 MCP로 연결해 쓰는 분들은 별도 설정 없이는 Plan 모드에서 그 도구들을 사용할 수 없습니다.
⚠️ 확인된 한계
Plan 모드에서 MCP 도구를 허용하려면 Policy Engine의 approval-modes 설정에서 해당 도구를 명시적으로 읽기 전용 허용 목록에 추가해야 합니다. 공식 문서: geminicli.com/docs/reference/policy-engine
이 부분은 공식 발표에서 충분히 강조되지 않은 내용입니다. 특히 n8n이나 Make 같은 자동화 도구를 MCP로 연결해 쓰는 분들, 혹은 DB 조회 MCP를 연결한 분들이라면 Plan 모드를 처음 사용할 때 반드시 이 설정을 확인하시기 바랍니다.
잠깐, 이게 사실입니다: 무료 쿼터의 두 얼굴
많은 분들이 "Gemini CLI는 무료"라고 알고 계십니다. 반은 맞고 반은 틀립니다. 로그인 방법에 따라 쿼터가 크게 달라집니다. 공식 문서(출처: developers.google.com/gemini-code-assist/resources/quotas)에 따른 무료 티어 쿼터를 비교하면 다음과 같습니다.
| 로그인 방법 | 일 최대 요청 | 분당 요청 | 사용 모델 |
|---|---|---|---|
| 구글 계정 로그인 | 1,000회 | 60회 | Gemini 3 Pro/Flash 자동 라우팅 |
| API Key (무료) | 250회 | 10회 | Flash 모델만 |
| Google AI Pro 구독 | 1,500회 | 120회 | Gemini 3 Pro/Flash 자동 라우팅 |
💡 공식 수치를 독자 언어로 해석하면:
API Key로 로그인하면 같은 "무료"처럼 보이지만 하루 쿼터가 4분의 1에 불과합니다. Plan 모드는 한 번 실행할 때 내부적으로 여러 서브에이전트 요청을 발생시키므로, 복잡한 플랜 하나가 10~30회 요청을 소모할 수 있습니다. API Key 무료 사용자라면 실질적으로 하루에 약 10~25회의 "플랜"만 돌릴 수 있는 셈입니다.
계산식으로 확인하면 이렇습니다.
→ 결과 해석: API Key 무료 사용자는 구글 계정 로그인 사용자와 비교해 동일한 "무료"라는 이름이지만 실제로 사용 가능한 일일 요청이 75% 적습니다. Plan 모드처럼 다단계 서브에이전트 호출이 발생하는 기능일수록 이 차이가 더욱 크게 체감됩니다. (출처: developers.google.com/gemini-code-assist/resources/quotas)
또 하나 주목할 점이 있습니다. Plan 모드 실행 중에는 Gemini CLI가 계획 단계에서 복잡한 추론이 필요할 경우 자동으로 Gemini 3.1 Pro 모델로 업그레이드해서 라우팅합니다. Pro 모델은 Flash보다 토큰 소비가 훨씬 높기 때문에, 쿼터가 예상보다 빠르게 줄어드는 이유 중 하나입니다. (출처: Gemini CLI v0.33.0 공식 릴리즈노트, developers.googleblog.com)
Conductor와 ask_user: Plan 모드를 200% 쓰는 법
Plan 모드를 그냥 켜고 "DB 마이그레이션 계획 세워줘"라고 입력하는 것도 유용하지만, 두 가지를 추가로 활용하면 훨씬 강력해집니다.
ask_user 도구: AI가 먼저 물어봅니다
Plan 모드에서 AI는 이제 일방적으로 계획을 내놓지 않습니다. ask_user 도구를 통해 목표 불명확 시 역으로 사용자에게 질문합니다. "어떤 ORM을 사용하나요?", "마이그레이션 롤백 전략이 필요한가요?" 같은 질문이 먼저 옵니다. 이를 통해 나온 최종 계획은 '대충 만든 계획'이 아니라 실제 프로젝트 맥락이 반영된 계획이 됩니다.
Conductor 확장: Plan 모드의 오케스트레이터
Conductor는 Gemini CLI의 확장(Extension)으로, Plan 모드와 ask_user 도구를 최대한 활용하는 멀티스텝 개발 오케스트레이터입니다. 복잡한 마이그레이션이나 대형 기능 구현에서 Conductor는 단계별 사전 점검(pre-flight checks)을 Plan 모드로 실행해 리스크 제로 상태를 만든 뒤, 각 마일스톤에서 사용자 확인을 ask_user로 받는 구조로 작동합니다.
# Conductor 설치
# 설치 후 Conductor와 Plan 모드는 자동으로 연동됩니다💡 다른 글에서 잘 다루지 않은 부분입니다.
Conductor는 Plan 모드가 내장화되기 전인 2025년 12월(v0.22.0)에 먼저 출시됐습니다. 당시에는 독립적인 계획 오케스트레이터였는데, Plan 모드가 내장되면서 이제 Conductor가 Plan 모드 위에서 동작하는 상위 레이어가 됐습니다. 구글이 공식적으로 "Conductor를 조만간 Gemini CLI 내장 모드로 통합할 예정"이라고 밝혔으므로, 향후 별도 설치 없이도 쓸 수 있게 될 가능성이 높습니다. (출처: geminicli.com/docs/changelogs/ v0.33.0 릴리즈노트)
Plan 모드에서 직접 만든 커스텀 계획 워크플로우도 가능합니다. enter_plan_mode와 exit_plan_mode 도구를 직접 호출하거나, Custom Policies를 통해 특정 조건에서만 Plan 모드가 활성화되는 워크플로우를 구성할 수 있습니다.
Claude Code vs Gemini CLI Plan 모드 — 실사용 비교
AI 코딩 에이전트 분야에서 가장 많이 비교되는 두 도구를 솔직하게 정리했습니다. Reddit과 실사용 커뮤니티 후기, 공식 수치를 교차해서 정리한 비교입니다.
| 항목 | Gemini CLI (Plan 모드) | Claude Code |
|---|---|---|
| 무료 여부 | ✅ 구글 계정 일 1,000회 무료 | 유료 구독 또는 API Key 필요 |
| 계획 모드 | 내장 Plan 모드 (v0.33.0~) | /plan 명령어 지원 |
| MCP 지원 | Plan 모드에서 별도 설정 필요 | 기본 지원 |
| 코드 품질 (복잡한 백엔드) | 일부 사용자 "루프·중간 포기" 보고 | 복잡한 백엔드·아키텍처 강점 |
| 프론트엔드·UI | Gemini 3.1 Pro 기반, 실사용 호평 | Sonnet 4.5 기준 양호 |
Reddit 커뮤니티 r/GeminiCLI의 실사용 후기를 보면, 프론트엔드 UI 작업에서는 Gemini CLI가 Claude Code보다 낫다는 평가가 많습니다. 반면 복잡한 백엔드 아키텍처나 장기 태스크에서는 Claude Code가 더 안정적이라는 의견이 우세합니다. "Gemini CLI is not at the same level as claude or codex"라는 부정적 의견도 있지만, 동시에 "복잡한 프론트엔드 개발에서는 Codex보다 낫다"는 반론도 함께 올라왔습니다.
개인적인 견해를 말씀드리자면, 지금 시점에서 Gemini CLI Plan 모드의 가장 큰 장점은 '무료'와 '속도'입니다. Claude Code가 API Key 비용이 부담스러운 분들이라면, Gemini CLI의 구글 계정 로그인 무료 티어로 먼저 AI 코딩 에이전트 워크플로우를 익히는 것이 합리적인 선택입니다. 다만 MCP 설정을 꼼꼼히 챙겨야 한다는 점은 잊지 마세요.
자주 묻는 질문 5가지
마치며: 지금 써야 하는 이유와 주의사항
Gemini CLI Plan 모드는 2026년 3월 현재 가장 합리적인 무료 AI 코딩 에이전트 옵션입니다. 구글 계정만 있으면 하루 1,000회 요청을 Gemini 3.1 Pro 모델로 무료 사용할 수 있다는 점은 분명한 강점입니다. Plan 모드 덕분에 "AI가 갑자기 파일을 다 바꿔버리는" 사고를 원천 차단하고 계획-검토-실행의 단계적 워크플로우를 구현할 수 있게 됐습니다.
단, 이 글에서 짚은 두 가지 함정은 반드시 기억하세요. 첫째, API Key로 로그인하면 같은 "무료"지만 쿼터가 4분의 1로 줄어듭니다. 반드시 구글 계정으로 로그인하세요. 둘째, MCP 서버를 연결해 사용하는 경우 Policy Engine 설정 없이는 Plan 모드에서 해당 도구들이 차단됩니다. 외부 서비스를 MCP로 연결했다면 policy-engine 문서를 먼저 읽어보시기 바랍니다.
AI 코딩 에이전트 시장은 지금 가장 빠르게 진화하고 있는 분야입니다. Gemini CLI는 이틀에 한 번 꼴로 업데이트가 나올 만큼 개발 속도가 빠릅니다. 오늘 한계가 내일은 해결될 수도 있습니다. 지금 Plan 모드를 직접 써보고 워크플로우를 잡아두는 것이, 나중에 유료 플랜으로 전환하든 다른 도구로 넘어가든 가장 유리한 출발점이 됩니다.
본 포스팅 참고 자료
- ① Google Developers Blog — Plan mode is now available in Gemini CLI (2026.03.11) — developers.googleblog.com
- ② Gemini CLI 공식 Changelog — v0.33.0, v0.32.0, v0.31.0 (2026.02~03) — geminicli.com/docs/changelogs
- ③ Google for Developers — Quotas and limits for Gemini Code Assist and Gemini CLI — developers.google.com/gemini-code-assist/resources/quotas
- ④ Gemini CLI 공식 요금 및 쿼터 페이지 — geminicli.com/docs/resources/quota-and-pricing
- ⑤ Google for Developers Korea Blog 3월 둘째 주 위클리 업데이트 (2026.03.13) — developers-kr.googleblog.com
본 포스팅은 2026년 3월 15일 기준 Gemini CLI v0.33.0 정보를 바탕으로 작성되었습니다. 본 포스팅 작성 이후 서비스 정책·UI·기능·쿼터 정책이 변경될 수 있으며, 최신 정보는 공식 문서(geminicli.com)에서 확인하시기 바랍니다. Gemini CLI는 오픈소스이며 거의 매주 업데이트가 진행됩니다.
댓글 남기기