Gemini CLI v최신 / Plan Mode 기본 활성화
Gemini CLI Plan 모드, 안전하다는 말이 절반만 맞습니다
2026년 3월 11일, 구글이 Gemini CLI에 Plan 모드를 추가하며 “읽기 전용 안전 환경”을 강조했습니다. 실제로는 계획을 승인하는 순간 제한이 풀리고, 무료 사용자는 Plan 모드 자체가 예상과 다르게 동작합니다. 공식 문서에서 직접 확인한 내용을 정리했습니다.
Plan 모드가 뭔지, 3줄 요약
결론부터 말씀드리면, Plan 모드는 Gemini CLI가 코드를 건드리기 전에 먼저 계획을 짜도록 강제하는 읽기 전용 단계입니다. 2026년 3월 11일 구글 개발자 블로그 공식 발표 기준으로, 모든 Gemini CLI 사용자에게 기본값으로 활성화됐습니다. (출처: Google Developers Blog, 2026.03.11)
작동 방식은 단순합니다. /plan을 입력하거나 Shift+Tab으로 모드를 전환하면, 에이전트가 파일을 읽고 코드베이스를 분석하되 수정은 하지 않습니다. 분석이 끝나면 마크다운 파일 형태로 구현 계획을 저장해두고 승인을 기다립니다.
이 흐름 자체는 타당합니다. 기존 AI 코딩 도구들이 “일단 고치고 보는” 방식으로 코드베이스를 망가뜨리던 문제를 직접 겨냥한 설계입니다. 막상 써보면 다릅니다. 읽기 전용이 끝나는 순간부터가 진짜 핵심입니다.
읽기 전용이라는 말, 정확히 어디까지 맞나요
공식 문서에 허용 도구 목록이 명시돼 있습니다. Plan 모드에서 실행 가능한 것은 read_file, grep_search, glob 등 읽기 계열 도구뿐입니다. 파일 수정을 허용하는 write_file과 replace는 딱 하나 예외가 있습니다. (출처: geminicli.com 공식 문서)
💡 공식 문서와 실제 동작을 같이 놓고 보니 이런 차이가 보였습니다
계획 파일이 저장되는 경로인 ~/.gemini/tmp/<project>/<session-id>/plans/ 내 .md 파일에 한해서는 Plan 모드 중에도 쓰기가 허용됩니다. 즉, 읽기 전용은 “프로젝트 코드에 대한 읽기 전용”이지, CLI 전체가 완전히 잠기는 건 아닙니다. 이 부분을 모르면 Plan 모드가 막연히 “아무것도 못 하는 안전 모드”라고 오해하기 쉽습니다.
게다가 Plan 모드는 외부 데이터 소스와도 연결됩니다. 읽기 전용 MCP 도구를 통해 GitHub 이슈, PostgreSQL 스키마, Google Docs 등에 접근할 수 있습니다. 로컬 파일만 보는 게 아닙니다. 이 부분이 좋기도 하지만, 외부 연결이 생긴다는 점에서 민감한 환경에서는 별도 정책 설정이 필요합니다.
ask_user 도구도 눈여겨볼 만합니다. 에이전트가 분석 도중 “이 DB 마이그레이션을 어느 방향으로 처리할까요?”처럼 직접 질문을 던지는 기능입니다. 일방적으로 계획을 짜는 게 아니라 개발자와 대화하면서 계획을 조율합니다. 생각보다 실용적입니다.
승인 버튼 누르면 실제로 어떤 일이 벌어지나요
⚠️ 많은 분이 놓치는 부분
Plan 모드에서 계획을 승인하는 순간, Gemini CLI는 자동으로 편집 실행 모드로 전환됩니다. 그냥 편집이 아닙니다. 공식 문서에 딱 이렇게 나옵니다: 비대화형 환경에서는 Plan 모드 승인 후 YOLO 모드로 자동 전환됩니다. (출처: geminicli.com/docs/cli/plan-mode, Tool Restrictions 섹션)
YOLO 모드는 사용자 확인 없이 파일 수정과 명령어 실행을 모두 자동으로 처리하는 모드입니다. “안전한 계획 → 자동 전체 실행”으로 이어지는 구조입니다. 대화형 세션에서는 승인 후 Default 모드나 Auto-Edit 모드로 전환돼 수동 확인 단계가 남아있지만, CI/CD 파이프라인 같은 비대화형 환경에서 gemini --approval-mode plan -p "..." 형식으로 실행하면 계획 승인 이후 모든 실행 단계가 자동화됩니다.
이게 의도된 설계입니다. 파이프라인 자동화를 위해 만들어진 기능입니다. 문제는 이 사실을 모른 채 “Plan 모드니까 안전하겠지”라고 생각하고 자동화 스크립트에 넣었다가 실수 코드가 그대로 배포되는 상황입니다. 계획 검토를 꼼꼼히 하지 않으면 Plan 모드도 결국 자동 실행과 결과가 같아집니다.
💡 공식 발표문과 실제 사용 흐름을 같이 놓고 보니 이런 차이가 보였습니다
Plan 모드의 진짜 안전망은 읽기 전용 자체가 아니라, 사용자가 계획 파일을 열어서 직접 편집하고 잘못된 단계를 지우는 과정(Ctrl+X로 외부 에디터 오픈)입니다. 이 단계를 건너뛰고 “승인”만 누르면 계획 검토 없이 실행 단계로 넘어갑니다. 안전은 도구가 주는 게 아니라 개발자가 계획을 직접 검토하는 시간에서 나옵니다.
무료 사용자가 놓치기 쉬운 모델 라우팅 구조
Plan 모드는 플래닝 단계에서 자동으로 Gemini 3.1 Pro 모델로 라우팅됩니다. 구조적 결정과 아키텍처 분석에 추론 성능이 높은 Pro 모델을 쓰고, 실행 단계에서는 빠른 Flash 모델을 씁니다. (출처: Google Developers Blog, 2026.03.11)
여기서 문제가 생깁니다. 무료 Gemini API 키를 쓰는 경우, 2025년 12월 이후 Gemini 2.5 Pro 이상 모델의 무료 일일 할당량이 사실상 없어졌습니다. 구글 AI Studio 기준으로 Gemini 2.5 Pro의 무료 RPD(일일 요청 수)가 50회에서 0회로 변경됐습니다. (출처: Postype 사용자 문서 정리, 2025.12.07) 이 상태에서 Plan 모드를 무료 API 키로 실행하면 플래닝 단계가 바로 할당량 초과 오류로 막힙니다.
| 사용 방식 | Plan 모드 라우팅 모델 | 무료 사용 가능 여부 | 실행 단계 모델 |
|---|---|---|---|
| 구글 계정 로그인 (Google OAuth) | Gemini 3.1 Pro | 일 1,000회 무료 | Gemini Flash |
| API 키 방식 (무료 티어) | Gemini 3.1 Pro | Pro 모델 무료 할당 없음 | Gemini Flash |
| API 키 방식 (유료 티어) | Gemini 3.1 Pro | 사용량 과금 | Gemini Flash |
* 구글 계정으로 직접 로그인하는 Google OAuth 방식에서는 일 1,000회 무료 한도가 유지됩니다. API 키 방식과 다릅니다. (출처: Gemini CLI 공식 문서, twofootdog.tistory.com, 2026.01.07)
결론적으로 Plan 모드를 실질적으로 무료로 쓰려면 구글 계정으로 직접 로그인하는 방식(Google OAuth)이 유일한 선택지입니다. API 키 기반으로 사용하다가 Plan 모드가 막힌다면 이 구조 때문입니다.
Claude Code와 비교했을 때 Plan 모드가 강한 상황
솔직히 말하면, Gemini CLI와 Claude Code의 전반적인 코딩 성능 비교는 Claude가 아키텍처 분석에서 더 깊다는 평가가 많습니다. 그런데 Plan 모드가 특히 빛나는 구체적인 상황이 있습니다.
🔹 MCP 통합 읽기가 필요한 경우
Plan 모드는 GitHub 이슈, PostgreSQL 스키마, Google Docs를 읽기 전용으로 끌어와서 계획에 반영할 수 있습니다. DB 마이그레이션 계획을 짤 때 현재 스키마와 이슈 트래커를 동시에 참조하면서 계획을 만드는 흐름이 가능합니다. Claude Code 단독으로는 이 외부 소스 연결이 MCP 구성 없이는 쉽지 않습니다.
🔹 터미널 기반 CI/CD 파이프라인 자동화
비대화형 모드에서 gemini --approval-mode plan -p "텔레메트리 분석 후 개선사항 적용"처럼 파이프라인에 직접 넣으면 Plan → 자동 실행 흐름이 완성됩니다. DevOps 팀이 AI 에이전트를 파이프라인에 끼워 넣는 구조를 설계할 때, 터미널 네이티브 설계가 Claude Code보다 유리합니다.
🔹 Conductor 확장으로 복잡한 멀티스텝 작업
구글이 곧 Gemini CLI 내장 모드로 통합 예정인 Conductor는 Plan 모드를 활용해 마일스톤마다 사용자 확인을 받는 구조입니다. 복잡한 마이그레이션이나 멀티트랙 개발 작업에서, 계획 아티팩트를 파일로 남기고 재사용하는 방식이 효율적입니다. (출처: Google Developers Blog, 2026.03.11)
💡 두 도구를 같이 쓰는 팀이 실제로 있습니다
Reddit r/cursor 커뮤니티 기준으로 “Claude Code로 계획 세우고 Codex로 실행”하는 패턴이 공유됐는데, 이와 비슷하게 “Gemini CLI Plan 모드로 MCP 연동 계획 수립 → Claude Code로 구조적 분석과 실행”을 분리하는 팀도 있습니다. (출처: r/cursor, 2026.03.04)
CI/CD 파이프라인에서는 다르게 동작합니다
이게 핵심입니다. 공식 문서에 “Non-interactive execution”(비대화형 실행) 섹션이 별도로 존재합니다. CI/CD처럼 사용자 입력이 없는 환경에서 Plan 모드를 실행하면 두 가지가 자동으로 일어납니다. (출처: geminicli.com 공식 문서, Non-interactive execution 섹션)
enter_plan_mode와exit_plan_mode도구 실행이 사용자 확인 없이 자동 승인됩니다.- Plan 모드 종료 후 구현 단계 진입 시, Default 모드가 아닌 YOLO 모드로 자동 전환됩니다.
YOLO 모드 자동 전환은 파이프라인이 “사람 없이 끝까지 실행”돼야 하기 때문에 의도된 설계입니다. 파이프라인에서 Plan 모드를 쓴다는 건 계획 검토가 사전에 완료됐다는 가정 위에서 돌아가는 구조입니다. 이 부분이 중요합니다.
⚠️ 파이프라인에 Plan 모드를 넣기 전에 확인할 것
파이프라인에서 처음 Plan 모드를 쓸 때는 반드시 –dry-run 방식으로 계획 파일만 생성하고, 계획 파일을 사람이 검토한 뒤에 실행 단계를 트리거하는 2단계 구조를 권장합니다. 이렇게 하지 않으면 “Plan 모드를 썼으니 안전하다”는 착각 속에 자동 배포가 진행됩니다.
모델 라우팅도 파이프라인에서는 추가 비용 요소입니다. 플래닝 단계마다 Gemini 3.1 Pro 토큰이 사용됩니다. 규모 있는 CI/CD에서 자동화 루틴으로 Plan 모드를 자주 실행하면 예상보다 빠르게 API 비용이 올라갈 수 있습니다. settings.json에서 "modelRouting": false로 설정하면 Pro 모델 자동 라우팅을 끌 수 있습니다.
자주 나오는 질문 5가지
마치며
Gemini CLI Plan 모드는 방향성이 맞습니다. “일단 고치고 보는” AI 코딩 도구의 가장 큰 문제점을 정면으로 해결하려는 시도입니다. 읽기 전용 탐색 → 계획 수립 → 개발자 검토 → 실행이라는 흐름은 엔터프라이즈 환경에서 특히 필요한 안전망입니다.
그런데 이 포스팅에서 정리한 두 가지는 실제로 써보기 전에 알아야 합니다. 첫째, 승인 이후에는 읽기 전용이 풀리고 특히 비대화형 환경에서는 YOLO 모드로 자동 전환됩니다. 안전은 계획 파일을 검토하는 시간에서 나옵니다. 둘째, 무료로 Plan 모드를 제대로 쓰려면 API 키가 아닌 구글 계정 직접 로그인 방식이어야 합니다.
이 부분 모르고 들어가면, Plan 모드가 제공하는 안전감이 착각으로 끝날 수 있습니다. 기능 자체는 좋습니다. 쓰기 전에 구조를 이해하고 써야 한다는 게 핵심입니다.
본 포스팅 참고 자료
- Google Developers Blog — Plan mode is now available in Gemini CLI (2026.03.11)
- Gemini CLI 공식 문서 — Plan Mode 상세 문서
- DevOps.com — Gemini CLI Plan Mode Separates Thinking From Doing (2026.03.16)
- Emergent.sh — Gemini CLI vs Claude Code 비교 가이드 (2026)
- InfoWorld — Gemini CLI introduces plan mode (2026.03.12)
본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 본 포스팅은 2026년 3월 22일 기준으로 작성됐으며, Gemini CLI 공식 문서 및 Google Developers Blog 발표 내용을 바탕으로 합니다. 무료 API 한도는 구글의 정책 변경에 따라 달라질 수 있으니 최신 공식 문서를 확인하세요.
댓글 남기기