Gemini CLI v0.32.x 기준
Gemini CLI Plan 모드, 써봤더니 이게 걸렸습니다
구글이 3월 11일 Gemini CLI에 Plan 모드를 정식 출시했습니다. 읽기 전용 환경에서 코드를 분석하고, 실행 전 설계를 먼저 검토할 수 있는 기능입니다. 생각보다 쓸 만했지만 막상 써보니 한 가지 구조적인 문제가 보였습니다. Plan 모드를 켜는 순간, 무료 한도가 예상보다 빠르게 줄어들었습니다.
Plan 모드가 뭔지, 딱 한 줄로 정리하면
결론부터 말씀드리면, Plan 모드는 “코드를 건드리지 않고 먼저 계획만 짜는 모드”입니다. 구글이 2026년 3월 11일 공식 블로그를 통해 발표했고 (출처: Google Developers Blog, 2026.03.11), Gemini CLI 전체 사용자에게 기본값으로 활성화되어 있습니다. 이게 핵심입니다. 새로 설치한 사람이든, 기존 사용자든 이미 Plan 모드가 켜진 상태로 동작하고 있다는 뜻입니다.
공식 문서에 따르면 Plan 모드가 활성화된 동안 Gemini CLI는 read_file, grep_search, glob처럼 읽기 전용 툴만 사용할 수 있습니다. 파일 수정은 자체 계획 파일(~/.gemini/tmp/<project>/<session-id>/plans/) 내의 마크다운 파일에 한해서만 허용됩니다. (출처: Gemini CLI 공식 문서, 2026.03)
한 줄 요약: 코드베이스를 읽고, 질문하고, 설계안을 마크다운으로 저장한 뒤 승인받으면 그때 실행합니다. 에이전트가 “알아서 바꿔버리는” 상황을 원천 차단하는 구조입니다.
켜는 방법은 3가지인데, 기본값이 이미 켜져 있습니다
Plan 모드를 시작하는 방법은 세 가지입니다. 터미널에서 /plan을 입력하거나, Shift+Tab으로 승인 모드를 순환(Default → Auto-Edit → Plan)시키거나, “start a plan for…”처럼 자연어로 요청하는 방법이 있습니다. 세션 시작부터 Plan 모드로 고정하고 싶다면 gemini --approval-mode=plan으로 실행하거나 /settings에서 Default Approval Mode를 Plan으로 설정하면 됩니다.
💡 공식 발표문과 실제 동작을 같이 놓고 보니 이런 차이가 보였습니다
구글 공식 블로그는 Plan 모드를 “선택 가능한 기능”으로 소개했습니다. 그런데 공식 문서에는 “Plan mode is now enabled by default for all users”라고 명시되어 있습니다. (출처: Google Developers Blog, 2026.03.11) 즉, 사용자가 선택하지 않아도 이미 기본 로테이션에 포함된 상태입니다. Shift+Tab을 한 번 잘못 누르면 Plan 모드로 전환된다는 뜻이고, 이 시점부터 모델 라우팅이 바뀝니다. 이 부분은 본문 3섹션에서 자세히 다룹니다.
Plan 모드를 끄고 싶다면 /settings에서 “Plan”을 검색해 토글을 끄면 됩니다. 이렇게 하면 Shift+Tab 로테이션에서 Plan 모드가 제거되고, enter_plan_mode와 exit_plan_mode 툴도 등록 해제됩니다.
Plan 모드가 무료인 줄 알았는데, 여기서 돈이 빠집니다
Gemini CLI는 구글 계정으로 로그인하면 무료로 쓸 수 있습니다. 공식 문서 기준으로 하루 1,000회 요청, 분당 60회 요청이 제공됩니다. (출처: Gemini CLI 공식 요금 문서, 2026.03) 여기까지는 대부분 알고 있는 내용입니다.
막상 써보면 이 단계에서 멈춥니다. Plan 모드가 활성화된 순간, Gemini CLI는 플래닝 단계에서 자동으로 Gemini 3.1 Pro를 사용하도록 라우팅을 전환합니다. 공식 발표문에는 이렇게 명시되어 있습니다: “Plan mode uses higher reasoning Pro models like the new Gemini 3.1 Pro model to ensure robust architectural decisions.” (출처: Google Developers Blog, 2026.03.11) 즉, 설계 단계에서는 Flash가 아닌 Pro 모델이 쓰이고, 구현 단계로 넘어가면 다시 Flash로 전환됩니다.
⚠️ 실제로 어떤 의미인지 계산해 보면
Google AI Pro 구독(개인용 유료 플랜) 기준 Gemini Code Assist Standard 라이선스는 하루 1,500 요청입니다. Plan 모드가 한 번의 플래닝 세션에서 여러 차례 Pro 모델 요청을 발생시키면, 하루 사용 가능한 Pro 모델 쿼터가 생각보다 빠르게 소모됩니다. 무료 한도를 넉넉하다고 믿고 복잡한 마이그레이션 작업을 시작했다가 플래닝 도중 한도 초과가 뜰 수 있습니다. (출처: Gemini CLI 공식 요금 문서, 2026.03)
자동 모델 라우팅 기능은 기본으로 켜져 있습니다. 이걸 끄려면 settings.json에서 "plan": { "modelRouting": false }를 추가하면 됩니다. 다만 이렇게 하면 플래닝 품질이 떨어질 수 있다는 점은 감수해야 합니다.
MCP를 켜놓으면 Plan 모드가 이렇게 멈춥니다
Plan 모드는 읽기 전용 MCP 툴도 지원합니다. GitHub 이슈를 읽거나, Postgres 스키마를 확인하거나, Google Docs를 조회하는 것이 가능합니다. 이 기능은 데이터베이스 마이그레이션 계획 같은 복잡한 작업에서 특히 유용합니다. 공식 문서에도 “외부 데이터 소스에서 컨텍스트를 가져오면서 코드베이스의 무결성을 유지할 수 있다”고 명시되어 있습니다.
💡 MCP 활성화 상태에서 Plan 모드를 쓰면 이런 증상이 나타납니다
2026년 3월 14일 Gemini CLI 공식 GitHub 이슈(#21096, #21937)에서 확인된 버그입니다. MCP 익스텐션을 활성화한 상태에서 gemini-3.1-pro-preview 모델을 사용하면 CLI가 “This is taking a bit longer, we’re still on it…”에서 무한 대기에 빠집니다. 디버그 로그를 확인하면 429 에러: “No capacity available for model gemini-3.1-pro-preview”가 반복됩니다. (출처: Reddit r/GeminiCLI, 2026.03.14)
이 문제의 가설적 원인은 두 가지입니다. 첫째, MCP 익스텐션이 활성화되면 CLI가 Function Calling 페이로드를 포함해 요청을 보내는데, 구글 서버의 tool-use 전용 풀은 표준 텍스트 생성 풀보다 가용 용량이 훨씬 제한적이라는 것입니다. 둘째, GitHub MCP 같은 익스텐션은 시스템 프롬프트에 대용량 컨텍스트를 주입하기 때문에 preview 모델의 숨겨진 토큰 한도에 걸릴 수 있습니다.
현재 확인된 임시 해결책은 gemini extensions disable <확장명>과 gemini mcp disable <MCP서버명>을 실행해 MCP를 비활성화하는 것입니다. 이 방법으로 즉시 해소됐다는 사례가 Reddit에서 공유된 바 있습니다. 공식 패치는 아직 배포되지 않았습니다 (2026.03.18 기준, 확인 필요).
Claude Code /plan과 뭐가 다를까요
Claude Code는 이미 자체적인 플래닝 워크플로를 갖추고 있습니다. Reddit의 실사용 후기에서 Gemini CLI Plan 모드를 처음 본 개발자 중 일부는 “Claude Code가 이미 있는 걸 따라잡은 것 아니냐”는 반응을 보였습니다. 틀린 말은 아닙니다. 구조적으로 비슷한 개념입니다.
| 항목 | Gemini CLI Plan 모드 | Claude Code /plan |
|---|---|---|
| 기본 활성화 | ✅ 기본값으로 켜짐 | 수동 명령어 필요 |
| 모델 자동 라우팅 | ✅ Plan→Pro, Impl→Flash | 수동 모델 선택 |
| MCP 읽기 전용 지원 | ✅ (단, 429 버그 존재) | ✅ (안정적) |
| 무료 한도 | 1,000 req/일 (Pro 포함) | Pro 플랜 필요 ($20/월~) |
| 계획 파일 저장 위치 | ~/.gemini/tmp/…/plans/ | 프로젝트 디렉토리 내 |
| 커스텀 정책(Policy) | ✅ plan.toml 기반 | CLAUDE.md 파일 기반 |
핵심 차이는 자동 모델 라우팅입니다. Gemini CLI는 플래닝 중에는 Gemini 3.1 Pro를, 구현 단계에서는 더 빠른 Flash 모델을 자동으로 선택합니다. 전략은 추론 모델이, 구현은 속도 모델이 담당하는 구조입니다. Claude Code는 이 선택을 개발자가 직접 해야 합니다.
이 부분이 좀 아쉬웠습니다. MCP와의 충돌 버그가 없었다면 훨씬 더 매력적인 차별점이 될 수 있었습니다. 지금 시점에서는 MCP를 적극적으로 쓰는 팀이라면 Plan 모드와의 조합을 조심스럽게 접근해야 합니다.
이 상황에서만 Plan 모드가 진짜 유리합니다
비판만 하는 게 공평하지는 않습니다. 막상 써보면 확실히 도움이 되는 시나리오가 있습니다. 특히 세 가지 상황에서 Plan 모드의 가치가 두드러집니다.
💡 공식 문서의 설계 의도와 실제 사용 흐름을 교차해 보니 이런 차이가 보였습니다
기존 블로그들은 Plan 모드를 “안전한 실행 전 검토 단계”로만 소개합니다. 그런데 공식 문서를 보면 ask_user 툴이 핵심입니다. 에이전트가 스스로 멈추고 “어느 방식을 선호하세요?”라고 묻는 구조는, 개발자가 미처 명시하지 못한 아키텍처 결정 사항을 표면으로 끌어올립니다. 이게 단순한 확인 절차가 아니라, 요구사항 정제 도구로 작동한다는 점에서 다른 AI 코딩 도구와 성격이 다릅니다.
첫째, 대규모 레거시 코드베이스 분석입니다. Gemini CLI의 무료 티어는 1M 토큰 컨텍스트를 지원합니다. Plan 모드에서 codebase_investigator 서브에이전트를 활용하면 수만 줄짜리 프로젝트 전체를 읽고 의존성을 매핑한 뒤 설계안을 제출합니다. 실행하기 전에 얼마나 많은 파일이 영향을 받는지 먼저 볼 수 있습니다.
둘째, 데이터베이스 마이그레이션 계획입니다. MCP 버그가 수정된다는 전제하에, Postgres 스키마를 읽고 GitHub 이슈를 참조해 마이그레이션 전략을 도출하는 워크플로는 Plan 모드의 설계 의도와 정확히 맞아떨어집니다. 지금 당장은 MCP 없이 로컬 파일만으로 쓰는 게 안정적입니다.
셋째, 팀 단위 코드 리뷰 전 설계 합의입니다. Conductor 익스텐션을 함께 쓰면 계획 파일을 프로젝트 내 conductor/ 디렉토리에 영구 저장합니다. 에이전트가 뭘 하려는지 팀원이 코드 리뷰 전에 먼저 검토하고 승인하는 흐름을 만들 수 있습니다. GCS 아카이브 훅을 연결하면 모든 실행 계획의 감사 기록도 자동으로 남습니다.
Q&A
마치며
Gemini CLI Plan 모드는 방향은 맞습니다. “실행하기 전에 먼저 계획을”이라는 철학은 AI 코딩 에이전트의 가장 큰 불안 요소, 즉 에이전트가 맥락도 없이 파일을 바꿔버리는 상황을 구조적으로 막아줍니다. 자동 모델 라우팅(플래닝에 Pro, 구현에 Flash)은 전략-전술 분리라는 개념을 실제 워크플로에 구현한 점에서 참신합니다.
이 부분이 좀 아쉬웠습니다. Plan 모드가 기본값으로 켜지면서 Pro 모델 쿼터 소모가 빨라지는 부분은 사전에 인지하지 못하면 당황스러울 수 있습니다. MCP와의 충돌 버그는 아직 공식 패치가 없는 상태입니다. 지금 당장 MCP를 적극적으로 쓰는 팀이라면 조합에 주의가 필요합니다.
MCP 버그가 수정되고 쿼터 정책이 좀 더 투명해지면, Plan 모드는 Claude Code나 Codex와 충분히 경쟁 가능한 워크플로를 제공할 것입니다. 기대했던 것과 달랐지만, 방향 자체는 틀리지 않았습니다.
본 포스팅 참고 자료
- Plan mode is now available in Gemini CLI — Google Developers Blog (2026.03.11)
- Plan Mode 공식 문서 — geminicli.com/docs/cli/plan-mode/
- Gemini CLI Quotas and Pricing — geminicli.com/docs/resources/quota-and-pricing/
- Gemini CLI introduces plan mode — InfoWorld (2026.03.12)
- MCP 충돌 이슈 — Reddit r/GeminiCLI (2026.03.14)
- Gemini CLI Plan Mode Separates Thinking From Doing — DevOps.com (2026.03.16)
본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. Gemini CLI는 활발히 업데이트 중인 오픈소스 프로젝트로, 본문의 수치·기능·버그 수정 여부는 최신 릴리스 노트와 공식 문서에서 재확인하시기 바랍니다. 본 포스팅은 2026년 3월 18일 기준으로 공개된 정보를 바탕으로 작성되었습니다.
댓글 남기기