Plan 모드가 생기기 전에는 뭐가 문제였나

Gemini CLI의 기존 작동 방식은 단순했습니다. 프롬프트를 입력하면 모델이 바로 파일을 읽고, 수정하고, 쉘 명령을 실행했습니다. 빠른 건 맞는데, 그만큼 실수가 잦았습니다. Reddit의 r/GeminiCLI에는 “들여쓰기가 자꾸 깨진다”, “루프에 빠져서 같은 파일을 계속 지웠다 썼다 한다”는 후기가 반복적으로 올라왔습니다 (출처: Reddit r/GeminiCLI, 2026.03.06).

핵심 문제는 순서입니다. 분석과 실행이 동시에 일어나면, 모델이 코드베이스를 충분히 이해하기 전에 수정을 시작합니다. 1만 줄짜리 레거시 프로젝트에서 의존성을 잘못 파악한 채 파일을 덮어쓰기 시작하면, 원복하는 데 오히려 시간이 더 걸립니다.

Plan 모드는 이 순서 문제를 구조적으로 해결하려는 시도입니다. 읽고, 분석하고, 계획을 세우는 단계와 실제로 코드를 건드리는 단계를 물리적으로 분리했습니다.

▲ 목차로 돌아가기

Plan 모드 실제 작동 방식 — 읽기 전용의 범위

Plan 모드에서 허용되는 도구는 공식 문서에 명확하게 나와 있습니다. read_file, list_directory, glob 같은 파일 읽기 툴과, grep_search, google_web_search 등의 검색 툴만 활성화됩니다. 파일 쓰기는 딱 한 곳 — ~/.gemini/tmp/<project>/<session-id>/plans/ 안의 마크다운 파일에만 허용됩니다. 프로젝트 코드 어디에도 손을 대지 않습니다 (출처: geminicli.com/docs/cli/plan-mode).

진입 방법은 세 가지입니다. 터미널에서 /plan을 입력하거나, Shift+Tab으로 모드를 순환시키거나, 자연어로 “이 기능을 구현할 계획 먼저 세워줘”라고 말하면 됩니다. 플랜이 완성되면 승인 여부를 묻고, 승인 시 자동으로 일반 구현 모드로 전환됩니다.

ask_user 툴도 새로 추가됐습니다. AI가 스스로 판단하기 애매한 구조적 선택지(예: 기존 Logger 클래스를 재사용할지 새로 만들지)를 만나면 플래닝을 멈추고 직접 물어봅니다. 가정으로 때우는 대신 확인하는 구조입니다 (출처: developers.googleblog.com, 2026.03.11).

▲ 목차로 돌아가기

무료인데 3.1 Pro가 쓰이는 구조

이게 이번에 제일 눈에 띄는 부분입니다. Gemini CLI는 기본적으로 비용·속도 효율이 좋은 Flash 계열 모델을 씁니다. 그런데 Plan 모드에 진입하는 순간, 공식 문서에 딱 이렇게 나옵니다.

“Planning Phase: While in Plan Mode, the CLI routes requests to a high-reasoning Pro model to ensure robust architectural decisions and high-quality plans.”

— Gemini CLI 공식 문서 “Automatic Model Routing” 섹션 (geminicli.com/docs/cli/plan-mode, 2026.03.11)

구글 계정으로 로그인한 무료 사용자도 플래닝 단계에서는 Gemini 3.1 Pro가 투입됩니다. 구현 단계로 넘어가면 다시 Flash로 자동 전환됩니다. 무료로 Pro를 쓰는 게 아니라, 모델 라우팅이 페이즈 단위로 자동 최적화되는 겁니다.

