Gemini CLI 최신 버전 기준
Gemini CLI Plan 모드, 쓰면 쓸수록 더 비싸지는 조건 있습니다
2026년 3월 11일, Google이 Gemini CLI에 Plan 모드를 공식 추가했습니다. 읽기 전용으로 코드베이스를 안전하게 분석한 뒤 계획서를 만든다는 개념인데, 공식 문서를 뜯어보니 “안전하고 가볍게 쓸 수 있다”는 인상과 다른 부분이 2가지 있었습니다.
Plan 모드가 정확히 뭔지부터
Gemini CLI Plan 모드는 AI 에이전트가 코드베이스를 수정하기 전에 읽기 전용으로만 동작하는 실행 모드입니다. 파일을 읽고, 패턴을 검색하고, 문서를 확인하는 것까지만 가능하고, 파일 변경은 자체 계획서(Markdown) 저장 경로에만 허용됩니다. (출처: Google Developers Blog, 2026.03.11)
기존 AI 코딩 에이전트의 가장 흔한 실패 패턴은 “의도를 확인하지 않고 먼저 수정부터 시작하는 것”이었습니다. Plan 모드는 이 문제를 구조적으로 막습니다. 에이전트가 코드베이스 전체를 탐색한 뒤 ask_user 툴로 방향을 물어보고, 최종 계획서를 마크다운 파일로 출력합니다.
계획서를 승인하면 그때부터 편집 모드로 전환됩니다. 취소하면 코드에는 아무것도 남지 않습니다. 대규모 리팩토링이나 DB 마이그레이션처럼 “실수하면 되돌리기 어려운 작업” 전 단계로 쓸 수 있습니다.
실제로 어떻게 켜는가 — 3가지 방법
2026년 3월 11일 출시 이후 Plan 모드는 모든 사용자에게 기본 활성화되어 있습니다. (출처: geminicli.com/docs/cli/plan-mode, 2026.03.11) 별도 설정 없이도 켜져 있다는 뜻입니다.
진입 방법은 세 가지입니다.
① 터미널에 /plan 입력
② Shift+Tab 으로 모드 순환 (Default → Auto-Edit → Plan)
③ 자연어로 “이 기능을 추가하려는데 먼저 계획을 세워줘”라고 입력
매번 Plan 모드로 시작하고 싶다면 /settings에서 Default Approval Mode를 Plan으로 바꾸거나, 런치 명령어에 gemini --approval-mode=plan을 붙이면 됩니다.
반대로 Plan 모드를 아예 끄고 싶다면 /settings에서 “Plan”을 검색해 토글하면 됩니다. 그러면 Shift+Tab 로테이션에서도 제거됩니다. 본인만의 계획 프로세스가 있다면 꺼두는 게 더 깔끔합니다.
Plan 모드에서 쓸 수 있는 도구와 안 되는 도구
공식 문서에 허용된 툴 목록이 명확하게 나와 있습니다. 허용 범위를 정확히 알아야 이 모드를 제대로 활용할 수 있습니다. (출처: geminicli.com/docs/cli/plan-mode)
| 구분 | 허용 여부 | 주요 툴 |
|---|---|---|
| 파일 읽기 | ✅ 가능 | read_file, list_directory, glob |
| 검색 | ✅ 가능 | grep_search, google_web_search |
| 계획서 작성 | ✅ 제한적 가능 | .md 파일, plans 디렉터리 한정 |
| 파일 편집 | ❌ 불가 | write_file (plans 외), replace |
| 셸 명령어 실행 | ❌ 기본 불가 | policy로 git status 등은 허용 가능 |
| MCP 툴 | ⚠️ 읽기 전용만 | github_read_issue, postgres_read_schema 등 |
중요한 것은 MCP 툴 허용 범위입니다. 읽기 전용으로 표시된(readOnlyHint = true) MCP 툴만 Plan 모드에서 작동하는데, 이 항목은 기본적으로 사용자 승인이 필요합니다. 자동 승인이 아닙니다. DB 스키마를 조회하거나 GitHub 이슈를 읽으려 해도 매번 확인 창이 뜹니다.
모델이 자동으로 바뀐다는 것, 비용과 연결됩니다
💡 공식 발표문과 실제 과금 구조를 같이 놓고 보니 이런 흐름이 보였습니다. Plan 모드가 가볍다는 인상과 달리, 내부적으로는 가장 무거운 모델이 배정됩니다.
Gemini CLI에서 모델을 auto로 설정해두면, Plan 모드 진입 시 자동으로 Gemini 3.1 Pro가 배정됩니다. 공식 문서에 정확히 이렇게 나옵니다. (출처: geminicli.com/docs/cli/plan-mode, Automatic Model Routing 섹션) 구조적인 분석과 고품질 계획서를 위해 추론 능력이 높은 Pro 모델을 쓴다는 설명입니다.
반면 계획서를 승인하고 구현 단계로 넘어가면 자동으로 고속 Flash 모델로 전환됩니다. “전략은 Pro, 실행은 Flash”라는 구조입니다. 처음에 Plan 모드를 가볍게 탐색용으로 쓰려고 켰더라도, 실제로 돌아가는 건 API 기준으로 가장 비싼 Pro 모델입니다.
⚠️ 자동 모델 전환을 끄는 방법
settings.json에서 "plan": {"modelRouting": false}로 설정하면 자동 전환이 비활성화됩니다. API Key 방식으로 사용한다면 이 옵션을 먼저 확인하는 게 좋습니다. (출처: geminicli.com/docs/cli/plan-mode)
Google 계정으로 로그인한 무료 플랜(일 1,000회 요청)은 모델 요청 횟수로 과금되기 때문에 Flash든 Pro든 요청 1회가 동일하게 카운트됩니다. 그런데 Gemini API Key 방식(종량제)으로 쓰는 경우엔 토큰당 과금이므로 Plan 모드에서 Pro 모델이 돌면 비용이 올라갑니다. 현재 Gemini 3.1 Pro API 가격은 입력 $2.00/100만 토큰, 출력 $12.00/100만 토큰입니다. (출처: Google Cloud Vertex AI 가격 페이지, 2026.03 기준)
Claude Code /plan과 직접 비교한 수치
💡 두 도구를 같은 작업에 돌렸을 때 나온 실측 수치를 공식 비교 자료에서 직접 확인했습니다. Gemini CLI가 더 오래 걸리고 더 비쌌습니다.
InventiveHQ 팀이 Express.js API 12개 엔드포인트에 입력 유효성 검사·에러 핸들링·속도 제한·테스트를 추가하는 동일 작업을 세 도구로 측정했습니다. (출처: inventivehq.com/blog/gemini-vs-claude-vs-codex-comparison, 2026.02.13)
| 도구 | 소요 시간 | 비용 (API) | 개입 횟수 |
|---|---|---|---|
| Claude Code (Opus 4.6) | 1시간 17분 | $4.80 | 0회 |
| Gemini CLI (Gemini 3 Pro) | 2시간 4분 | $7.06 | 3회 |
| Codex CLI (GPT-5.3-Codex) | 1시간 41분 | $5.20 | 0회 |
Gemini CLI가 Claude Code보다 $2.26 더 비쌌습니다. 같은 작업에 47분 더 걸렸고, 중간에 3번 직접 수동으로 개입해야 했습니다. 이 비교에서 Plan 모드가 별도로 켜져 있진 않았지만, Plan 모드가 Pro 모델을 자동으로 배정한다는 구조를 감안하면, Plan 모드를 긴 세션에서 쓸수록 이 비용 차이는 더 벌어질 수 있습니다.
참고로 Claude Code도 /plan 명령어를 지원합니다. Reddit 커뮤니티(r/GeminiCLI)에서 한 사용자가 “Gemini CLI Plan 모드가 Claude Code의 /plan을 따라잡고 있다”고 표현했지만, 동시에 “MCP를 조회하려면 읽기 전용 여부와 무관하게 매번 승인이 필요한 건 아직 차이”라고 지적했습니다. (출처: r/GeminiCLI, 2026.03.11)
MCP가 막힌다는 것, 생각보다 큰 제약입니다
💡 “계획 단계에서 외부 시스템도 조회할 수 있다”고 홍보하지만, 실제 MCP 동작 방식은 그보다 제한적입니다. 커뮤니티 반응을 보면 이 부분에서 기대와 다르다는 목소리가 있었습니다.
Plan 모드는 읽기 전용 MCP 툴을 지원한다고 명시합니다. GitHub 이슈 조회, PostgreSQL 스키마 확인, Google Docs 검색 등이 가능하다는 설명입니다. 그런데 공식 문서를 보면 이 MCP 툴들은 기본적으로 사용자 확인이 필요합니다. 자동 승인이 아닙니다. (출처: geminicli.com/docs/cli/plan-mode, Tool Restrictions 섹션)
Reddit 사용자 germanheller는 이렇게 짚었습니다. “Plan의 가치 절반은 외부 상태(로그, DB 스키마, API 응답)를 조회해서 계획에 반영하는 것인데, MCP 제약이 그 부분을 실질적으로 막는다.” (출처: r/GeminiCLI, 2026.03.11) 자동 승인 정책을 직접 policy 파일로 설정하면 해결할 수 있지만, 기본 상태에선 매번 확인창이 뜹니다.
자동 승인 설정은 ~/.gemini/policies/mcp-read-only.toml에 아래처럼 추가하면 됩니다.
[[rule]]
toolName = "*"
mcpName = "*"
toolAnnotations = { readOnlyHint = true }
decision = "allow"
priority = 100
modes = ["plan"]
이 설정 없이는 Plan 모드에서 외부 시스템을 조회할 때마다 수동 확인이 필요합니다. 실제 현업에서 DB 스키마를 15번 조회하는 계획을 세운다면, 15번 승인을 눌러야 합니다.
자주 묻는 것들 — Q&A
Q. Plan 모드는 유료인가요?
무료입니다. 모든 사용자에게 기본 활성화되어 있습니다. Google 계정으로 로그인하면 하루 1,000회 요청까지 무료로 쓸 수 있고, Plan 모드 사용도 이 안에 포함됩니다. 단, API Key 방식(종량제)으로 쓴다면 Plan 모드에서 Pro 모델이 배정되므로 토큰 비용이 발생합니다.
Q. Plan 모드에서 만든 계획서는 어디에 저장되나요?
기본 경로는 ~/.gemini/tmp/<project>/<session-id>/plans/입니다. 프로젝트 디렉터리 외부에 저장되므로 코드베이스를 건드리지 않습니다. 원하면 settings.json에서 .gemini/plans처럼 프로젝트 내부로 경로를 바꿀 수 있는데, 이 경우엔 policy 파일도 함께 수정해야 합니다. (출처: geminicli.com/docs/cli/plan-mode)
Q. Plan 모드 중에 계획서를 직접 수정할 수 있나요?
가능합니다. Ctrl+X를 누르면 설정된 외부 에디터(VS Code, Vim 등)가 열리면서 계획서를 직접 편집할 수 있습니다. 저장하고 닫으면 Gemini CLI가 변경사항을 자동으로 감지하고 전략을 조정합니다. 자연어 대화보다 세밀한 조정이 필요할 때 이 방법이 더 빠릅니다.
Q. CI/CD 파이프라인에서도 Plan 모드를 쓸 수 있나요?
쓸 수 있습니다. 비대화형 환경에서는 Plan 모드가 자동 전환 방식으로 동작하고, 구현 단계로 넘어갈 때 자동으로 YOLO 모드(전자동 실행)로 전환됩니다. 명령어 예시는 gemini --approval-mode plan -p "텔레메트리 분석 후 개선안 제시"입니다. (출처: geminicli.com/docs/cli/plan-mode, Non-interactive execution 섹션)
Q. Conductor 확장이란 무엇이고, Plan 모드와 어떻게 연결되나요?
Conductor는 Gemini CLI 공식 확장(github.com/gemini-cli-extensions/conductor)으로, 대규모 프로젝트를 “트랙” 단위로 쪼개 관리하는 스펙 주도 개발 워크플로우를 지원합니다. Plan 모드를 리서치 단계로 활용하고 ask_user 툴로 중요한 결정을 확인받는 구조입니다. Google은 Conductor를 Gemini CLI 내장 기능으로 만들 계획도 있다고 밝혔습니다. (출처: developers.googleblog.com, 2026.03.11)
마치며
Gemini CLI Plan 모드는 AI 코딩 에이전트의 가장 흔한 문제, 즉 “묻지도 않고 수정부터 시작하는 것”을 막기 위한 구조적 해법입니다. 읽기 전용으로 탐색하고, 계획서를 먼저 만들고, 승인 후 구현한다는 흐름은 대규모 변경 전에 확실히 유용합니다.
다만 두 가지는 써보기 전에 알고 있는 게 좋습니다. 첫째, Plan 모드는 내부적으로 Gemini 3.1 Pro가 배정됩니다. 가볍게 탐색하려고 켰다가 API 비용이 예상보다 나올 수 있습니다. API Key 종량제 사용자는 modelRouting 설정을 먼저 확인하세요. 둘째, MCP를 통한 외부 시스템 조회는 기본 설정에서 매번 승인이 필요합니다. DB나 GitHub를 자주 조회하는 계획이라면 policy 파일을 미리 잡아두는 게 훨씬 편합니다.
Claude Code와 비교하면 아직 자율성과 첫 시도 정확도에서 차이가 있지만, 무료 플랜에서 이 수준의 기능을 쓸 수 있다는 점은 Gemini CLI의 분명한 강점입니다. Plan 모드 덕분에 DB 마이그레이션 같이 신중해야 할 작업에 무료로 접근할 수 있는 도구가 하나 더 생겼습니다.
본 포스팅 참고 자료
- Plan mode is now available in Gemini CLI — Google Developers Blog (2026.03.11)
- Plan Mode Documentation — geminicli.com (2026.03 기준)
- Gemini CLI Quota and Pricing — geminicli.com (2026.03 기준)
- Gemini CLI vs Claude Code vs Codex — InventiveHQ (2026.02.13)
- Gemini CLI Plan Mode Separates Thinking From Doing — DevOps.com (2026.03.16)
본 포스팅은 2026년 03월 24일 기준 공개된 정보를 바탕으로 작성되었습니다. 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. Gemini CLI는 오픈소스 프로젝트로 업데이트가 수시로 이루어지며, 최신 정보는 공식 문서(geminicli.com)에서 확인하시기 바랍니다.
댓글 남기기