IT / AI 도구
Gemini CLI Plan 모드, 무료라도 이 한계가 먼저입니다
2026년 3월 11일, 구글이 Gemini CLI에 Plan 모드를 공식 탑재했습니다. 터미널에서 코드를 건드리기 전에 계획부터 짜주는 기능입니다. 무료라는 소식에 바로 써봤는데, 막상 쓰면 조건이 있었습니다.
Plan 모드란 정확히 무엇인가
Gemini CLI Plan 모드는 터미널에서 코드 변경을 시작하기 전, 읽기 전용(read-only) 상태로 코드베이스를 분석하고 실행 계획을 먼저 짜는 환경입니다. 구글 개발자 블로그에 직접 이렇게 나와 있습니다.
“Plan mode is a read-only mode that restricts Gemini CLI to a subset of its tools. When active, the agent can navigate your codebase, search for patterns, and read documentation, but it cannot modify any files except for its own internal plans.”
— Google Developers Blog, 2026.03.11 (출처: developers.googleblog.com)
핵심은 파일을 건드리지 않는다는 것입니다. 실수로 코드가 바뀌는 사고를 원천 차단하면서 분석에만 집중합니다. 계획 파일은 Markdown 형식으로 ~/.gemini/tmp/<project>/<session-id>/plans/ 경로에 저장되고, 기본 30일 보존됩니다. (출처: geminicli.com 공식 문서, 2026.03)
진입 방법은 세 가지입니다. 터미널에서 /plan을 치거나, Shift+Tab으로 모드를 순환하거나, “start a plan for…”라고 자연어로 입력하면 됩니다. 기본값으로 전체 사용자에게 켜져 있습니다.
쓸 수 있는 도구와 쓸 수 없는 도구
Plan 모드에서 허용되는 도구는 공식 문서에 목록이 정확히 나와 있습니다. 생각보다 넓기도 하고, 생각보다 좁기도 합니다.
| 구분 | 허용 도구 | 비고 |
|---|---|---|
| 파일 읽기 | read_file, list_directory, glob |
쓰기 불가 |
| 검색 | grep_search, google_web_search, get_internal_docs |
웹 검색 포함 |
| 서브에이전트 | codebase_investigator, cli_help |
읽기 전용 |
| 사용자 소통 | ask_user |
목표 명확화용 |
| MCP 도구 | 읽기 전용 MCP만 허용 (github_read_issue 등) |
기본값은 확인 요청 |
| 계획 파일 쓰기 | write_file, replace |
.md 파일, plans 디렉터리 한정 |
출처: geminicli.com 공식 문서 — Plan Mode Tool Restrictions (2026.03)
눈에 띄는 건 읽기 전용 MCP 도구도 기본적으로 사용자 확인을 요청한다는 점입니다. 자동 허용하려면 policy 파일을 직접 만들어야 합니다. 쓰기 도구는 계획 파일(.md)에 한정되고, 이 경로를 벗어나면 policy engine에서 차단합니다.
모델이 자동으로 바뀐다는 게 문제입니다
💡 공식 발표문과 실제 작동 흐름을 같이 놓고 보니 이런 차이가 보였습니다. Plan 모드가 “무료”라는 말을 그대로 믿으면 예상치 못한 부분에서 막힙니다.
Plan 모드를 쓰면 Gemini CLI는 내부적으로 자동 모델 라우팅을 실행합니다. 공식 문서에 이렇게 나옵니다.
“While in Plan Mode, the CLI routes requests to a high-reasoning Pro model to ensure robust architectural decisions and high-quality plans.”
— geminicli.com 공식 문서, Automatic Model Routing (2026.03)
계획 단계에서는 Gemini 3.1 Pro가 작동하고, 승인 후 구현 단계로 넘어가면 Gemini Flash 모델로 자동 전환됩니다. 속도와 품질을 나눠서 처리하는 구조입니다.
이게 왜 문제냐면, Gemini CLI는 Google 계정으로 무료 사용이 가능하지만 무료 할당량은 Flash 기준입니다. Plan 모드 진입 시 Pro 모델을 자동 호출하면 이 할당량과 별도로 처리될 수 있습니다. 공식 요금 페이지(geminicli.com/docs/resources/quota-and-pricing)에는 “무료 등급에서는 분당 60개 요청, 일 1,000개 요청”이 명시돼 있지만, 이는 Google 계정 기본 제공 기준입니다. Pro 모델 라우팅이 이 범위 안에 포함되는지 여부는 Gemini API 키 인증 방식에 따라 달라집니다.
설정에서 자동 라우팅을 끄려면 settings.json에 "modelRouting": false를 추가하면 됩니다. 이때는 직접 지정한 모델로만 동작합니다. Pro 자동 전환 없이 Flash로만 계획을 돌리고 싶다면 이 옵션이 필수입니다.
MCP 제한, 실무에서 막히는 지점
💡 “Plan 모드에서 외부 데이터도 읽어준다”고 알려진 것과 달리, 실제로는 매번 확인창이 뜨는 구조입니다. 이 차이를 알면 쓰는 방식이 달라집니다.
Plan 모드에서 MCP 도구를 쓰려면 매 요청마다 사용자 확인이 필요합니다. GitHub 이슈를 읽거나 PostgreSQL 스키마를 가져오는 것처럼 외부 소스 조회도 마찬가지입니다. 이 부분은 커뮤니티에서도 바로 지적됐습니다.
“the MCP limitation is a real gap — half the value of planning is querying external state (logs, db schemas, api responses) to inform the plan.”
— Reddit r/GeminiCLI, 사용자 germanheller, 2026.03.12
자동 허용이 안 되는 이유는 보안 때문입니다. Plan 모드는 코드를 건드리지 않는 대신 외부 시스템과 통신할 때도 승인을 받는 방식으로 신뢰 경계를 만들었습니다. 그래서 매번 팝업이 뜹니다.
해결책은 policy 파일 커스터마이징입니다. ~/.gemini/policies/mcp-read-only.toml에 아래처럼 설정하면 읽기 전용 MCP 도구는 자동 승인됩니다. toolAnnotations = { readOnlyHint = true }를 조건으로 decision = "allow"를 주면 됩니다. (출처: geminicli.com 공식 문서 — Custom Policies, 2026.03)
Claude Code /plan 과 무엇이 다른가
Gemini CLI Plan 모드는 구조상 Claude Code의 /plan 기능과 비슷합니다. 하지만 직접 비교해보면 다른 부분이 몇 가지 있습니다.
| 항목 | Gemini CLI Plan 모드 | Claude Code /plan |
|---|---|---|
| 진입 방법 | /plan, Shift+Tab, 자연어 |
/plan, –plan 플래그 |
| 자동 모델 전환 | ✅ Pro → Flash 자동 | 수동 모델 선택 |
| MCP 읽기 | 기본값: 확인 필요 | MCP 도구 지원 |
| 계획 파일 저장 | Markdown, 30일 보존 | 세션 내 관리 |
| ask_user 도구 | ✅ 내장 | 별도 설정 |
| 기본 무료 여부 | Google 계정으로 무료 | 유료 플랜 필요 |
출처: geminicli.com 공식 문서, emergent.sh 비교 분석 (2026.03)
커뮤니티 반응을 보면 “계획은 Gemini, 실행은 Claude Code”로 나눠 쓰는 흐름이 나타납니다. 실제로 Reddit r/GeminiCLI에서 한 사용자는 “gemini는 프론트엔드 디자인이 강하고, codex는 백엔드와 구조 설계에 강하다”(2026.03.12)고 비교했습니다. 두 도구가 경쟁 관계라기보다 용도가 갈리고 있다는 뜻입니다.
Plan 모드를 제대로 쓰는 흐름
공식 문서에서 권장하는 흐름은 다섯 단계입니다. 순서를 지키면 실수를 줄일 수 있습니다.
“migrate this database” 또는 “plan a new feature”처럼 자연어로 입력합니다. Gemini CLI가 자동으로 Plan 모드에 진입합니다.
AI가 목표를 구체화하기 위해 질문합니다. 아키텍처 선택지나 설정 파일 위치 같은 것들입니다. 성의껏 답해야 계획 품질이 올라갑니다.
Markdown 파일로 계획이 생성됩니다. Ctrl+X로 외부 에디터에서 직접 수정도 가능합니다.
계획이 마음에 들면 승인합니다. 부족하면 피드백을 입력하거나 계획 파일을 직접 수정하면 AI가 다시 반영합니다.
승인 즉시 Plan 모드가 종료되고 Flash 모델로 전환되면서 구현을 시작합니다. 코드 변경이 이 시점부터 시작됩니다.
한 가지 더. CI/CD 환경처럼 비대화형(non-interactive) 실행을 쓸 때는 Plan 모드가 자동으로 YOLO 모드로 전환됩니다. 이때는 모든 단계가 자동 승인되므로 주의가 필요합니다. 공식 문서에서 직접 이 동작을 명시하고 있습니다. (출처: geminicli.com, Non-interactive execution, 2026.03)
Q&A
마치며
Gemini CLI Plan 모드는 터미널 AI 코딩 도구 중에서 “짜놓고 후회하는” 패턴을 구조적으로 막으려는 시도입니다. 읽기 전용 상태에서 코드베이스를 분석하고, 계획을 검토하고, 승인 후 실행하는 흐름은 명확합니다.
다만 무료라는 말만 보고 쓰면 두 가지에서 막힙니다. Plan 모드 진입 시 Gemini 3.1 Pro가 자동 호출된다는 것, 그리고 MCP 도구는 기본값으로 매번 승인이 필요하다는 것입니다. 둘 다 settings나 policy 파일로 제어할 수 있지만, 기본 상태에서는 이 조건이 그대로 적용됩니다.
솔직히 말하면, 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/ - Gemini CLI 공식 문서 — Plan Mode (2026.03)
https://geminicli.com/docs/cli/plan-mode/ - GitHub — Gemini CLI v0.33.0 Discussion (2026.03.11)
https://github.com/google-gemini/gemini-cli/discussions/22078 - ADT Magazine — Google Adds Plan Mode to Gemini CLI (2026.03.12)
https://adtmag.com/articles/2026/03/12/google-adds-plan-mode-to-gemini-cli-to-support-safer-code-planning.aspx - Gemini CLI 공식 문서 — Quotas and Pricing
https://geminicli.com/docs/resources/quota-and-pricing/
⚠️ 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. Gemini CLI는 지속적으로 업데이트되는 오픈소스 프로젝트이므로, 최신 정보는 공식 문서(geminicli.com) 및 GitHub 저장소를 직접 확인해 주세요. 본 내용은 v0.33.0 / 2026.03.11 공식 발표 기준으로 작성됐습니다.
댓글 남기기