Gemini CLI Plan 모드
Gemini CLI Plan 모드,
기본값으로 켜진 이유가 있습니다
코드를 건드리기 전에 먼저 생각하게 만드는 구조 — 왜 Google은 이걸 모든 사용자에게 기본으로 강제했을까요.
Plan 모드란 무엇인가, 한 줄로 정리하면
Gemini CLI Plan 모드는 에이전트가 코드를 수정하기 전에 반드시 읽기 전용으로 먼저 분석하도록 강제하는 실행 단계 분리 구조입니다. 2026년 3월 11일 v0.33.0으로 공개됐습니다. (출처: Google Developers Blog, 2026.03.11)
이 모드가 활성화된 동안 Gemini CLI는 read_file, grep_search, glob 같은 읽기 전용 도구만 사용할 수 있습니다. 파일 수정은 ~/.gemini/tmp/ 하위에 있는 계획 문서(.md)에만 허용됩니다. 즉, 프로젝트 파일에는 단 한 글자도 변경할 수 없습니다. (출처: geminicli.com/docs/cli/plan-mode)
단순히 “계획을 먼저 짠다”는 개념이 아니라, 실제로 도구 수준에서 쓰기 권한이 막혀 있는 물리적 격리 환경입니다. 막상 써보면 이 차이가 생각보다 크게 느껴집니다.
기본값으로 켜져 있다는 게 왜 중요한가
Plan 모드가 “기본값”이라는 건 단순한 설정 문제가 아닙니다. 이 결정은 AI 코딩 에이전트 업계 전체의 방향을 읽을 수 있는 단서입니다.
💡 공식 발표문과 업계 반응을 같이 놓고 보니 이런 흐름이 보였습니다
Futurum Group의 Mitch Ashley는 “Plan 먼저 실행 구조는 엔터프라이즈 도입에서 기본 거버넌스 요건이 될 것이며, 자율 실행을 기본값으로 두는 도구는 조달 과정에서 마찰을 겪게 될 것”이라고 분석했습니다. (출처: DevOps.com, 2026.03.11) 이 말을 다시 번역하면, Google이 Plan 모드를 기본으로 켠 건 개발자를 배려한 게 아니라 기업 고객을 먼저 겨냥한 설계라는 뜻입니다.
실제로 Cursor는 크레딧 소진 후 사용자가 영문도 모른 채 에이전트가 코드를 바꿔버리는 사례가 지속적으로 보고됐고, Claude Code도 “옳다고 판단하면 바로 실행”하는 방식이 팀 환경에서 갈등을 일으키는 경우가 있었습니다. Gemini CLI는 이 지점을 “기본값 변경”이라는 방식으로 정면 공략한 겁니다.
끄고 싶다면 /settings에서 “Plan” 검색 후 토글 해제하면 됩니다. Plan 모드가 필요 없는 사람에게도 진입 장벽은 없습니다. 하지만 기본으로 켜져 있기 때문에, 의식적으로 끄지 않으면 자동으로 안전하게 동작하는 구조입니다.
모델이 자동으로 바뀐다는 사실, 알고 있었나요
Plan 모드에서 가장 간과되기 쉬운 부분이 바로 모델 라우팅(Model Routing)입니다. 공식 문서가 조용히 적어두고 있지만, 대부분의 사용자는 이 흐름을 모릅니다.
💡 공식 문서에는 나와 있지만 실제 동작까지 따라가 보면 의외의 지점이 있습니다
| 단계 | 자동 배정 모델 | 이유 |
|---|---|---|
| Plan 모드 (설계·분석) | Gemini 3.1 Pro | 고추론 모델로 아키텍처 오류 최소화 |
| 구현 모드 (실제 코드 작성) | Flash 계열 | 속도 우선, 반복 편집에 최적 |
(출처: geminicli.com/docs/cli/plan-mode#automatic-model-routing, 2026.03.11)
이게 무슨 의미냐면, 플랜을 짤 때와 코드를 실제로 쓸 때 모델 자체가 다릅니다. 전략은 Pro가 짜고, 실행은 Flash가 한다는 뜻입니다. 단순히 “빠른 모델 vs 느린 모델” 수준이 아니라 추론 깊이가 구분됩니다.
이 자동 전환은 기본값으로 활성화돼 있습니다. 원하지 않으면 settings.json에서 "modelRouting": false로 끌 수 있습니다. 하지만 끄는 순간 Plan 단계에도 Flash 모델이 들어오기 때문에 아키텍처 오류 가능성이 올라갑니다.
MCP는 Plan 모드에서 안 된다고? 반은 맞고 반은 틀립니다
커뮤니티에서 가장 많이 오해하는 부분입니다. “Plan 모드 = MCP 불가”는 정확하지 않습니다.
공식 문서의 실제 규정은 이렇습니다: Plan 모드에서는 읽기 전용 MCP 도구만 허용됩니다. 예를 들어 GitHub 이슈 조회(github_read_issue), Postgres 스키마 조회(postgres_read_schema), Google Docs 검색은 가능합니다. 쓰기 작업이 포함된 MCP만 차단됩니다. (출처: geminicli.com/docs/cli/plan-mode#tool-restrictions)
⚠️ 단, 주의할 점: 읽기 전용 MCP 도구도 Plan 모드에서는 기본적으로 사용자 확인을 요구합니다. 자동 승인하려면 ~/.gemini/policies/에 TOML 정책 파일을 별도로 생성해야 합니다. 이 과정이 없으면 매번 수동으로 허용해야 해서 번거롭습니다.
Reddit의 한 사용자는 “MCP가 기본적으로 읽기 전용으로 취급되지 않는 점이 실제로 갭”이라고 지적했습니다. 쉽게 말해, 내가 연결한 MCP 서버가 읽기 전용임을 Gemini CLI가 자동으로 인식하지 못한다는 뜻입니다. 직접 정책 파일을 작성해서 명시해야 합니다. (출처: Reddit r/GeminiCLI, 2026.03.11)
이 부분은 Claude Code의 /plan 모드보다 현재 설정 과정이 복잡한 편입니다. 정책 엔진 TOML 파일 작성에 익숙하지 않다면, 처음에는 로컬 파일 시스템 중심으로만 쓰는 게 현실적입니다.
실제로 어떻게 쓰는가 — 진입·승인·탈출 흐름 전체
Plan 모드 진입 방법은 세 가지입니다. 인풋창에 /plan 입력, Shift+Tab으로 모드 순환, 또는 자연어로 “이 기능에 대한 계획을 세워줘”라고 입력하면 됩니다. 항상 Plan 모드로 시작하고 싶다면 gemini --approval-mode=plan으로 실행하거나 /settings에서 기본 승인 모드를 Plan으로 설정하면 됩니다.
계획이 완성되면 어떻게 됩니까
Gemini CLI는 분석이 끝나면 ~/.gemini/tmp/<project>/<session-id>/plans/에 Markdown 파일로 구현 계획서를 작성합니다. Ctrl+X를 누르면 VS Code나 Vim 같은 에디터로 바로 열 수 있고, 직접 수정하거나 코멘트를 달면 CLI가 그걸 읽고 계획을 수정합니다.
이 “계획서 직접 편집” 기능이 생각보다 강력합니다. 자연어로 피드백을 주는 것보다 계획서에 직접 “Wait, shouldn’t we use the existing Logger class here?”라고 써두는 게 훨씬 정밀하게 의도가 전달됩니다.
승인 후 Plan 모드를 자동으로 빠져나가면서 구현 단계로 전환됩니다. 이 전환 시점에 모델이 Pro → Flash로 바뀌는 것입니다. 30일간 세션 히스토리가 보존되고, 이후 자동 삭제됩니다. (출처: geminicli.com/docs/cli/session-management#session-retention)
Claude Code Plan 모드와 비교하면 어디서 걸립니까
Gemini CLI Plan 모드는 Claude Code의 /plan 기능에서 영감을 받은 구조임이 커뮤니티에서 공공연히 언급됩니다. 현실적인 비교를 정리하면 이렇습니다.
💡 같은 “Plan 모드”라는 이름인데 실제 동작을 나란히 놓고 보면 이 차이가 보였습니다
| 항목 | Gemini CLI (v0.33.0) | Claude Code |
|---|---|---|
| 기본값 | Plan 모드 ON | 수동 활성화 |
| 모델 자동 전환 | Pro↔Flash 자동 | 모델 고정 사용 |
| MCP 읽기 전용 지원 | 가능 (정책 설정 필요) | 기본 내장 |
| 무료 티어 | 일 1,000회 무료 | 없음 |
| SWE-bench (최상위 모델) | 76.2% (Gemini 3 Pro) | 80.9% (Opus 4.5) |
(출처: morphllm.com/ai-coding-agent, 2026년 3월 기준 / geminicli.com/docs/resources/quota-and-pricing)
추론 품질 면에서는 Claude Code가 아직 앞섭니다. 실제로 “코드 들여쓰기도 못 맞추고 루프에 빠진다”는 커뮤니티 지적도 있습니다. (출처: Reddit r/GeminiCLI, 2026.03.06) 이건 Plan 모드 자체의 문제라기보다 기반 모델의 코딩 완성도 차이입니다.
반면 Gemini CLI의 강점은 비용입니다. 일 1,000회 무료 사용 한도 안에서 Plan 모드 포함 모든 기능을 쓸 수 있습니다. Claude Code는 무료 티어가 없고, 헤비 유저 기준 월 $150~200까지 나옵니다. 이 수치는 “어느 도구가 더 좋냐”가 아니라 “어느 도구를 언제 써야 하냐”의 문제로 프레임이 바뀌는 근거입니다.
자주 묻는 질문
마치며 — 총평
Gemini CLI Plan 모드는 단순한 기능 추가가 아닙니다. AI 코딩 에이전트가 “바로 실행”에서 “먼저 검토”로 패러다임을 바꾸는 흐름 속에서, 구글이 선택한 방향이 이 기본값 설계에 담겨 있습니다.
솔직히 말하면, 지금 시점에서 코딩 완성도만 놓고 보면 Claude Code가 여전히 앞섭니다. 하지만 무료로 일 1,000회 Pro 모델에 접근하면서 읽기 전용 계획 단계까지 쓸 수 있는 도구는 Gemini CLI가 유일합니다. 이 가격 대비 기능 구조는 무시하기 어렵습니다.
MCP 정책 설정이 번거롭고 다중 파일 편집 안정성이 아직 부족한 건 실제 아쉬운 부분입니다. 하지만 Plan 모드에서 Conductor까지 완전히 통합되는 방향으로 개발이 계속되고 있어, 앞으로 몇 달이 중요한 시점입니다. 지금 써봐야 감이 잡히는 도구입니다.
본 포스팅 참고 자료
본 포스팅은 2026년 3월 20일 기준 Gemini CLI v0.33.0 공식 문서를 바탕으로 작성됐습니다.
본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 최신 정보는 공식 문서를 참고하세요.
댓글 남기기