Gemini CLI v최신 기준
Gemini CLI Plan 모드, 기본 켜진다는 말이 틀린 조건이 있습니다
2026년 3월 11일, 구글이 Gemini CLI에 Plan 모드를 정식 추가했습니다. “기본 활성화”라는 문구가 눈에 띄지만, 실제로 쓰다 보면 예상과 다른 상황이 꽤 있습니다. Plan 모드가 작동하지 않는 조건, 무료 쿼터 함정, 그리고 모델이 중간에 교체된다는 사실까지 — 공식 문서에 그대로 나와 있는데 대부분 이야기하지 않습니다.
Plan 모드가 뭔지 30초로 정리하면
Gemini CLI는 터미널에서 AI와 함께 코딩하는 도구입니다. 이전까지는 프롬프트를 입력하면 AI가 곧바로 파일을 수정하거나 명령어를 실행하는 방식이었는데, 여기서 문제가 생겼습니다. 맥락을 충분히 파악하지 않은 채 코드를 건드리다 보니 예상치 못한 수정이 발생하거나 의존성 충돌이 생겼습니다.
2026년 3월 11일 공식 출시된 Plan 모드는 이 문제를 해결하기 위해 쓰기 권한을 완전히 차단한 상태에서 코드베이스를 먼저 탐색하게 합니다. 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)에만 허용됩니다.
“기본 활성화”인데 작동 안 하는 상황이 있습니다
공식 블로그 발표문에는 “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 모드 진입 명령이 애초에 없는 상태라, /plan을 입력해도 반응이 없습니다.
공식 문서에 이렇게 나옵니다. “Natural Language: Ask Gemini CLI to start a 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 공식 문서 기준 (2026.03.11)
Plan 중간에 모델이 바뀌는 이유
Plan 모드에서 가장 눈에 띄는 설계 중 하나가 자동 모델 라우팅입니다. 대부분 “Gemini CLI는 Gemini 3.1 Pro를 쓴다”고 알고 있는데, 실제로는 같은 세션 안에서 모델이 교체됩니다. 공식 문서에 이렇게 나옵니다.
— geminicli.com/docs/cli/plan-mode (2026.03.11 기준)
계획 단계에서는 Gemini 3.1 Pro가 쓰이고, 승인 후 실제 구현에 들어가면 Flash 모델로 전환됩니다. 속도와 비용을 동시에 최적화하는 구조입니다. 단, 이 자동 전환은 “Auto” 모델 설정일 때만 작동합니다. 특정 모델을 고정해 두면 라우팅이 비활성화됩니다. 끄고 싶다면 settings.json에서 "modelRouting": false로 설정하면 됩니다.
💡 발표문에서 짚지 않았던 부분인데, 실제 쓰기 비용과 직결됩니다
Pro 모델은 Flash보다 토큰당 비용이 훨씬 높습니다. Gemini API 종량제(Pay-As-You-Go)로 쓰는 경우, Plan 단계에서 복잡한 코드베이스를 탐색하면 예상보다 과금이 많이 쌓일 수 있습니다. 계획 자체가 길어질수록 Pro 모델 호출 비용이 늘어나는 구조입니다.
또 하나 — 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 웹 앱과 구글 One 스토리지 혜택이 중심입니다. Gemini CLI 쿼터 혜택은 지원 계획이 있다고만 나오고, 아직 적용되지 않았습니다. Plan 모드를 포함한 Gemini CLI에서 Pro 모델을 안정적으로 쓰려면 Google AI Pro 요금제(월 29,000원 한국 기준)가 필요합니다.
요금제별 Gemini CLI 실제 쿼터를 직접 비교하면 차이가 큽니다.
| 로그인 방식 | 일일 요청 한도 | 분당 한도 | 사용 모델 |
|---|---|---|---|
| 구글 계정(무료) | 1,000회 | 60회 | Gemini 계열 자동 |
| Google AI Plus ❌ | 미지원 | 미지원 | 적용 안 됨 |
| Gemini API Key(무료) | 250회 | 10회 | Flash 모델만 |
| Google AI Pro ✅ | 확장 적용 | 120회 | Gemini 계열 자동 |
출처: geminicli.com/docs/resources/quota-and-pricing (2026.03 기준) / Gemini Code Assist Standard: 1,500회/일, Enterprise: 2,000회/일
특히 무료 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 모드 실전 흐름 — 직접 따라하기
실제로 Plan 모드를 써보면 흐름이 생각보다 명확합니다. 아래 단계는 공식 문서 기준입니다. (geminicli.com/docs/cli/plan-mode, 2026.03.11)
- Plan 모드 진입: 터미널에서
/plan입력 또는Shift+Tab으로 모드 전환 - 목표 설명: “이 데이터베이스를 마이그레이션할 계획을 세워줘” 같이 원하는 작업을 설명
- AI의 질문에 답변:
ask_user도구로 AI가 아키텍처 선택이나 설정 파일 위치를 물어봄 — 이 대화가 계획 품질을 결정합니다 - 계획 파일 검토:
~/.gemini/tmp/에 마크다운 파일 생성됨,Ctrl+X로 에디터에서 직접 편집 가능 - 승인: “Yes, automatically accept edits” 또는 “Yes, manually accept edits” 선택 → Plan 모드 자동 종료 후 구현 시작
이 흐름에서 실제로 유용한 팁이 있습니다. 계획 파일에 직접 코멘트를 달 수 있다는 점입니다. “Wait, shouldn’t we use the existing Logger class here?”처럼 인라인 질문을 남기면 AI가 자동으로 감지하고 계획을 재수정합니다. 큰 기능을 개발할 때 팀 리뷰처럼 쓸 수 있는 방식입니다.
복잡한 멀티스텝 프로젝트라면 Conductor 익스텐션을 같이 쓰는 것도 방법입니다. 구글이 조만간 Conductor를 Gemini CLI 내장 기능으로 통합할 예정이라고 공식 발표했습니다. (출처: developers.googleblog.com, 2026.03.11) 지금은 별도 설치가 필요합니다.
비대화형 환경(CI/CD 파이프라인, 헤드리스 스크립트)에서 Plan 모드를 쓸 때는 동작 방식이 달라집니다. 사용자 확인 없이 enter_plan_mode와 exit_plan_mode가 자동 승인되고, 구현 단계에서는 YOLO 모드로 자동 전환됩니다. gemini --approval-mode plan -p "분석하고 개선점 제안해"처럼 쓰면 됩니다.
자주 묻는 질문 5개
마치며
Gemini CLI Plan 모드는 AI 코딩 도구에서 흔히 생기는 “일단 고쳐놓고 보는” 문제를 구조적으로 막으려는 시도입니다. 읽기 전용 탐색 → 계획 파일 생성 → 명시적 승인 → 구현이라는 흐름은 설계와 구현을 명확히 나누는 방식이고, 그 점에서 진지한 접근입니다.
다만 “기본 켜진다”는 말만 믿고 쓰다 보면 막히는 지점이 있습니다. 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 공식 문서 — Quotas and Pricing
https://geminicli.com/docs/resources/quota-and-pricing/ - Google Cloud — Gemini Code Assist Quotas and Limits
https://developers.google.com/gemini-code-assist/resources/quotas - GitHub Gemini CLI Issue #22141 — 성능 저하 보고 (2026.03.12)
https://github.com/google-gemini/gemini-cli/issues/22141
본 포스팅은 2026년 3월 27일 기준으로 작성됐습니다. 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. Gemini CLI는 활발히 업데이트되는 도구로, 쿼터·모델 라우팅·플랜 동작 방식이 이후 버전에서 달라질 수 있습니다. 최신 내용은 공식 문서를 직접 확인하는 것을 권장합니다.
댓글 남기기