Gemini CLI Plan 모드
Gemini CLI Plan 모드,
써봤더니 이게 달랐습니다
“코드 건드리기 전에 계획 먼저”라는 말이 얼마나 실용적인지 직접 확인해봤습니다.
안전하다는 말은 반만 맞고, 모델 자동 전환과 요청 한도 소진 속도가 진짜 핵심이었습니다.
Plan 모드가 기본값이 된 날 — v0.34.0
Gemini CLI Plan 모드는 2026년 2월 17일 v0.29.0에서 처음 도입됐습니다. 그리고 딱 한 달 뒤인 3월 17일 v0.34.0부터 모든 사용자에게 기본(default)으로 켜졌습니다. (출처: Gemini CLI 공식 changelog, 2026.03.17)
기본값 전환은 단순 업데이트가 아닙니다. 구글이 “AI가 코드를 건드리기 전에 반드시 계획을 세워야 한다”는 방향으로 에이전트 전략을 굳혔다는 선언입니다. Shift+Tab을 누르면 Default → Auto-Edit → Plan 순서로 순환하는데, 이제 세션을 새로 열면 아무 설정 없이도 Plan 상태에서 시작합니다.
사용하고 싶지 않다면 /settings에서 “Plan”을 검색해 끄면 됩니다. 끄면 Shift+Tab 순환에서도 빠집니다. 그런데 꺼야 할 이유가 생각보다 제한적입니다. 오히려 켜둬야 하는 이유를 모르는 게 더 큰 문제입니다.
Plan 모드, 실제로 어떻게 작동하나
Plan 모드에 들어가는 방법은 세 가지입니다. /plan 명령어를 입력하거나, Shift+Tab을 눌러 순환시키거나, “이 기능 추가하는 계획 세워줘”처럼 자연어로 말해도 됩니다. 자연어 방식을 쓰면 AI가 스스로 enter_plan_mode 툴을 호출합니다.
Plan 모드에 진입하면 AI는 코드베이스를 읽고, 디렉터리를 탐색하고, 웹 검색도 합니다. 하지만 파일을 직접 수정하지는 않습니다. ~/.gemini/tmp/<프로젝트>/<세션ID>/plans/ 경로에 .md 파일로 계획서를 작성하는 것만 허용됩니다. (출처: Gemini CLI Plan Mode 공식 문서)
계획서 초안이 나오면 Ctrl+X를 눌러 외부 에디터(VS Code, Vim 등)에서 직접 편집할 수 있습니다. “이 단계는 빼줘”처럼 채팅으로 피드백을 주면 AI가 계획서를 수정해 다시 제안합니다. 만족하면 승인, 승인하는 순간 AI가 구현 단계로 넘어갑니다.
💡 공식 발표 원문과 실제 사용 흐름을 같이 놓고 보니 이런 차이가 보였습니다.
공식 문서에는 Plan 모드의 허용 도구 목록이 꼼꼼하게 정의돼 있습니다. read_file, list_directory, glob, grep_search, google_web_search, codebase_investigator, ask_user, 그리고 읽기 전용 MCP 도구만 사용 가능합니다. 이 목록을 보면 Plan 모드가 단순히 “코드 못 건드리게 막는 것”이 아니라, 탐색·검색·질의 중심의 완전히 다른 에이전트 모드임을 알 수 있습니다.
‘읽기 전용’이라는 말이 전부가 아닌 이유
“Plan 모드는 읽기 전용이라 안전하다”는 말이 많습니다. 맞는 말이지만, 이 설명만 보면 Plan 모드의 핵심을 절반만 이해한 겁니다. 진짜 중요한 건 읽기 전용이기 때문에 가능해지는 것들입니다.
Plan 모드에서 AI는 외부 MCP 도구 중 읽기 전용인 것도 쓸 수 있습니다. GitHub 이슈를 읽고, Postgres 스키마를 확인하고, Google Docs를 검색하고, 이 모든 맥락을 계획서에 반영합니다. 코드베이스 밖의 정보까지 끌어다 쓰는 전처리 에이전트라고 보는 게 더 정확합니다. (출처: Google Developers 공식 블로그, 2026.03.11)
ask_user 툴도 이 맥락에서 봐야 합니다. Plan 모드에 들어간 AI는 모르는 게 있으면 스스로 멈추고 질문을 던집니다. “설정 파일이 어디 있어요?”, “DB 마이그레이션 시 롤백 전략은 어떻게 할까요?” 같은 식입니다. 어차피 실행 단계에서 막혀서 되돌아올 질문을, 계획 단계에서 미리 해결하는 겁니다.
💡 기존 설명들이 ‘안전성’에만 집중하는 사이, 정작 이 부분이 잘 언급되지 않았습니다.
DevOps.com의 분석 기사는 “DB 마이그레이션 계획을 세울 때 AI가 현재 스키마를 읽고, 이슈 트래커에서 관련 티켓을 확인하고, 기존 문서를 검토한 뒤 제안을 내놓는다”고 정리했습니다. 이건 안전망이 아니라, 작업 전 사전 조사를 AI에 위임하는 구조입니다. (출처: DevOps.com, 2026.03.16)
모델 자동 라우팅 — 이게 진짜 숨겨진 기능
Plan 모드에서 가장 많이 지나치는 기능이 자동 모델 라우팅입니다. 계획 단계에서는 Gemini 3.1 Pro처럼 추론 성능이 높은 모델을 씁니다. 계획이 승인되고 구현 단계로 넘어가면 자동으로 Flash 모델로 전환합니다. (출처: Gemini CLI Plan Mode 공식 문서 — Automatic Model Routing)
이 전환은 settings.json에서 "modelRouting": false로 끄지 않으면 기본적으로 켜진 상태입니다. 전략은 Pro가, 실행은 Flash가 담당하는 구조입니다. Pro의 정확한 아키텍처 판단을 받은 뒤, Flash의 속도로 코드를 쓰는 겁니다. 단순히 “Plan 모드 = 느린 모드”라는 생각은 이 지점에서 깨집니다.
DataCamp의 비교 분석에 따르면, SWE-bench Verified 기준으로 Gemini 3.1 Pro는 약 80.6%를 기록했습니다. (출처: DataCamp — Gemini CLI vs Claude Code, 2026.03) 계획 단계에서 이 수준의 모델이 의존성을 분석하고 계획서를 작성한다는 의미입니다. 아키텍처 품질이 80%짜리 판단으로 결정됩니다.
| 단계 | 사용 모델 | 주요 작업 |
|---|---|---|
| Plan 모드 (계획) | Gemini 3.1 Pro | 코드베이스 탐색, 의존성 분석, 계획서 작성 |
| 구현 단계 (실행) | Gemini 3 Flash | 계획서 기반 코드 작성, 파일 수정 |
▲ Plan 모드 승인 후 모델이 자동 전환됩니다. 출처: Gemini CLI Plan Mode 공식 문서 (2026.03)
무료 한도, 생각보다 빨리 닳습니다
구글 계정으로 로그인하면 하루 1,000회 요청이 무료입니다. Gemini API 키(무료)로 쓰면 250회입니다. (출처: Gemini CLI 공식 한도 안내) 250회는 현실적으로 턱없이 부족합니다.
Plan 모드 한 세션에서 AI가 코드베이스를 여러 번 탐색하고, 질문을 주고받고, 계획서를 수정하는 과정이 반복되면 수십 번의 모델 호출이 일어납니다. DataCamp의 비교 테스트에서 동일한 작업을 처리할 때 Gemini CLI가 Claude Code보다 약 65% 더 많은 토큰을 사용했다는 측정치가 있습니다. (출처: DataCamp — Gemini CLI vs Claude Code, 2026.03) 토큰이 많다고 요청 횟수가 곧바로 늘어나지는 않지만, 복잡한 계획 세션일수록 API 호출 횟수가 늘어날 수 있습니다.
현재 무료 구글 계정 기준 데이터 수집에 동의하면 1,000회 한도가 적용됩니다. 팀 프라이버시가 중요한 경우 무료 구글 계정 데이터는 모델 개선에 쓰일 수 있어서 유의가 필요합니다. 개인 프로젝트나 오픈소스 작업은 문제없지만, 사내 코드를 Plan 모드로 분석시키는 건 다른 얘기입니다.
💡 Gemini API 키 무료 250회와 구글 계정 무료 1,000회의 차이를 나란히 놓고 보면 판단이 달라집니다.
API 키 250회는 Plan 모드로 복잡한 리팩토링을 시도하면 하루 안에 소진될 수 있습니다. 구글 계정 1,000회는 실 사용에서는 충분하지만, 프리뷰 기간이 끝나거나 정책이 바뀔 가능성은 열려 있습니다. 지금 당장은 구글 계정 로그인이 훨씬 현실적입니다.
CI/CD에서 Plan 모드, 아는 사람만 씁니다
여기서부터는 기존 블로그 대부분이 언급하지 않는 부분입니다. Plan 모드는 헤드리스(non-interactive) 환경에서 동작 방식이 완전히 달라집니다.
CI/CD 파이프라인처럼 터미널 입력이 없는 환경에서 실행하면, enter_plan_mode와 exit_plan_mode 승인이 사용자 확인 없이 자동 처리됩니다. 그리고 계획이 승인되고 구현 단계로 넘어갈 때 자동으로 YOLO 모드로 전환됩니다. (출처: Gemini CLI 공식 문서 — Non-interactive execution)
YOLO 모드는 모든 툴 호출을 사용자 확인 없이 자동 실행하는 모드입니다. 즉, CI/CD에서 gemini --approval-mode plan -p "텔레메트리 분석 후 개선 제안"을 실행하면 AI가 코드베이스를 분석하고, 계획을 세우고, 계획대로 코드를 직접 바꿉니다. 파이프라인에서 쓸 때는 이 동작을 명확히 이해하고 사용해야 합니다.
Claude Code Plan 모드와 뭐가 다른가
Claude Code도 Plan 모드가 있습니다. Shift+Tab으로 진입하고, Ctrl+G로 외부 에디터에서 계획서를 편집합니다. Gemini CLI의 Ctrl+X와 기능이 같습니다. 그런데 결정적인 차이가 있습니다.
무료 여부가 가장 큽니다. Gemini CLI는 구글 계정으로 하루 1,000회 무료입니다. Claude Code는 최저 월 $20(한화 약 2만 8천 원 이상)의 Pro 플랜이 있어야 Plan 모드를 포함한 기능 전체를 쓸 수 있습니다. 무료 티어 자체가 없습니다. (출처: DataCamp — Gemini CLI vs Claude Code, 2026.03)
실행 신뢰도는 복잡한 멀티파일 리팩토링에서 Claude Code 쪽이 높다는 커뮤니티 피드백이 있습니다. 같은 작업에서 Gemini CLI가 432K 입력 토큰을 쓴 반면 Claude Code는 261K를 사용했다는 비교치도 있습니다. 토큰 효율로는 Claude Code가 앞서지만, 비용 효율로는 무료인 Gemini CLI가 명확히 유리합니다. 두 도구 중 하나를 고르는 게 아니라, 용도에 따라 병행하는 게 현실적입니다.
| 항목 | Gemini CLI | Claude Code |
|---|---|---|
| Plan 모드 진입 | /plan, Shift+Tab, 자연어 | /plan, Shift+Tab |
| 계획서 편집 | Ctrl+X (외부 에디터) | Ctrl+G (외부 에디터) |
| 기본 활성화 여부 | ✅ 기본 ON | 수동 설정 |
| 모델 자동 라우팅 | ✅ Pro→Flash | Haiku Explore 서브에이전트 |
| 무료 사용 | ✅ 1,000회/일 | ❌ 월 $20~ |
| 오픈소스 | ✅ Apache 2.0 | ❌ 독점 |
▲ 출처: Gemini CLI 공식 문서, DataCamp Gemini CLI vs Claude Code (2026.03)
Q&A
Q1. Plan 모드를 끄는 방법은 무엇인가요?
/settings를 입력한 뒤 “Plan”을 검색하면 Plan 모드 토글이 나옵니다. 비활성화하면 Shift+Tab 순환에서 Plan이 빠지고, enter_plan_mode·exit_plan_mode 툴도 등록 해제됩니다. settings.json에서 직접 수정할 수도 있습니다. (출처: Gemini CLI 공식 문서)
Q2. Plan 모드에서 작성된 계획서는 어디에 저장되나요?
기본적으로 ~/.gemini/tmp/<프로젝트명>/<세션ID>/plans/ 경로에 .md 파일로 저장됩니다. 세션은 기본 30일간 보관 후 자동 삭제됩니다. settings.json에서 "plan": { "directory": ".gemini/plans" }로 프로젝트 내부 경로로 변경할 수 있습니다. 단, 커스텀 경로를 쓰면 자동 삭제가 되지 않아 직접 관리해야 합니다. (출처: Gemini CLI Plan Mode 공식 문서)
Q3. 무료 사용자도 Plan 모드에서 Pro 모델을 쓸 수 있나요?
구글 계정으로 로그인한 경우, Plan 모드의 자동 모델 라우팅이 Pro 모델을 호출하도록 돼 있습니다. 그러나 무료 티어에서 Pro 모델 접근이 가능한지 여부는 Gemini CLI의 내부 라우팅 정책에 따라 달라지며, 구글이 이 부분의 상세 조건을 공식 문서에 별도로 밝히지 않은 상황입니다. 실제 사용 중 모델 전환 여부는 /stats model 명령어로 확인할 수 있습니다.
Q4. Plan 모드에서 외부 에디터로 계획서를 편집하면 AI가 바로 반영하나요?
Ctrl+X를 눌러 에디터에서 계획서를 수정하고 저장 후 닫으면, Gemini CLI가 변경사항을 자동으로 감지합니다. 댓글이나 수정 내용을 반영해 계획서를 업데이트한 뒤 최종 승인을 다시 요청합니다. 채팅으로 피드백을 주는 것보다 복잡한 수정이나 단계 삭제에 더 빠릅니다. (출처: Gemini CLI Plan Mode 공식 문서 — Collaborative plan editing)
Q5. CI/CD에서 Plan 모드로 실행하면 정말 코드가 자동으로 바뀌나요?
맞습니다. 헤드리스 환경에서는 계획 승인과 구현 전환이 자동 처리되고, 구현 단계에서 YOLO 모드로 전환돼 파일이 직접 수정됩니다. 파이프라인에 연결하기 전에 충분한 테스트가 필요하고, 민감한 코드베이스에는 정책 파일(~/.gemini/policies/)로 허용 명령어를 제한하는 것이 권장됩니다. (출처: Gemini CLI 공식 문서 — Non-interactive execution)
마치며
v0.34.0부터 기본값이 됐다는 건, 구글이 이미 “먼저 계획, 나중에 실행”을 에이전트 표준으로 정했다는 신호입니다. Claude Code Plan 모드와 구조는 비슷하지만 무료라는 점에서 진입 장벽이 없습니다. 복잡한 기능을 짜기 전에 /plan 한 번 입력해보는 것, 지금 당장 시도해볼 만한 이유가 충분합니다.
본 포스팅 참고 자료
- ① Gemini CLI Plan Mode 공식 문서 (geminicli.com)
- ② Plan mode is now available in Gemini CLI — Google Developers Blog (2026.03.11)
- ③ Gemini CLI 공식 changelog (geminicli.com)
- ④ Gemini CLI Plan Mode Separates Thinking From Doing — DevOps.com (2026.03.16)
- ⑤ Gemini CLI vs. Claude Code — DataCamp (2026.03)
- ⑥ Gemini CLI Quotas and Pricing 공식 문서 (geminicli.com)
본 포스팅은 2026년 3월 29일 기준 Gemini CLI v0.34.0~v0.35.2 공식 문서와 공개 자료를 참고해 작성됐습니다. 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 특히 무료 한도, 모델 라우팅 정책, 요금제 구조는 Google 공식 발표에 따라 달라질 수 있으므로, 최신 정보는 geminicli.com에서 직접 확인하세요.
댓글 남기기