Gemini CLI 최신 버전
Gemini CLI Plan 모드,
“읽기 전용”이 핵심인 이유
AI 코딩 에이전트가 파일을 망가뜨리기 전에 스스로 멈추게 만드는 방법이 생겼습니다. 2026년 3월 11일, 구글이 Gemini CLI에 Plan 모드를 정식 출시했습니다. 실행 전에 먼저 탐색·계획하고, 사람이 승인한 뒤에야 코드를 건드리는 구조입니다.
Plan 모드가 생긴 배경 — 에이전트가 먼저 망가뜨리던 문제
AI 코딩 에이전트가 가장 많이 욕을 먹는 순간은 코드를 고쳐줘서가 아닙니다. 물어보지도 않고 파일을 덮어쓰거나, 의존성을 잘못 파악한 채 리팩토링을 시작할 때입니다. Gemini CLI 커뮤니티에서 보고된 issue #7383을 보면 단일 에이전트 방식의 구조적 한계가 다섯 가지로 정리돼 있습니다. 체계적인 사전 계획 없음, 긴 작업 중 컨텍스트 손실, 의존성 처리 부실, 진행 상황 불투명, 중단된 작업 재개 불가 — 이 다섯 가지입니다.
구글은 이 문제에 읽기 전용 선행 탐색으로 답했습니다. Plan 모드는 에이전트가 코드베이스를 탐색하고, 의존성을 파악하고, 구현 계획을 마크다운으로 작성하는 동안 파일 수정을 아예 막아버립니다. 사람이 계획을 검토·승인한 뒤에야 편집 모드로 전환됩니다. “생각 먼저, 행동은 나중”이라는 원칙을 CLI 수준에서 강제하는 구조입니다.
💡 공식 발표문과 실제 커뮤니티 이슈를 같이 놓고 보니, Plan 모드는 기능 추가가 아니라 구조적 결함 보완으로 읽힙니다. 구글이 Plan 모드를 기본값(Default on)으로 설정한 것도 같은 맥락입니다.
2026년 3월 현재, AI 코딩 도구 시장 전반에서 “실행 전 검토”를 강제하는 흐름이 공통적으로 나타나고 있습니다. Anthropic의 Code Review 에이전트 팀, VS Code의 수명 주기 훅, 구글의 Plan 모드는 각각 다른 방식으로 같은 문제를 풀고 있습니다. (출처: DevOps.com, 2026.03.16)
Plan 모드의 실제 작동 방식 — 3단계 흐름
Plan 모드에 진입하는 방법은 세 가지입니다. 터미널에서 /plan을 입력하거나, Shift+Tab으로 모드를 순환하거나(Default → Auto-Edit → Plan), 자연어로 “~에 대한 계획을 세워줘”라고 요청하면 됩니다. 기본값이 Plan 모드로 설정돼 있어 별도 설정 없이도 바로 사용 가능합니다. (출처: Gemini CLI 공식 문서, geminicli.com/docs/cli/plan-mode)
① 탐색 단계 (읽기 전용)
에이전트는 read_file, grep_search, glob, codebase_investigator 같은 읽기 전용 도구만 사용할 수 있습니다. 로컬 파일뿐 아니라 MCP를 통해 GitHub 이슈, Postgres 스키마, Google Docs도 읽어올 수 있습니다. 파일 쓰기는 ~/.gemini/tmp/ 아래 plans 디렉터리 내 마크다운 파일에만 허용됩니다.
② 질문·정교화 단계 (ask_user 도구)
Plan 모드에서 새로 도입된 ask_user 도구는 에이전트가 가정 대신 질문을 하게 만듭니다. 숨겨진 설정 파일 위치, 아키텍처 선택지 중 선호도, 누락된 요구사항 같은 내용을 중간에 물어볼 수 있습니다. 기존 AI 코딩 에이전트의 가장 흔한 실패 패턴인 “잘못된 것을 자신 있게 구현하기”를 구조적으로 방지하는 장치입니다. (출처: Google Developers Blog, 2026.03.11)
③ 계획 검토·승인 단계
에이전트가 구현 계획을 마크다운 파일로 작성하면, Ctrl+X로 외부 편집기(VS Code, Vim 등)에서 직접 열어 수정할 수 있습니다. 단계를 지우거나 순서를 바꾸거나 주석을 남기면 에이전트가 이를 반영해 계획을 다듬습니다. 승인하면 편집 모드로 전환되면서 구현이 시작됩니다.
무료 1,000건이지만 실제로 쓸 수 있는 횟수는 다릅니다
구글 계정으로 로그인하면 하루 1,000건의 요청이 무료입니다. 직관적으로는 1,000번 명령을 쓸 수 있다고 생각하기 쉽습니다. 하지만 공식 문서에는 중요한 주석이 붙어 있습니다.
“에이전트 모드 또는 Gemini CLI 사용 시, 프롬프트 1회가 여러 번의 모델 요청으로 이어질 수 있습니다.”
(출처: Gemini CLI 공식 할당량 문서, geminicli.com/docs/resources/quota-and-pricing)
Plan 모드처럼 탐색·계획·검증을 단계별로 수행하는 작업은 명령 1회당 모델 요청이 3~5번 발생합니다. 실효 한도를 계산하면 이렇습니다.
| 작업 유형 | 요청당 모델 호출 수 | 1,000건 기준 실효 작업 수 |
|---|---|---|
| 단순 질의 (비에이전트) | 1회 | 1,000회 |
| 일반 에이전트 작업 | 약 3~5회 | 200~333회 |
| Plan 모드 (탐색+계획+구현) | 5회 이상 | 200회 미만 |
표 내 수치는 공식 문서 설명에 기반한 추정 범위입니다.
하루에 Plan 모드로 복잡한 작업을 20회만 해도 1,000건 한도가 금방 찹니다. 무료 1,000건은 단순 질의 기준이지, Plan 모드 풀 워크플로 기준이 아닙니다.
💡 Claude Code와 비교하면 무료/유료 경계가 반대입니다. Gemini CLI는 무료로 시작하지만 Plan 모드 집중 사용 시 한도 소진이 빠릅니다. Claude Code는 무료 티어가 아예 없고 월 최소 20달러부터 시작합니다. (출처: DataCamp 비교 분석, 2026.03.26)
API Key 방식으로 인증하면 무료 한도가 하루 250건으로 더 낮고, Flash 모델만 사용 가능합니다. 무료로 Plan 모드를 제대로 쓰려면 구글 계정 로그인(Gemini Code Assist 개인용) 방식이 유일한 선택입니다.
모델 라우팅의 조건 — Plan 단계에서 Pro가 붙는 타이밍
Plan 모드의 가장 눈에 띄는 기능 중 하나는 모델 자동 라우팅입니다. 공식 문서 설명은 이렇습니다. Plan 단계에서는 고추론 Pro 모델(Gemini 3.1 Pro)이 사용되고, 계획이 승인된 뒤 구현 단계에서는 빠른 Flash 모델로 자동 전환됩니다. (출처: Gemini CLI 공식 문서, geminicli.com/docs/cli/plan-mode/#automatic-model-routing)
여기에 중요한 조건이 있습니다. 이 자동 라우팅은 “auto 모델” 설정을 사용할 때만 작동합니다. 그리고 무료 구글 계정에서는 대부분의 요청이 Flash로 처리되며, Pro 접근은 복잡한 작업 판단 시에만 제한적으로 제공됩니다. 느린 응답이 2회 이상 발생하면 그 세션 내에서는 Flash로 전환되는 경우도 있습니다.
| 인증 방식 | Plan 단계 모델 | 구현 단계 모델 |
|---|---|---|
| 무료 구글 계정 | Flash (Pro는 제한적 제공) | Flash |
| Google AI Pro (~$20/월) | Gemini 3.1 Pro | Flash (자동 전환) |
| Vertex AI 유료 | Gemini 3.1 Pro | Flash (자동 전환) |
구글이 공식 발표에서 강조한 “Plan 단계 → Pro 모델, 구현 단계 → Flash 모델”이라는 라우팅은 유료 플랜에서 제대로 동작합니다. 무료 사용자에게는 Pro 라우팅이 보장되지 않습니다. 이 부분은 공식 발표문에는 잘 안 보이고 할당량 문서에 조건으로 들어가 있습니다.
💡 발표 자료와 실제 할당량 문서를 나란히 놓고 보니 이런 차이가 보였습니다. “Plan 모드는 Gemini 3.1 Pro를 쓴다”는 설명은 유료 플랜 기준입니다. 무료 계정은 대부분 Flash를 씁니다. (출처: Gemini CLI 할당량 문서, geminicli.com/docs/resources/quota-and-pricing)
자동 라우팅을 끄고 싶다면 settings.json에서 "modelRouting": false로 설정하면 됩니다. 특정 모델을 고정하고 싶을 때 유용합니다.
Claude Code Plan 모드와 나란히 놓고 보면
두 도구 모두 Plan 모드를 지원합니다. 진입 방식도 비슷합니다. Gemini CLI는 /plan 또는 Shift+Tab, Claude Code도 /plan 또는 Shift+Tab입니다. 계획을 마크다운 파일로 저장하고 외부 편집기에서 수정하는 방식도 동일합니다.
차이는 기본값과 비용에서 갈립니다. Gemini CLI Plan 모드는 기본값(Default on)이고 무료입니다. Claude Code Plan 모드는 토글 방식이며, 사용하려면 최소 월 20달러(Pro 플랜)가 필요합니다. 코드 품질 면에서는 SWE-bench Verified 기준 Claude Opus 4.6이 80.8%, Gemini 3.1 Pro가 80.6%로 거의 동일한 수준입니다. (출처: DataCamp 비교 분석, 2026.03.26)
| 항목 | Gemini CLI | Claude Code |
|---|---|---|
| Plan 모드 기본값 | 기본 활성 | 토글 방식 |
| 무료 티어 | 1,000건/일 | 없음 |
| Plan 단계 모델 (유료) | Gemini 3.1 Pro | Claude Sonnet 4.6 |
| 컨텍스트 창 | 100만 토큰 | 100만 토큰 |
| 오픈소스 | Apache 2.0 | 비공개 |
| 멀티 에이전트 | 내장 서브에이전트 | Agent Teams (Team/Enterprise) |
실제 작업 효율 면에서도 흥미로운 수치가 있습니다. Composio의 비교 실험에서 동일한 CLI 도구 빌드 작업에 Claude Code는 1시간 17분, Gemini CLI는 2시간 2분이 걸렸습니다. 단순 속도는 Claude Code가 앞섰지만, Gemini CLI는 무료 시작이라는 진입 장벽 차이가 있습니다. (출처: DataCamp, 2026.03.26)
Plan 모드를 제대로 쓰기 위한 설정 3가지
기본값으로도 쓸 수 있지만, 조금 더 손을 보면 달라집니다.
/settings → Default Approval Mode → Plan 으로 설정하면 세션 시작부터 Plan 모드가 유지됩니다. 매번 /plan을 입력할 필요가 없어집니다.
settings.json에서 "plan": {"directory": ".gemini/plans"}로 설정하면 계획 파일이 프로젝트 루트 안에 저장됩니다. 팀원과 계획을 git으로 공유할 때 편리합니다. 단, 커스텀 경로 지정 시 policy 파일도 함께 수정해야 합니다.
기본적으로 계획 파일을 포함한 세션 데이터는 30일 후 자동 삭제됩니다. /settings에서 Session Retention을 검색해 조정할 수 있습니다. 커스텀 경로를 지정한 경우 자동 삭제가 적용되지 않으므로 직접 관리가 필요합니다. (출처: Gemini CLI 공식 문서)
CI/CD 파이프라인 같은 비대화형 환경에서 Plan 모드를 쓰면 에이전트가 enter/exit plan mode를 자동 승인하고, 구현 단계에서 YOLO 모드(모든 도구 자동 승인)로 전환됩니다. 프로덕션 환경에서는 주의가 필요합니다.
Q&A
마치며
Gemini CLI Plan 모드는 무료라는 점 하나만으로도 시도해볼 이유가 충분합니다. AI 코딩 에이전트가 파일을 덮어쓰기 전에 계획을 먼저 보여주고, 사람이 수정할 수 있게 하는 구조는 실제로 큰 차이를 만듭니다.
솔직히 말하면, “무료 1,000건”이라는 숫자는 Plan 모드를 집중적으로 쓸 때는 생각보다 빨리 소진됩니다. Plan 모드 작업 1회당 모델 요청이 5회 이상 발생한다는 점을 감안하면, 실질적으로 하루 200회 미만의 완전한 Plan 워크플로가 가능합니다. 프로토타이핑이나 가벼운 작업이라면 무료로 충분하지만, 하루 종일 복잡한 리팩토링을 Plan 모드로 돌린다면 Google AI Pro 구독을 검토하는 게 현실적입니다.
2026년 3월 현재, AI 코딩 도구 시장에서 “실행 전 검토 강제”는 선택이 아닌 기본값이 되는 방향으로 움직이고 있습니다. Gemini CLI가 그걸 무료로 기본값으로 제공한다는 점은 주목할 만합니다.
- Plan mode is now available in Gemini CLI — Google Developers Blog (2026.03.11)
- Plan Mode 공식 문서 — geminicli.com
- Gemini CLI 할당량 및 요금 공식 문서 — geminicli.com
- Gemini CLI Plan Mode Separates Thinking From Doing — DevOps.com (2026.03.16)
- Gemini CLI vs. Claude Code: Differences and Use Cases (2026) — DataCamp
본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 본문의 수치 및 기능 설명은 2026.03.27 기준으로 작성되었으며, Gemini CLI 버전 업데이트에 따라 내용이 달라질 수 있습니다. 최신 정보는 공식 문서(geminicli.com/docs)에서 확인하시기 바랍니다.
댓글 남기기