Gemini CLI
Gemini CLI Plan 모드, 무조건 플래닝부터입니다
2026년 3월 11일, Gemini CLI v0.33.0 업데이트와 함께 Plan 모드가 기본값으로 활성화됐습니다. 코드 한 줄 건드리기 전에 AI가 먼저 읽기 전용으로 코드베이스를 분석하고, 직접 질문을 던지며, 계획서를 작성해서 가져옵니다. 쓰기 권한은 그 다음입니다.
Plan 모드가 뭔지, 핵심만 먼저
Gemini CLI에 Plan 모드가 생겼다는 소식은 3월 11일 공식 블로그에서 처음 공개됐습니다. 정확히는 v0.33.0 업데이트에 포함된 기능이고, 발표 즉시 모든 사용자에게 기본값으로 적용됐습니다. 요약하면 이렇습니다. AI가 코드에 손대기 전에, 읽기 전용 상태로 먼저 코드베이스를 탐색하고, 계획서를 Markdown 파일로 작성해서 사람이 검토하고 승인하면 그때 비로소 실제 수정에 들어가는 구조입니다.
공식 발표문에는 이렇게 나와 있습니다. “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) 실행 전 분석 단계를 강제로 분리한 겁니다.
이게 왜 중요한지는 실제 개발자 커뮤니티 반응에서 바로 읽힙니다. AI 코딩 에이전트를 써본 사람이라면 한 번쯤 겪어봤을 상황 — “시키지도 않은 파일을 덮어씌웠다”, “계획도 안 세우고 코드부터 갈아엎어 버렸다” — 이런 문제를 구조적으로 막는 게 Plan 모드의 출발점입니다.
기본값으로 켜진다는 게 생각보다 큰 차이입니다
💡 공식 발표문과 실제 사용 흐름을 같이 놓고 보니 이런 차이가 보였습니다
Plan 모드는 사용자가 “켜는” 기능이 아닙니다. 반대로 원하지 않으면 직접 꺼야 합니다. 이 순서가 바뀐 것이 이 업데이트에서 가장 중요한 변화입니다.
대부분의 AI 도구 업데이트는 새 기능을 선택적으로 제공하고, 기존 워크플로우를 유지하고 싶은 사람은 기본값을 그대로 씁니다. Plan 모드는 반대입니다. Plan 모드가 기본값이고, 이전처럼 “바로 코드 수정” 방식으로 쓰고 싶다면 /settings 에서 직접 꺼야 합니다.
이 설계는 의도적입니다. 구글 공식 블로그에서 직접 밝힌 내용입니다. “If plan mode isn’t your cup of tea, disabling it is easy! Just type /settings and search for ‘Plan’ to toggle it off.” (출처: Google Developers Blog, 2026.03.11) 비활성화가 쉽다고 안내하지만, 시작점이 Plan 모드 켜진 상태라는 점은 변하지 않습니다.
실제로 Shift+Tab 을 누르면 Default → Auto-Edit → Plan 세 가지 모드를 순환할 수 있습니다. Plan 모드를 꺼버리면 이 순환에서 빠지고, enter_plan_mode 와 exit_plan_mode 도구도 함께 비활성화됩니다.
Plan 모드에서 쓸 수 있는 도구와 쓸 수 없는 것
Plan 모드에서 Gemini CLI가 사용할 수 있는 도구는 공식 문서에 명시된 허용 목록으로만 제한됩니다. (출처: geminicli.com/docs/cli/plan-mode, 2026.03.11 기준) 어떤 도구가 열려 있고 어떤 게 막혀 있는지 표로 정리했습니다.
| 분류 | 허용 도구 | 상태 |
|---|---|---|
| 파일시스템 읽기 | read_file, list_directory, glob |
✅ 허용 |
| 검색 | grep_search, google_web_search |
✅ 허용 |
| MCP 읽기 전용 | github_read_issue, postgres_read_schema 등 |
✅ 허용 (확인 필요) |
| 계획서 쓰기 | write_file, replace — .md 파일만, plans 디렉토리 한정 |
⚠️ 제한적 허용 |
| 코드 파일 수정 | 프로젝트 내 모든 파일 쓰기 | ❌ 차단 |
| 셸 명령 실행 | run_shell_command (git read 제외) | ❌ 기본 차단 |
MCP 읽기 전용 도구는 기본적으로 사용자 확인을 요청합니다. 정책 파일을 직접 수정하면 자동 승인으로 바꿀 수 있고, git status나 git diff도 별도 정책 파일로 Plan 모드에서 허용할 수 있습니다. 계획서 파일의 기본 저장 경로는 ~/.gemini/tmp/<project>/<session-id>/plans/ 이고, settings.json에서 프로젝트 루트 내부로 변경 가능합니다.
플래닝 중에 Pro, 실행 중에 Flash — 자동으로 바뀝니다
💡 기존 AI 도구들과 다르게 작동하는 부분을 공식 문서에서 확인했습니다
Plan 모드에서는 Gemini 3.1 Pro가 자동 투입됩니다. 사용자가 Pro 플랜이든 무료 플랜이든 상관없이, Plan 모드 진입 시 자동 모델 라우팅이 작동합니다.
공식 문서에는 이렇게 나와 있습니다. “While in Plan Mode, the CLI routes requests to a high-reasoning Pro model to ensure robust architectural decisions and high-quality plans. Once a plan is approved and you exit Plan Mode, the CLI detects the existence of the approved plan and automatically switches to a high-speed Flash model.” (출처: geminicli.com/docs/cli/plan-mode, 2026.03.11 기준)
전략 짜는 단계엔 추론 능력이 높은 Pro를, 실제 코드 작업엔 속도가 빠른 Flash를 씁니다. 이 전환이 자동으로 됩니다. 따로 모델을 지정하지 않아도 됩니다. 이 설정은 settings.json에서 "modelRouting": false 로 끌 수 있습니다.
이 구조가 의미하는 건 간단합니다. 비용이 더 드는 추론 모델을 “필요한 시점”에만 쓴다는 뜻입니다. 플래닝에만 Pro를 쓰고 나머지는 Flash로 처리하면, 전체 세션에 Pro를 계속 쓰는 것보다 토큰 비용이 줄어듭니다. 특히 Pay-As-You-Go 방식으로 API 키를 사용하는 경우에 직접적인 차이가 납니다.
ask_user 도구가 없으면 Plan 모드의 절반입니다
이번 업데이트에서 Plan 모드와 함께 공개된 게 ask_user 도구입니다. 기존 AI 코딩 에이전트는 코드를 분석하다가 의도가 불분명한 부분이 나오면 그냥 가장 그럴싸한 쪽으로 선택하고 진행했습니다. 틀리면 나중에 되돌려야 했습니다. ask_user 는 이 단계에서 멈추고 사람에게 직접 물어봅니다.
공식 블로그 원문에는 이렇게 나와 있습니다. “Instead of making assumptions or guessing your intent, Gemini CLI can now present you with options, request clarification on a specific architectural choice, or ask for the location of a hidden configuration file. This bi-directional communication ensures that the final plan aligns perfectly with your vision before you commit to the implementation.” (출처: Google Developers Blog, 2026.03.11)
예를 들어 데이터베이스 마이그레이션을 요청하면, Plan 모드의 Gemini CLI는 현재 스키마를 읽고, 관련 이슈를 MCP로 확인하고, 문서를 검색한 뒤 — 여러 구현 방향 중 어느 쪽을 원하는지 물어봅니다. 구조 설계 결정에 사람이 끼어들 수 있는 지점이 생긴 겁니다. Conductor 확장이 이 도구를 가장 적극적으로 활용하는데, 각 마일스톤마다 ask_user 로 결정을 확인하며 진행합니다.
Claude Code랑 뭐가 다른지 직접 비교해봤습니다
💡 실사용자 후기와 공식 기능 설명을 교차해서 보니 이런 패턴이 보였습니다
Claude Code는 구조화된 플래닝 없이도 실행이 강하고, Gemini CLI는 플래닝 단계가 체계화된 대신 실제 코드 수정 완성도에서 차이가 납니다. 두 도구의 강점이 엇갈린 지점이 바로 여기입니다.
Reddit r/GeminiCLI(2026.03.06 게시)에 올라온 비교 스레드에서는 이런 평가가 나왔습니다. “Claude Code를 사용하는 데는 구조화된 워크플로우 없이도 코딩 작업을 해낼 수 있지만, Gemini CLI는 Conductor 같은 구조를 함께 써야 Claude Code 수준에 가까워진다.” (출처: Reddit r/GeminiCLI, 사용자 mystilleef, 2026.03.06) 코드 편집 완성도 자체는 Claude가 앞선다는 평이 우세합니다.
| 항목 | Gemini CLI + Plan 모드 | Claude Code |
|---|---|---|
| 플래닝 구조화 | ✅ 기본 내장, 강점 | 별도 지시 필요 |
| 코드 편집 완성도 | 들여쓰기 오류, 루프 발생 사례 | ✅ 안정적 평가 우세 |
| 무료 사용량 | ✅ 구글 계정 하루 1,000회 | 유료 플랜 기본 |
| 오픈소스 | ✅ GitHub 공개 | 비공개 |
| MCP 외부 소스 연동 | ✅ Plan 모드 내 읽기 전용 지원 | 지원 |
한 달간 같은 프로젝트에 세 가지 CLI 에이전트를 동시에 써본 Medium 기고(sohail_saifi, 2026.03.08)에서는 이렇게 정리했습니다. “I used it extensively for planning and specification work rather than direct coding.” Gemini CLI의 강점을 플래닝과 스펙 작업에 집중 활용했다는 겁니다. Plan 모드 도입 이후 이 용도가 더 명확하게 지원되는 구조가 됐습니다.
무료로 쓰면 어디까지 가능한지 확인한 수치
Gemini CLI 무료 한도는 인증 방식에 따라 다릅니다. 공식 요금 페이지(geminicli.com/docs/resources/quota-and-pricing, 2026.03.11 기준)에서 직접 확인한 수치입니다.
| 인증 방식 | 일일 한도 | 분당 한도 | 모델 |
|---|---|---|---|
| Google 계정 로그인 (무료) | 1,000회 | 60회 | Gemini 모델 패밀리 전체 |
| Gemini API 키 (무료) | 250회 | 10회 | Flash 모델만 |
| Google AI Pro (유료) | 구독 한도 기준 | 구독 한도 기준 | Gemini 모델 패밀리 전체 |
| Code Assist Standard (기업) | 1,500회 | 120회 | Gemini 모델 패밀리 전체 |
여기서 중요한 포인트가 있습니다. API 키 무료 방식은 Flash 모델만 사용 가능하고 하루 250회로 제한됩니다. Plan 모드에서 자동 모델 라우팅이 작동하려면 Google 계정 로그인 방식을 써야 합니다. API 키 무료 방식에서는 Plan 모드에서도 Pro 자동 라우팅이 적용되지 않습니다. 이 차이는 공식 문서에서 별도로 명시하지 않고 있지만, 요금 페이지의 모델 항목에서 확인할 수 있습니다.
/stats model 명령으로 현재 세션의 토큰 사용량과 남은 한도를 실시간으로 확인할 수 있습니다. Pay-As-You-Go를 쓴다면 세션 종료 시에도 사용량 요약이 출력됩니다.
Q&A
마치며
Gemini CLI Plan 모드는 기능 추가라기보다 철학의 변화에 가깝습니다. 기존 AI 코딩 에이전트가 “행동 먼저, 검토 나중”으로 작동했다면, Plan 모드는 그 순서를 뒤집어 “분석 먼저, 행동은 승인 후”를 기본값으로 만들었습니다.
솔직히 말하면, 코드 편집 완성도 면에서 Gemini CLI가 Claude Code를 따라잡으려면 아직 갈 길이 있습니다. 들여쓰기 오류, 루프 문제, 파일 수정 실패 등은 커뮤니티에서 반복적으로 지적되는 사안입니다. 반면 플래닝 구조화, 무료 사용량, 오픈소스 생태계에서는 확실한 강점이 있습니다.
쓸 만한 시나리오가 있습니다. 큰 리팩토링이나 DB 마이그레이션처럼 “코드를 건드리기 전에 전체 그림을 먼저 그려야 하는” 작업에 Plan 모드를 투입하고, 실제 구현은 더 안정적인 도구로 넘기는 방식입니다. Gemini CLI를 설계 도구로 쓰고, 실행 도구는 따로 가져가는 겁니다. 이 분업이 지금 시점에서 현실적인 활용법입니다.
📎 본 포스팅 참고 자료
- 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.11 기준)
https://geminicli.com/docs/cli/plan-mode/ - Gemini CLI 공식 문서 — Quota and Pricing
https://geminicli.com/docs/resources/quota-and-pricing/ - GitHub Discussions — Gemini CLI v0.33.0 Release Notes
https://github.com/google-gemini/gemini-cli/discussions/22078 - 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/
본 포스팅은 2026년 3월 21일 기준으로 작성됐습니다. Gemini CLI v0.33.0 기준이며, 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 요금·한도 수치는 공식 문서 기준이며, 구글 정책 변경 시 달라질 수 있습니다.
댓글 남기기