2026.03.11 Plan 모드 출시
IT/AI
Gemini CLI Plan 모드, “기본 켜진다”는 말이 맞는 조건
2026년 3월 11일, 구글은 Gemini CLI에 Plan 모드를 정식 추가하며 “모든 사용자에게 기본 활성화”라고 발표했습니다. 그런데 막상 써보면 Plan 모드가 아예 뜨지 않는 상황이 있습니다. 공식 문서에 버젓이 나와 있는데, 대부분 이야기하지 않습니다. YOLO 모드와 공존이 안 된다는 점, Google AI Plus 구독이 Gemini CLI에서 아무 의미가 없다는 점, 그리고 Plan 중간에 모델이 조용히 교체된다는 점 — 이 세 가지만 알면 헤맬 일이 없습니다.
Plan 모드가 뭔지 30초로 정리하면
2026년 3월 11일 공식 출시된 Plan 모드(v0.33.0)는 이 문제를 해결하기 위해 쓰기 권한을 완전히 차단한 상태에서 코드베이스를 먼저 탐색하게 합니다. AI가 파일을 읽고, 의존성을 분석하고, 필요하면 질문까지 던진 뒤 구현 계획을 마크다운 파일로 만들어줍니다. 개발자가 그 계획을 검토하고 승인하면 그때 비로소 실제 수정이 시작됩니다.
공식 문서에 딱 이렇게 나옵니다. “Plan mode is a read-only mode that restricts Gemini CLI to a subset of its tools.” (출처: geminicli.com/docs/cli/plan-mode, 2026.03.11) 허용된 도구 목록도 명확합니다. read_file, grep_search, glob 같은 읽기 전용 도구와 ask_user만 쓸 수 있습니다. 쓰기 권한이 있는 도구는 오직 ~/.gemini/tmp/ 경로 아래 플랜 파일(.md)에만 허용됩니다.
| 허용 도구 유형 | 대표 도구 | 비고 |
|---|---|---|
| 파일 읽기 | read_file, list_directory, glob |
쓰기 불가 |
| 검색 | grep_search, google_web_search |
web_fetch는 확인 필요 |
| 서브에이전트 | codebase_investigator, cli_help |
코드베이스 분석 전용 |
| 사용자 상호작용 | ask_user |
Plan 모드 핵심 기능 |
| MCP 읽기 전용 | github_read_issue, postgres_read_schema |
외부 DB·이슈 조회 가능 |
출처: geminicli.com/docs/cli/plan-mode (2026.03.11 기준)
“기본 활성화”인데 작동 안 하는 조건
공식 블로그 발표문에는 “Plan mode is now enabled by default for all users!”라고 나옵니다. (출처: developers.googleblog.com, 2026.03.11) 이 문장 하나 때문에 “그냥 쓰면 되겠구나”라고 생각하기 쉬운데, 실제로는 작동하지 않는 조건이 딱 하나 있습니다.
💡 공식 발표문과 실제 동작을 같이 놓고 보니 이런 차이가 보였습니다
YOLO 모드(--yolo 또는 --approval-mode=yolo)로 Gemini CLI를 실행하면 enter_plan_mode 도구 자체가 등록되지 않습니다. /plan을 입력해도 반응이 없습니다.
공식 문서에 그대로 나와 있습니다. “This tool is not available when Gemini CLI is in YOLO mode.” (출처: geminicli.com/docs/cli/plan-mode, 2026.03.11) 빠른 테스트나 자동화 파이프라인에서 YOLO 모드를 즐겨 쓰는 경우라면, Plan 모드를 쓰려면 별도로 재시작해야 합니다. 두 모드는 애초에 공존 설계가 아닙니다.
Plan 모드 진입 방법은 세 가지입니다. Shift+Tab으로 승인 방식을 순환하거나(Default → Auto-Edit → Plan), /plan을 입력하거나, 자연어로 “계획 세워줘”라고 말하면 됩니다. 매번 Plan 모드로 시작하고 싶다면 /settings에서 Default Approval Mode를 Plan으로 바꾸거나, 실행 시 gemini --approval-mode=plan을 쓰면 됩니다.
| 승인 모드 | 파일 수정 | Plan 진입 | 주로 쓰는 상황 |
|---|---|---|---|
| Default | 승인 후 가능 | ✅ 가능 | 일반 작업 |
| Auto-Edit | 자동 승인 | ✅ 가능 | 빠른 반복 작업 |
| Plan | 읽기 전용 | ✅ 기본 상태 | 복잡한 기능 설계 |
| YOLO | 모두 자동 | ❌ 불가 | CI/CD, 스크립트 |
출처: geminicli.com/docs/cli/plan-mode (2026.03.11 기준)
Plan 중간에 모델이 바뀌는 이유
Plan 모드에서 가장 눈에 띄는 설계 중 하나가 자동 모델 라우팅입니다. 대부분 “Gemini CLI는 Gemini 3.1 Pro를 쓴다”고 알고 있는데, 실제로는 같은 세션 안에서 모델이 교체됩니다. 공식 문서에 이렇게 나옵니다.
💡 모델 라우팅과 종량제 비용을 같이 놓고 보면 이런 연결 고리가 보입니다
“Planning Phase: While in Plan Mode, the CLI routes requests to a high-reasoning Pro model… Implementation Phase: Once a plan is approved and you exit Plan Mode, the CLI automatically switches to a high-speed Flash model.” (출처: geminicli.com/docs/cli/plan-mode, 2026.03.11)
계획 단계에서는 Gemini 3.1 Pro가 쓰이고, 승인 후 실제 구현에 들어가면 Flash 모델로 전환됩니다. 속도와 비용을 동시에 최적화하는 구조입니다. 단, 이 자동 전환은 “Auto” 모델 설정일 때만 작동합니다. 특정 모델을 고정해 두면 라우팅이 비활성화됩니다. 끄고 싶다면 settings.json에서 "modelRouting": false로 설정하면 됩니다.
또 하나 — Plan 파일은 기본적으로 ~/.gemini/tmp/ 경로에 저장되고 30일 후 자동 삭제됩니다. 프로젝트 디렉터리 안에 남기고 싶다면 settings.json의 plan.directory 값을 바꿔야 하고, 그에 맞는 Policy 파일도 별도로 작성해야 합니다. 설정만 바꾼다고 끝나지 않습니다.
Google AI Plus 구독자가 놓치는 쿼터 문제
월 5,500원짜리 Google AI Plus 요금제로 Gemini CLI를 더 넉넉하게 쓸 수 있다고 생각하기 쉽습니다. 실제로 커뮤니티에서도 이렇게 알고 있는 사람이 많습니다. 하지만 공식 쿼터 문서에는 이렇게 나옵니다.
⚠️ 공식 문서 원문
“Supported tiers: Tiers not listed above, including Google AI Plus, are not supported.” (출처: geminicli.com/docs/resources/quota-and-pricing, 2026.03 기준)
Google AI Plus 구독은 Gemini CLI 쿼터에 적용되지 않습니다. 이 요금제를 지원할 계획이 있다고만 나와 있고, 시점은 공개되지 않았습니다.
Google AI Plus는 Gemini 웹 앱과 구글 One 스토리지 혜택이 중심입니다. Plan 모드를 포함한 Gemini CLI에서 Pro 모델을 안정적으로 쓰려면 Google AI Pro 요금제(월 29,000원, 한국 기준)가 필요합니다. (출처: one.google.com/intl/ko_kr/about/google-ai-plans/, 2026.03 기준)
| 로그인 방식 | 일일 요청 한도 | Plan 모드 Pro 라우팅 | 비고 |
|---|---|---|---|
| 구글 계정(무료) | 1,000회 | ✅ 적용 | 가장 유리한 무료 방법 |
| Google AI Plus ❌ | 미지원 | ❌ 미지원 | CLI에 적용 안 됨 |
| Gemini API Key(무료) | 250회 | ❌ Flash만 | Pro 라우팅 미적용 |
| Google AI Pro ✅ | 1,500회 | ✅ 적용 | 월 29,000원(한국 기준) |
출처: geminicli.com/docs/resources/quota-and-pricing (2026.03 기준) / one.google.com 요금제 페이지
특히 무료 API Key로 Plan 모드를 쓰면 Flash 모델만 호출됩니다. Plan 단계에서 Pro 모델 라우팅이 적용되려면 구글 계정 로그인(무료) 또는 AI Pro 이상이 필요합니다. 쿼터와 모델 품질, 두 가지가 연결되어 있습니다.
Claude Code·Cursor와 Plan 방식이 다른 점
AI 코딩 도구마다 “계획 후 실행” 개념은 있지만 구현 방식이 다릅니다. Claude Code는 “계획을 세우자”고 요청하면 AI가 텍스트로 단계를 나열해주는데, 이건 일반 대화 응답과 구조적으로 같습니다. 전용 모드가 아니라 프롬프트 레벨에서 처리됩니다.
Cursor의 경우 에디터 내 Composer가 계획과 실행을 혼합 처리하는 방식입니다. 코드 변경 미리보기는 있지만 “완전히 읽기 전용 상태에서 탐색 → 계획 파일 생성 → 명시적 승인 → 구현 전환”이라는 단계별 분리는 없습니다.
💡 세 도구의 “계획” 방식을 나란히 놓고 보면 이런 차이가 보입니다
Gemini CLI Plan 모드는 계획 단계를 별도 실행 환경으로 격리합니다. 계획 파일은 마크다운으로 저장되고, Ctrl+X로 에디터에서 직접 편집도 됩니다. 계획에 인라인 코멘트를 달아 피드백을 주면 AI가 재검토 후 수정합니다. 이 협업 편집 구조는 Claude Code나 Cursor에는 없습니다.
다만 실사용에서 불거진 이슈도 있습니다. GitHub 공식 이슈 트래커(#22141, 2026.03.12)에 올라온 사례를 보면, Auto 모드에서 1~3개 파일 수정 같은 작은 작업인데도 1~14분씩 멈추는 현상이 보고됐습니다. 특히 macOS 환경에서 구글 계정 브라우저 로그인 방식을 쓸 때 발생했고, 원인은 아직 공개되지 않았습니다. Plan 모드가 오버헤드가 없는 도구라고 보기는 아직 이릅니다.
| 항목 | Gemini CLI Plan | Claude Code | Cursor Composer |
|---|---|---|---|
| 전용 읽기 전용 모드 | ✅ | ❌ | ❌ |
| 계획 파일(Markdown) 생성 | ✅ | ❌ | ❌ |
| 계획 편집 후 AI 재검토 | ✅ | ❌ | ❌ |
| 계획→구현 모델 자동 교체 | ✅ (Pro→Flash) | ❌ | ❌ |
| 읽기 전용 MCP 도구 지원 | ✅ | 별도 설정 | 별도 설정 |
공식 문서 및 각 도구 스펙 기준 비교 (2026.03 기준)
Plan 모드 실전 흐름 — 직접 따라하기
실제로 Plan 모드를 써보면 흐름이 생각보다 명확합니다. 아래 단계는 공식 문서 기준입니다. (geminicli.com/docs/cli/plan-mode, 2026.03.11)
터미널에서 /plan 입력 또는 Shift+Tab으로 모드 전환
“이 데이터베이스를 마이그레이션할 계획을 세워줘”처럼 원하는 작업을 설명
ask_user 도구로 AI가 아키텍처 선택이나 설정 파일 위치를 물어봄 — 이 대화가 계획 품질을 결정합니다
~/.gemini/tmp/에 마크다운 파일 생성됨, Ctrl+X로 에디터에서 직접 편집 가능
“Yes, automatically accept edits” 선택 → Plan 모드 자동 종료, Flash 모델로 전환 후 구현 시작
이 흐름에서 실제로 유용한 포인트가 있습니다. 계획 파일에 직접 코멘트를 달 수 있다는 점입니다. “Wait, shouldn’t we use the existing Logger class here?”처럼 인라인 질문을 남기면 AI가 자동으로 감지하고 계획을 재수정합니다. 큰 기능을 개발할 때 팀 리뷰처럼 쓸 수 있는 방식입니다.
비대화형 환경(CI/CD 파이프라인, 헤드리스 스크립트)에서 Plan 모드를 쓸 때는 동작 방식이 달라집니다. 사용자 확인 없이 enter_plan_mode와 exit_plan_mode가 자동 승인되고, 구현 단계에서는 YOLO 모드로 자동 전환됩니다. (출처: geminicli.com/docs/cli/plan-mode, 2026.03.11) 이 자동 YOLO 전환은 CI/CD 환경 전용 동작이고, 일반 대화형 세션에서는 적용되지 않습니다.
⚙️ CI/CD 환경 실행 예시
gemini --approval-mode plan -p "분석하고 개선점 제안해"
출처: geminicli.com/docs/cli/plan-mode (2026.03.11)
자주 묻는 질문 5개
마치며
“기본 켜진다”는 말만 믿고 쓰다 보면 막히는 지점이 있습니다. YOLO 모드와 공존 불가, Google AI Plus 쿼터 미지원, API Key 환경에서의 Flash 전용 제한, Pro→Flash 자동 라우팅에 따른 종량제 비용 주의까지 — 어느 하나 공식 문서에 없는 이야기가 아닙니다. 쓰기 전에 확인하면 나중에 헤맬 일이 없습니다.
솔직히 말하면, 지금 단계에서 실용성이 가장 높은 시나리오는 복잡한 리팩터링이나 DB 마이그레이션 전에 Plan 모드로 먼저 코드베이스를 분석하는 용도입니다. 작은 작업에 매번 Plan 모드를 쓰기엔 오버헤드가 있고, 실제로 hang 현상도 보고되고 있습니다. 상황에 맞게 쓰는 게 맞습니다.
본 포스팅 참고 자료
- Google Developers Blog — Plan mode is now available in Gemini CLI
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 Cloud — Vertex AI Gemini Pricing
https://cloud.google.com/vertex-ai/generative-ai/pricing - GitHub Gemini CLI Discussions v0.33.0 릴리스 노트 (2026.03.11)
https://github.com/google-gemini/gemini-cli/discussions/22078
본 포스팅은 2026년 4월 2일 기준, Gemini CLI v0.35.3 및 공식 문서(2026.03.11)를 참고해 작성됐습니다. 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. Gemini CLI는 활발히 업데이트되는 오픈소스 도구로, 쿼터·모델 라우팅·Plan 모드 동작 방식이 이후 버전에서 달라질 수 있습니다. 최신 내용은 공식 문서에서 직접 확인하는 것을 권장합니다.
댓글 남기기