Gemini CLI v최신
IT/AI
Gemini CLI Plan 모드, 써봤더니 Claude Code와 달랐습니다
2026년 3월 11일, Google이 Gemini CLI에 Plan 모드를 추가하고 기본값으로 활성화했습니다. 설치 직후부터 켜져 있고, 모르고 넘기면 오히려 손해인 구조입니다. Claude Code에 이미 있던 기능이라고 가볍게 볼 수 없는 이유가 있습니다. 공식 문서와 GitHub 이슈 원문을 직접 뜯어봤습니다.
Plan 모드가 뭔지, 한 줄로 정리하면
Gemini CLI Plan 모드는 “코드를 건드리기 전에 먼저 읽고 계획만 세우는 상태”입니다. 파일을 열어보고, 패턴을 검색하고, 의존성을 파악하되 — 실제 수정은 아무것도 하지 않습니다. 공식 문서에 딱 이렇게 나옵니다: “read-only mode that restricts Gemini CLI to a subset of its tools” (출처: Google Developers Blog, 2026.03.11).
쉽게 말하면, AI가 무작정 코드를 고치기 시작하는 게 아니라 먼저 전체 구조를 파악하고 계획안을 작성한 뒤 승인을 받아야 실행 단계로 넘어갑니다. 승인 전까지는 파일 하나도 바뀌지 않습니다.
허용되는 도구는 딱 정해져 있습니다. read_file, grep_search, glob 같은 읽기 전용 도구들, 그리고 GitHub 이슈를 읽거나 Postgres 스키마를 조회하는 MCP 읽기 도구까지는 사용할 수 있습니다. 쓰기 권한이 있는 도구는 단 하나 — 자신의 계획 파일(.md)을 저장하는 것뿐입니다. (출처: geminicli.com/docs/cli/plan-mode, 2026.03.11)
설치하자마자 켜져 있는 이유
💡 공식 발표문과 실제 동작 방식을 같이 놓고 보니 이런 차이가 보였습니다. 대부분의 선택적 기능과 달리, Plan 모드는 별도 설정 없이 이미 활성화된 상태로 작동합니다.
Plan 모드는 기본값(Default)으로 활성화된 상태입니다. Gemini CLI를 설치하고 아무것도 건드리지 않아도 Plan 모드는 이미 켜져 있습니다. 공식 문서에 “Plan Mode is enabled by default”라고 명시되어 있습니다. (출처: geminicli.com/docs/cli/plan-mode, 2026.03.11) 막상 써보면 생각보다 조용한 변화라 모르고 지나치기 쉽습니다.
진입 방법은 세 가지입니다. 채팅창에 /plan을 입력하거나, Shift+Tab을 눌러 모드를 순환하거나(Default → Auto-Edit → Plan), 또는 “이 기능을 위한 계획을 세워줘”처럼 자연어로 요청하면 됩니다. 이미 기본값으로 설정되어 있으니 많은 경우 자동으로 진입합니다.
원하지 않는다면 /settings에서 “Plan”을 검색해 끄면 됩니다. 끄면 Shift+Tab 순환에서 Plan 모드가 사라지고, 관련 도구도 등록 해제됩니다. 개인적으로는 끄는 것보다 켜두고 습관을 들이는 쪽이 장기적으로 낫다고 생각합니다.
Plan 단계에서 Pro 쓰고, 구현 단계에서 Flash로 바뀌는 구조
💡 GitHub 이슈 원문을 직접 확인해보니, 모델 전환이 단순한 비용 절감 장치가 아니라 처음부터 의도된 설계였습니다.
Plan 모드에서 가장 눈에 띄는 부분은 자동 모델 라우팅입니다. Plan 모드로 진입하면 Gemini CLI는 자동으로 Gemini 3.1 Pro (고추론 모델)를 사용해 코드베이스를 분석하고 계획을 작성합니다. 계획이 승인되고 구현 단계로 전환되는 순간, 자동으로 Flash 모델 (고속 모델)로 교체됩니다. (출처: Google Developers Blog, 2026.03.11)
| 단계 | 사용 모델 | 역할 |
|---|---|---|
| Plan 모드 (계획) | Gemini 3.1 Pro | 코드베이스 분석, 아키텍처 설계 |
| 구현 단계 (실행) | Flash 모델 | 승인된 계획의 빠른 실행 |
| 비활성화 시 | 기존 라우팅 로직 | 복잡도 기반 분류기가 결정 |
GitHub Issue #19454에서 이 설계의 배경이 직접 나옵니다. “Planning is inherently complex, requiring deep codebase analysis and strategic foresight. Implementation is often more mechanical, involving specific, bounded edits that are perfectly suited for Flash.” — 설계 단계와 실행 단계의 특성 차이를 인식하고 모델을 다르게 배치한 겁니다. (출처: github.com/google-gemini/gemini-cli/issues/19454, 2026.02.18)
“Pro 모델을 더 쓰면 비용이 더 든다”고 생각하기 쉽지만, 계획 단계가 끝나면 자동으로 Flash로 전환되기 때문에 장시간 구현 작업에서는 오히려 전체 비용이 내려갑니다. 아끼려고 전부 Flash만 쓰면 계획 품질이 떨어져서 구현 단계에서 재작업이 발생하는 경우가 더 많습니다.
Claude Code와 실제로 어떻게 다른가
💡 2025년 11월 한 개발자의 비교 후기와 2026년 3월 공식 출시 타임라인을 같이 놓고 보면, 이 기능이 왜 이 시점에 나왔는지가 보입니다.
솔직히 말하면 Plan 모드 자체는 Claude Code에 이미 있었던 기능입니다. 2025년 11월 27일, Kevin Simper라는 개발자가 두 도구를 비교하며 이렇게 적었습니다: “It is weird that gemini cli has no plan mode. In Claude Code you can do plan mode with two shift tabs.” (출처: kevinsimper.dk, 2025.11.27) 그리고 약 4개월 뒤인 2026년 3월 11일, Gemini CLI에 동일한 방식(Shift+Tab 2회 순환)으로 Plan 모드가 추가됐습니다.
그런데 차이가 없는 건 아닙니다. 가장 눈에 띄는 차이는 계획 파일이 Markdown으로 저장된다는 것입니다. Claude Code에서 Plan 모드는 대화 안에서 계획이 오가는 반면, Gemini CLI는 계획 결과물을 ~/.gemini/tmp/<project>/<session-id>/plans/ 경로에 실제 파일로 저장합니다. Ctrl+X를 누르면 VS Code나 Vim에서 직접 편집도 가능합니다.
또 다른 차이는 읽기 전용 MCP 도구 지원입니다. Plan 모드 안에서 GitHub 이슈를 읽거나, Postgres 스키마를 확인하거나, Google Docs 문서를 검색할 수 있습니다 — 전부 로컬 파일이 아닌 외부 데이터 소스에서요. 코드 외적인 맥락(이슈 티켓, DB 구조, 기획 문서)까지 계획에 반영할 수 있다는 점이 실무에서는 의외로 큽니다.
ask_user 도구가 달라지는 점
Plan 모드와 함께 추가된 ask_user 도구는 작동 방식이 조금 다릅니다. 기존 AI 코딩 도구들은 요청을 받으면 스스로 판단하고 실행하는 경향이 있었습니다. ask_user는 에이전트가 분석 중에 스스로 멈추고 질문을 던지는 구조입니다. (출처: Google Developers Blog, 2026.03.11)
예를 들어 DB 마이그레이션 계획을 세우는 중이라면, “기존 컬럼을 유지하면서 새 컬럼을 추가하는 방식이 좋겠습니까, 아니면 새 테이블로 분리하는 게 나을까요?” 같은 아키텍처 선택지를 제시하며 답을 기다립니다. 이 선택이 반영된 뒤에야 계획을 완성합니다.
이 부분이 좀 아쉬웠습니다 — 간단한 작업에도 질문이 끼어들면 흐름이 끊깁니다. 간단한 작업에는 오히려 Auto-Edit 모드가 더 편할 수 있습니다. Plan 모드는 데이터베이스 마이그레이션, 대규모 리팩토링, 여러 서비스에 걸친 기능 추가처럼 판단 지점이 여러 개인 작업에서 진가를 발휘합니다.
Plan 모드가 불편한 상황도 있습니다
⚠️ Plan 모드가 기본값이라고 해서 모든 상황에 맞는 건 아닙니다. 아래 상황에서는 오히려 불편할 수 있습니다.
Plan 모드의 가장 큰 전제는 “먼저 읽고 계획한 뒤 실행”이지만, 빠르게 작은 수정을 반복하는 바이브 코딩 스타일과는 맞지 않습니다. 코드 한 줄 바꾸는데 먼저 계획 파일을 작성하고 승인받아야 한다면 속도가 오히려 느려집니다. 이런 경우엔 Shift+Tab으로 Auto-Edit 모드나 Default 모드로 바꾸는 게 낫습니다.
무료 티어의 한도도 확인이 필요합니다. Plan 모드에서 Gemini 3.1 Pro가 자동으로 사용되는데, 무료 등급의 Gemini 3 Pro 쿼터는 일별로 재설정됩니다. (출처: shipyard.build/blog/claude-code-vs-gemini-cli, 2026.01.15) 하루 쿼터가 소진되면 2.5 Pro → 2.5 Flash 순으로 자동 강등됩니다. 기대했던 것과 달리, Plan 모드를 켰다고 해서 항상 Gemini 3.1 Pro가 보장되진 않습니다.
또한 무료 티어에서는 입출력 데이터가 Google에 수집되는 옵션이 기본으로 켜져 있습니다. 업무용 코드나 내부 시스템 코드를 분석할 때는 이 부분을 반드시 확인해야 합니다. 유료 티어에서는 데이터 수집 옵션을 해제할 수 있습니다.
자주 나오는 질문들
Q1. Plan 모드를 활성화하려면 별도 설정이 필요한가요?
필요 없습니다. 2026년 3월 11일 업데이트 이후 Gemini CLI를 설치하면 Plan 모드가 기본값으로 활성화됩니다. 채팅창에 /plan을 입력하거나 Shift+Tab으로 모드를 순환하면 즉시 사용할 수 있습니다. (출처: geminicli.com/docs/cli/plan-mode, 2026.03.11)
Q2. Plan 모드에서 자동으로 Gemini 3.1 Pro가 쓰인다고 했는데, 무료로도 사용되나요?
무료 티어에서도 Gemini 3 Pro에 대한 일별 한도 내에서 사용됩니다. 단, 한도가 소진되면 자동으로 2.5 Pro → 2.5 Flash로 내려갑니다. 정확한 일별 한도는 Google AI Studio에서 확인할 수 있습니다. (출처: shipyard.build/blog/claude-code-vs-gemini-cli, 2026.01.15)
Q3. Plan 모드에서 작성된 계획 파일은 어디에 저장되나요?
기본 저장 경로는 ~/.gemini/tmp/<project>/<session-id>/plans/입니다. settings.json에서 커스텀 디렉토리로 변경할 수 있으며, 단 프로젝트 루트 내 경로만 허용됩니다. 세션 데이터는 기본적으로 30일 후 자동 삭제됩니다. (출처: geminicli.com/docs/cli/plan-mode, 2026.03.11)
Q4. Plan 모드와 Claude Code의 Plan 모드는 어떻게 다른가요?
핵심 개념은 같습니다. 차이점은 Gemini CLI가 계획을 실제 Markdown 파일로 저장하고 외부 편집기에서 수정할 수 있는 점, 읽기 전용 MCP 도구로 외부 시스템(GitHub, DB 등) 맥락을 가져올 수 있다는 점입니다. Claude Code는 현재 Conductor 같은 Orchestration 레이어를 내장하지 않는 반면, Gemini CLI는 Conductor 확장을 통해 멀티스텝 워크플로를 지원합니다.
Q5. CI/CD 파이프라인에서도 Plan 모드를 사용할 수 있나요?
가능합니다. 비대화형(headless) 환경에서는 gemini --approval-mode plan -p "분석 및 개선안 제안" 형태로 실행합니다. 이 모드에서는 enter_plan_mode와 exit_plan_mode가 자동 승인되며, 구현 단계 진입 시 자동으로 YOLO 모드로 전환되어 사용자 확인 없이 실행됩니다. (출처: geminicli.com/docs/cli/plan-mode, 2026.03.11)
마치며 — Plan 모드, 쓸 만한가
Plan 모드 자체가 완전히 새로운 개념은 아닙니다. Claude Code에 이미 있던 기능이고, 그 부재가 지적받은 지 4개월 만에 나온 것이기도 합니다. 그런데 실제로 써보면 단순 따라하기가 아닌 것도 사실입니다. 계획 파일의 외부 저장, MCP 읽기 도구를 통한 외부 맥락 수집, Pro-Flash 자동 전환 — 이 세 가지가 기존 Claude Code Plan 모드에 없거나 약한 부분입니다.
기대했던 것과 달랐던 점은 무료 티어에서 Gemini 3.1 Pro가 무한정 보장되지 않는다는 것입니다. 하루 쿼터가 소진되면 조용히 낮은 모델로 내려갑니다. Plan 모드 기반 작업이 많은 날은 쿼터 소진 여부를 확인하는 습관이 필요합니다.
결론적으로 — Gemini CLI를 이미 쓰고 있다면 Plan 모드는 별다른 설정 없이 켜져 있으니 바로 활용할 수 있습니다. 처음 접하는 분이라면 간단한 작업부터 Plan 모드로 진입해보고, 어떤 질문을 던지고 어떤 계획 파일을 만드는지 직접 확인해보는 게 빠릅니다.
본 포스팅 참고 자료
-
Google Developers Blog — Plan mode is now available in Gemini CLI (2026.03.11)
https://developers.googleblog.com/plan-mode-now-available-in-gemini-cli/ - https://geminicli.com/docs/cli/plan-mode/
-
GitHub Issue #19454 — Support model switching for Plan Mode (2026.02.18)
https://github.com/google-gemini/gemini-cli/issues/19454 -
DevOps.com — Gemini CLI Plan Mode Separates Thinking From Doing (2026.03.16)
https://devops.com/gemini-cli-plan-mode-separates-thinking-from-doing-and-makes-read-only-the-default/ -
Kevin Simper — My experience using Claude Code vs Gemini CLI (2025.11.27)
https://www.kevinsimper.dk/posts/my-experience-using-claude-code-vs-gemini-cli -
Shipyard Build — Claude Code vs Gemini CLI (2026.01.15)
https://shipyard.build/blog/claude-code-vs-gemini-cli/
본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. Gemini CLI는 활발히 업데이트되는 오픈소스 프로젝트로, 버전에 따라 동작 방식이 달라질 수 있습니다. 본문 내 모델명·가격·쿼터 정보는 2026년 3월 24일 기준이며, 최신 정보는 공식 문서에서 직접 확인하시기 바랍니다.
댓글 남기기