이 설정은 기본값입니다. 끄고 싶다면 settings.json에서 "plan": { "modelRouting": false }로 설정하면 됩니다. 단, 끄면 플래닝 품질이 Flash 수준으로 떨어집니다 (출처: geminicli.com/docs/cli/plan-mode#automatic-model-routing).

▲ 목차로 돌아가기

쿼터 수치로 보는 Plan 모드 비용 현실

공식 문서 기준으로 인증 방식에 따라 쿼터가 다르게 적용됩니다 (출처: geminicli.com/docs/resources/quota-and-pricing, 2026.03 기준).

여기서 한 가지 짚어둬야 할 부분이 있습니다. “한 번의 프롬프트 = 한 번의 요청”이 아닙니다. 공식 문서에 이렇게 나옵니다: “When in agent mode or when using the Gemini CLI, one prompt might result in multiple model requests.” (출처: developers.google.com/gemini-code-assist/resources/quotas). 복잡한 코드베이스를 분석하는 Plan 모드 1회 실행이 내부적으로 수십 번의 모델 요청을 만들 수 있습니다. 무료 사용자 기준 하루 1,000회 한도가 생각보다 빨리 바닥날 수 있다는 뜻입니다.

API 키로 인증한 경우엔 더 심합니다. 하루 250회 한도 안에서 Plan 모드 실행과 이후 구현까지 마치려면, 작은 프로젝트 기준으로도 하루 2~3건이 한계입니다. 큰 레포를 다룰 계획이라면 구글 계정 로그인 방식이 훨씬 유리합니다.

▲ 목차로 돌아가기

Claude Code와 비교했을 때 달라지는 점

Plan 모드가 추가되면서 Gemini CLI와 Claude Code의 접근 방식 차이가 더 선명해졌습니다. Claude Code(Claude Sonnet 4.6 기준)는 처음부터 실행 전에 구조 분석과 계획을 거치는 방식을 기본으로 삼습니다. 반면 Gemini CLI는 기존에 속도를 우선했는데, Plan 모드를 통해 선택적으로 그 방식을 선택할 수 있게 됐습니다 (출처: emergent.sh/learn/gemini-cli-vs-claude-code, 2026.03.05).

실사용자 관점에서 차이가 남는 부분이 있습니다. Claude Code는 계획 없이 시작해도 복잡한 의존성을 비교적 잘 추적합니다. Gemini CLI는 Plan 모드를 켜야 비슷한 수준이 나오고, Plan 모드를 끄면 들여쓰기 오류나 루프 이슈가 다시 나타납니다 (출처: Reddit r/GeminiCLI, 2026.03.06). 요컨대 Plan 모드는 선택 기능이지만, Gemini CLI에서는 사실상 필수에 가깝게 써야 한다는 게 현재 사용자 피드백의 중론입니다.

Conductor 확장도 이번에 함께 공개됐습니다. Plan 모드와 ask_user를 조합해서 복잡한 마이그레이션이나 멀티 트랙 개발을 오케스트레이션해주는 외부 확장입니다. 구글은 이 Conductor를 향후 Gemini CLI 내장 모드로 통합할 계획이라고 밝혔습니다 (출처: developers.googleblog.com, 2026.03.11).

▲ 목차로 돌아가기

Plan 모드가 오히려 불편한 조건

Plan 모드가 무조건 좋은 건 아닙니다. 구조적으로 빠르게 막히는 시나리오가 있습니다.

첫째, 단발성 수정 작업에는 오버헤드입니다. 함수 이름 하나 바꾸거나 변수 타입 수정 같은 작은 변경에도 Plan 모드를 쓰면 분석-계획-승인 사이클을 거쳐야 합니다. 이 경우엔 그냥 Auto-Edit 모드로 바로 처리하는 게 빠릅니다.

둘째, API 키 인증 사용자는 Plan 모드 중 Pro 모델이 아닙니다. 앞서 표에서도 나왔지만, API 키로 인증하면 Flash 계열 모델만 씁니다. 무료 API 키로 Plan 모드를 써봤는데 결과가 기대 이하라면, 그 이유가 모델 차이에 있을 수 있습니다.

셋째, Git 상태 확인이 기본적으로 막혀 있습니다. Plan 모드는 read-only MCP 툴은 허용하지만, git status나 git diff 같은 쉘 명령은 기본적으로 차단됩니다. 변경 이력을 참조해서 플랜을 짜야 하는 경우엔 별도로 policy 파일을 만들어서 허용해줘야 합니다 (출처: geminicli.com/docs/cli/plan-mode#custom-policies).

넷째, YOLO 모드와 함께 쓸 때 주의가 필요합니다. CI/CD 파이프라인처럼 비대화형 환경에서 Plan 모드를 실행하면, 플랜 승인 후 자동으로 YOLO 모드로 전환됩니다. 사람 확인 없이 전부 실행된다는 뜻입니다. 프로덕션 레포에 직접 붙여서 쓸 때는 이 자동 전환 동작을 미리 인지하고 있어야 합니다.

▲ 목차로 돌아가기

자주 묻는 질문

▲ 목차로 돌아가기

마치며

Plan 모드의 핵심은 “코드를 건드리기 전에 생각부터 한다”는 원칙을 Gemini CLI에 구조적으로 집어넣었다는 점입니다. 이건 Claude Code가 처음부터 내세우던 접근 방식과 같습니다. Gemini CLI가 그 방향으로 옮겨왔다는 게 이번 업데이트의 실질적인 의미입니다.

다만 Plan 모드가 만능은 아닙니다. 쿼터 소모 방식, API 키 인증 시 모델 제한, git 명령 기본 차단 같은 조건들은 직접 문서를 확인하고 쓰기 시작해야 당황하지 않습니다. 특히 무료로 쓰는 분들은 하루 1,000회 한도가 Plan 모드 안에서 훨씬 빠르게 소진된다는 점을 미리 알고 있는 게 좋습니다.

개인적으로 이 방향은 맞다고 봅니다. AI가 코드를 먼저 읽고 질문하고 나서 건드리는 흐름은, 실수를 줄이는 가장 직관적인 방법입니다. 남은 건 모델 품질과 쿼터 한계가 실사용에서 얼마나 버텨주느냐입니다.

▲ 목차로 돌아가기

본 포스팅 참고 자료

1. Gemini CLI 공식 블로그 — Plan mode is now available in Gemini CLI
   https://developers.googleblog.com/plan-mode-now-available-in-gemini-cli/
2. Gemini CLI 공식 문서 — Plan Mode
   https://geminicli.com/docs/cli/plan-mode/
3. Gemini CLI 공식 문서 — Quotas and Pricing
   https://geminicli.com/docs/resources/quota-and-pricing/
4. Google Developers — Gemini Code Assist 쿼터 및 한도
   https://developers.google.com/gemini-code-assist/resources/quotas
5. emergent.sh — Gemini CLI vs Claude Code 비교 (2026.03.05)
   https://emergent.sh/learn/gemini-cli-vs-claude-code