IT/AI
Gemini CLI Plan 모드,
안 되는 경우가 있습니다
기본값이 됐다고 해서 항상 작동하는 건 아닙니다. 2026년 3월 11일 구글이 Plan 모드를 모든 사용자의 기본 설정으로 전환했지만, 실제로 쓰다 보면 분명히 막히는 상황이 생깁니다. 어떤 조건에서 어떻게 막히는지, 공식 문서와 실사용 데이터를 교차해서 정리했습니다.
Plan 모드가 기본값이 된 배경
결론부터 말하면, Plan 모드는 AI 코딩 도구들이 공통적으로 겪어온 한 가지 문제를 정면으로 겨냥한 설계입니다. 개발자가 무언가를 요청하면 에이전트가 곧바로 파일을 수정해버리는 것, 그게 문제였습니다. 2026년 3월 11일 구글은 Gemini CLI v0.33.0을 통해 Plan 모드를 전체 사용자 기본값으로 전환했습니다. (출처: Google Developers Blog, 2026.03.11)
이 업데이트 이전까지는 Gemini CLI가 요청을 받으면 곧장 코드를 작성하고 파일을 덮어쓰는 방식으로 동작했습니다. 복잡한 프로젝트에서 이런 방식은 되돌리기 어려운 수정 사항을 남기는 경우가 많았고, 개발자 커뮤니티에서 꾸준히 지적받아 왔습니다. Plan 모드 도입 이후 Gemini CLI는 기본적으로 읽기 전용 상태에서 먼저 코드베이스를 분석하고, 계획을 Markdown 파일로 작성한 뒤 개발자의 승인을 받아야만 실제 파일 수정 단계로 넘어갑니다.
DevOps.com의 분석에 따르면, 이 전환은 단순한 안전장치를 넘어 엔터프라이즈 시장 공략과 직결된 포지셔닝 전략입니다. “기업이 AI 코딩 도구를 평가할 때 계획 우선 실행(plan-first execution)을 기본 거버넌스 요건으로 간주하게 될 것”이라는 분석이 나온 배경이기도 합니다. (출처: DevOps.com, 2026.03.16)
Plan 모드에서 실제로 허용되는 것과 막히는 것
Plan 모드가 읽기 전용이라고는 하지만, 정확히 어디까지 허용되는지는 공식 문서를 직접 들여다봐야 알 수 있습니다. 생각보다 세밀하게 구분돼 있습니다.
💡 공식 문서와 실제 동작을 같이 놓고 보니 이런 차이가 보였습니다
“읽기 전용”이라는 표현 때문에 Plan 모드에서는 아무것도 쓸 수 없다고 오해하기 쉽습니다. 실제로는 plans 디렉터리 내 .md 파일에 한해서 쓰기가 허용됩니다. 프로젝트 파일 전체가 막히는 게 아니라, 계획 문서 파일만 선택적으로 쓸 수 있는 구조입니다.
공식 문서(geminicli.com/docs/cli/plan-mode)에 명시된 허용 도구 목록은 아래와 같습니다.
| 구분 | 허용 도구 | 비고 |
|---|---|---|
| 파일 읽기 | read_file, list_directory, glob | 쓰기 불가 |
| 검색 | grep_search, google_web_search | 웹 검색 포함 |
| 서브에이전트 | codebase_investigator, cli_help | 내장 에이전트만 |
| MCP 연동 | 읽기 전용 MCP 도구 | 기본적으로 확인 필요 |
| 계획 파일 쓰기 | write_file, replace | plans 디렉터리 .md만 |
| 차단 항목 | run_shell_command (기본) | 정책 수정 시 부분 허용 |
(출처: Gemini CLI 공식 문서 — geminicli.com/docs/cli/plan-mode)
여기서 실제로 많이 막히는 포인트가 있습니다. MCP 읽기 전용 도구는 Plan 모드에서 허용되긴 하지만, 기본 설정에서는 사용자 확인(confirmation)을 요구합니다. 자동 승인을 원한다면 별도의 정책 파일(~/.gemini/policies/)을 직접 작성해야 합니다. 이 과정이 생략된 채로 “Plan 모드에서 GitHub 이슈를 바로 읽을 수 있다”고 기대하면 첫 시도에서 멈추는 경험을 하게 됩니다.
모델 자동 전환 — Pro가 항상 쓰이는 건 아닙니다
Plan 모드의 홍보 문구 중 가장 많이 언급되는 것이 “계획 단계에서 고추론 Pro 모델 자동 적용”입니다. 그런데 이게 모든 사용자에게 동일하게 작동하지 않습니다.
💡 “자동 모델”이라는 설정이 전제 조건입니다
공식 문서에는 이렇게 나옵니다. “When using an auto model, Gemini CLI automatically optimizes model routing.” 즉 자동 모델 라우팅은 auto model 설정을 사용 중일 때만 작동합니다. 특정 모델을 직접 지정해 사용하고 있다면 Plan 모드에서도 그 모델이 그대로 쓰입니다. (출처: geminicli.com/docs/cli/plan-mode — Automatic Model Routing 항목)
auto model 설정 상태에서 Plan 모드가 활성화되면 Gemini CLI는 계획 단계에 Gemini 3.1 Pro를 배정하고, 승인 후 구현 단계로 전환될 때 자동으로 Gemini 3 Flash로 내려옵니다. 전략 수립에는 고추론 모델, 실제 코드 작성에는 빠른 모델을 쓰는 방식입니다. 직접 계산해보면 이 구조가 의미하는 바가 명확해집니다.
Gemini 3.1 Pro API 기준 입력 토큰은 100만 개당 $2, 출력은 $12입니다. (출처: DataCamp — Gemini CLI vs. Claude Code, 2026.03.26) 같은 작업을 Gemini 3 Flash로만 수행했을 때와 비교하면 계획 단계에서의 토큰 비용이 수배 이상 차이 납니다. Pro 모델 라우팅을 비활성화하고 싶다면 settings.json에서 plan.modelRouting: false를 설정하면 됩니다. 하지만 그렇게 하면 Plan 모드의 추론 품질이 크게 떨어진다는 것도 감수해야 합니다.
무료 플랜 사용자에게는 이 자동 전환이 더 복잡하게 작용합니다. 아래 섹션에서 이어집니다.
무료 플랜에서 Plan 모드를 쓰면 생기는 일
Gemini CLI 무료 플랜은 하루 1,000개 요청이 가능합니다. (출처: Gemini CLI 공식 pricing 페이지, 2026.03.26) 그런데 이 숫자가 Plan 모드 환경에서는 생각보다 빨리 소모됩니다.
Plan 모드는 코드베이스를 분석할 때 codebase_investigator 같은 리서치 서브에이전트를 활성화합니다. 이 서브에이전트는 독립적인 LLM 호출을 여러 번 발생시키기 때문에, 복잡한 프로젝트 하나를 분석하는 것만으로도 수십 건의 요청이 소진될 수 있습니다. 무료 플랜에서 하루 1,000건이라는 숫자가 많아 보이지만, 대형 코드베이스 분석 서너 번이면 소진될 수 있습니다.
더 큰 문제는 무료 플랜에서는 Pro 모델에 접근이 제한된다는 점입니다. 2026년 3월 말 현재 무료 사용자는 Flash 모델만 사용 가능합니다. auto model 설정으로 Plan 모드를 시작해도, 무료 플랜이라면 계획 단계에서 Pro로 라우팅되지 않고 Flash가 그대로 쓰입니다. 이 부분을 공식 문서에서 별도로 명시하지 않아 많은 혼란이 생기고 있습니다.
💡 사용 가이드 FAQ와 실제 사용 패턴을 같이 놓고 보면 이런 흐름이 보입니다
Gemini 개발자 포럼(discuss.ai.google.dev)에서 실제 유료 Pro 구독자조차 “최근 사용량 제한 강화로 실무 개발 워크플로에서 사용이 사실상 불가능해졌다”고 토로한 사례가 2026년 3월 23일 확인됩니다. 구글이 공식 답변을 내놓지 않은 부분입니다. 무료 플랜에서 Plan 모드를 기대한 대로 쓰려면, 적어도 Google AI Pro 구독($19.99/월)이 필요한 현실입니다.
Claude Code Plan 모드와 실제로 다른 점
두 도구 모두 Plan 모드를 갖추고 있고, 기능 이름도 같습니다. 그런데 막상 써보면 동작 방식이 꽤 다릅니다.
Gemini CLI는 Plan 모드가 기본값이고, Plan → 구현 전환 시 모델이 자동으로 바뀝니다. Claude Code의 Plan 모드는 Shift+Tab으로 수동 전환하는 방식이고, 계획 단계에서 Haiku Explore Subagent를 활용합니다. 또한 Claude Code는 계획 파일을 열고 편집할 때 Ctrl+G 단축키를 쓰는 반면, Gemini CLI는 Ctrl+X입니다. 단순한 인터페이스 차이처럼 보이지만, 팀 환경에서 공유 설정을 맞출 때 혼란 포인트가 됩니다.
토큰 효율 측면에서 같은 작업을 수행할 때 Gemini CLI가 Claude Code보다 더 많은 토큰을 사용한다는 실측 데이터가 있습니다. DataCamp 비교 분석에 따르면 동일 작업 기준 Gemini CLI는 약 432K 입력 토큰을 소비한 반면 Claude Code는 약 261K에 그쳤습니다. (출처: DataCamp — Gemini CLI vs. Claude Code, 2026.03.26) 토큰 단가가 낮더라도 사용량 자체가 많으면 실제 비용 차이가 예상보다 작아집니다.
반면 Gemini CLI가 우위를 갖는 지점도 분명합니다. 오픈소스(Apache 2.0)라는 점이 가장 큽니다. 기업 환경에서 코드 감사가 필요하거나, Plan 모드 정책을 조직 맞춤으로 수정해야 할 때는 Gemini CLI가 현실적인 선택지가 됩니다. Claude Code는 Anthropic 모델만 지원하고 소스를 열람할 수 없습니다.
Plan 모드가 안 맞는 상황
Plan 모드가 무조건 좋은 건 아닙니다. 솔직히 말하면, 빠른 프로토타이핑이나 간단한 스크립트 작성에는 Plan 모드가 오히려 느려집니다.
코드베이스 분석 → 계획 수립 → 승인 → 구현 단계를 모두 거쳐야 하기 때문에, 한 줄짜리 수정이나 단순 함수 추가 같은 작업에서는 Plan 단계가 불필요한 대기 시간이 됩니다. 이런 경우 Shift+Tab으로 Auto-Edit 모드로 전환하거나, /settings에서 Default Approval Mode를 바꾸는 게 낫습니다.
또 CI/CD 파이프라인처럼 비대화형(non-interactive) 환경에서는 동작 방식이 달라집니다. 공식 문서에 따르면 Plan 모드를 headless 환경에서 실행하면 계획 승인 단계에서 자동으로 YOLO 모드로 전환되어 모든 구현이 자동 실행됩니다. 이 부분을 인지하지 못한 채 CI/CD에 적용하면 계획을 검토할 기회 없이 코드가 변경될 수 있습니다. (출처: Gemini CLI 공식 문서 — Non-interactive execution 항목)
💡 “안전한 기본값”이라는 홍보와 다른 면이 있습니다
Plan 모드가 기본값이 됐다는 사실과, CI/CD 파이프라인에서 Plan 모드가 YOLO 모드로 자동 전환된다는 사실을 함께 놓으면 역설적인 구조가 보입니다. 자동화 환경에서 Plan 모드를 켜두는 것이 오히려 무통제 실행으로 이어질 수 있습니다. 공식 문서에 명시된 내용이지만, 이 부분을 다룬 한국어 자료는 아직 없습니다.
커뮤니티(Reddit/r/GeminiCLI, 2026.03.19)에서는 유럽 시간대 오전 이후(미국 동부 기준 오전 2시 이후) Gemini CLI가 과부하로 응답이 현저히 느려지는 사례도 보고됩니다. Plan 모드는 분석 단계에서 여러 번의 LLM 호출을 발생시키기 때문에, 서버 과부하 상황에서 더 오래 걸리거나 중간에 끊기는 경우가 있습니다. 이 부분도 이유가 아직 공개되지 않았습니다.
Q&A
마치며
Gemini CLI Plan 모드는 AI 코딩 도구가 지금까지 가져온 “일단 실행부터” 방식을 뒤집는 설계입니다. 그 의도는 분명히 좋고, 실제로 복잡한 리팩터링이나 데이터베이스 마이그레이션 계획 수립에서는 명확한 가치가 있습니다.
다만 “기본값이 됐다”는 사실과 “모든 상황에 적합하다”는 건 다른 이야기입니다. 무료 플랜에서 Pro 모델 라우팅이 작동하지 않는 점, MCP 도구 사용 시 별도 정책 파일이 필요한 점, CI/CD 환경에서 자동으로 무확인 실행으로 전환된다는 점은 공식 홍보에서 잘 부각되지 않는 조건들입니다.
막상 써보고 “왜 안 되지”를 반복하게 만드는 포인트가 거기 있습니다. 조건을 이해하고 쓰면 꽤 쓸 만한 도구입니다.
📚 본 포스팅 참고 자료
- Gemini CLI 공식 Plan 모드 문서 — geminicli.com/docs/cli/plan-mode/
- Google Developers Blog — Plan Mode 발표 (2026.03.11) — developers-kr.googleblog.com
- DevOps.com — Gemini CLI Plan Mode Separates Thinking From Doing (2026.03.16) — devops.com
- ADTmag — Google Adds “Plan Mode” to Gemini CLI (2026.03.12) — adtmag.com
- DataCamp — Gemini CLI vs. Claude Code (2026.03.26) — datacamp.com
- Google AI Developer Forum — Pro Plan Usage Limits Discussion (2026.03.23) — discuss.ai.google.dev
- GitHub Gemini CLI — Plan Mode v0.33.0 Release Discussion (2026.03.11) — github.com/google-gemini/gemini-cli
본 포스팅은 2026년 3월 30일 기준 / Gemini CLI v0.33.0 기준으로 작성되었습니다. 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 최신 정보는 Gemini CLI 공식 문서에서 반드시 확인하세요.
댓글 남기기