무료 1,000회/일 · 읽기 전용 안전 모드
Gemini CLI Plan 모드, 안전하다고요?
이 조건 먼저 보세요
구글이 2026년 3월 11일 Gemini CLI에 Plan 모드를 정식 출시했습니다. “실수로 파일을 건드리지 않는 읽기 전용 모드”라는 설명은 맞습니다. 그런데 막상 써보면, 이 모드가 동작하지 않는 조건이 있고, 무료 한도가 생각보다 빠르게 소진됩니다. 결론부터 말씀드리면, Plan 모드는 분명히 유용하지만 두 가지를 먼저 알고 쓰는 것과 모르고 쓰는 것 사이에 꽤 큰 차이가 있습니다.
Plan 모드, 도대체 어떤 기능인가요?
구글이 2026년 3월 11일 공식 블로그를 통해 발표한 Plan 모드는 Gemini CLI의 실행 권한을 읽기 전용으로 제한하는 모드입니다. (출처: Google Developers Blog, 2026.03.11) 쉽게 말하면, 코드를 고치기 전에 먼저 “무엇을 어떻게 바꿀지” 계획서를 Markdown 파일로 작성하고 사용자가 승인해야만 실제 수정이 시작되는 구조입니다.
이 모드에서 Gemini CLI가 사용할 수 있는 도구는 read_file, grep_search, list_directory, glob, google_web_search, 그리고 ask_user로 제한됩니다. 파일을 생성하거나 덮어쓰는 것은 불가능하고, 오직 계획서(~/.gemini/tmp/ 하위의 .md 파일)만 쓸 수 있습니다. (출처: Gemini CLI 공식 문서, 2026.03.11)
진입 방법은 세 가지입니다. 터미널에서 /plan을 입력하거나, Shift+Tab으로 모드를 순환하거나, 그냥 자연어로 “이 기능 추가하기 전에 먼저 계획 세워줘”라고 말하면 됩니다. 기본값으로 이미 활성화돼 있어서 별도 설치나 설정 없이 쓸 수 있습니다.
무료라는데, 정작 Plan 모드에서 어떤 모델이 쓰이나요?
💡 공식 발표문과 실제 과금 구조를 같이 놓고 보니 이런 차이가 보였습니다.
Gemini CLI 무료 티어는 하루 1,000번 요청이 가능하다고 알려져 있습니다. 그런데 이 한도는 주로 Gemini Flash 모델 기준입니다. Plan 모드는 설계 단계에서 자동으로 Gemini 3.1 Pro 모델로 라우팅됩니다. Pro 모델의 무료 한도는 Flash보다 현저히 낮습니다. 즉, Plan 모드를 쓰는 순간 1,000번의 여유가 아니라 훨씬 짧은 한도에서 시작한다는 뜻입니다.
공식 문서에 따르면 Plan 모드는 “자동 모델 라우팅(Automatic Model Routing)” 기능을 통해 계획 단계에서는 고추론 Pro 모델을, 구현 단계에서는 고속 Flash 모델을 사용합니다. (출처: Gemini CLI 공식 문서 — Automatic Model Routing, 2026.03.11) 이 구조 자체는 품질 면에서 훌륭한 설계입니다.
문제는 Pro 모델 무료 사용량 관련 Reddit 커뮤니티에서 “1,500회도 안 되는데 한도 초과 메시지가 뜬다”는 보고가 여러 건 올라와 있다는 점입니다. (출처: r/GeminiCLI, 2026.03.08) 무료 계정 기준 Pro 모델 한도는 Flash 한도와 별도로 훨씬 빠르게 소진된다는 의미입니다. 계획이 복잡해질수록, 그리고 `ask_user` 도구를 통한 대화가 길어질수록 Plan 모드에서의 토큰 소비는 증가합니다.
이 부분이 아쉬웠습니다. “무료로 Pro 성능을 쓴다”는 인식이 퍼져 있는데, 막상 Plan 모드를 집중적으로 사용하면 하루 안에 Pro 한도에 걸릴 수 있습니다. /settings에서 Default Approval Mode를 Plan으로 고정해두면 세션 시작부터 Pro 모델이 돌기 때문에 한도 소진이 더 빨라집니다.
⚠️ 실용 팁: 무료 계정이라면 /settings에서 Default Approval Mode를 Default로 유지하고, 복잡한 작업 직전에만 수동으로 /plan을 입력하는 방식이 Pro 한도 절약에 유리합니다.
YOLO 모드에서는 Plan 모드가 안 됩니다
💡 “모든 작업을 자동 승인”하는 YOLO 모드와 “계획 먼저 세우는” Plan 모드, 둘 다 편해 보여서 같이 쓰고 싶어지는데 — 공식 문서를 보면 이건 구조적으로 함께 쓸 수 없습니다.
Gemini CLI에는 네 가지 승인 모드가 있습니다. Default(매번 확인), Auto-Edit(파일 수정은 자동 승인), Plan(읽기 전용 계획), 그리고 YOLO(모든 작업 자동 승인)입니다. 이 중 YOLO 모드에서는 enter_plan_mode 도구 자체가 등록되지 않습니다. (출처: Gemini CLI 공식 설정 문서, 2026.03.11)
이게 핵심입니다. YOLO 모드를 쓰는 사람들은 보통 “어차피 내가 다 확인할 거니까 빠르게 처리하자”는 의도입니다. 그런데 YOLO 모드에서는 Plan 모드로 진입하는 명령어(/plan)도, 자연어로 “계획 먼저 세워줘”라고 말해도 Plan 모드로 전환되지 않습니다. YOLO 모드의 철학(즉각 실행)과 Plan 모드의 철학(먼저 계획)이 설계 수준에서 충돌하기 때문입니다.
자동화 스크립트나 CI/CD 파이프라인에서 gemini --yolo를 쓰면서 동시에 Plan 모드의 아키텍처 분석 결과를 기대하는 경우라면 이 부분에서 막힙니다. Plan 모드가 필요한 작업이라면 YOLO 플래그 없이 Default 또는 Auto-Edit 모드에서 시작해야 합니다.
Claude Code와 실제로 비교해보면 어떤가요?
“계획 먼저 세우는 AI” 측면에서 Claude Code와 Gemini CLI Plan 모드를 비교하는 시선이 많습니다. 실제 벤치마크 결과를 보면 생각보다 차이가 분명합니다. InventiveHQ의 실제 프로젝트 기반 테스트(Express.js API 12개 엔드포인트 리팩토링, 2026년 2월 기준)에서 Claude Code(Opus 4.6)는 1시간 17분, API 비용 $4.80에 완전 자율 완료했습니다. Gemini CLI는 2시간 4분, $7.06이 들었고 중간에 3번 수동 개입이 필요했습니다. (출처: InventiveHQ 비교 분석, 2026.02.13)
| 항목 | Gemini CLI (Plan 모드) | Claude Code (Opus 4.6) |
|---|---|---|
| 1차 코드 정확도 | 85~88% | 약 95% |
| 컨텍스트 윈도우 | 1M 토큰 (기본) | 200K (1M 베타) |
| 최대 출력 토큰 | 65K | 128K |
| 무료 사용 가능 | ✅ (Flash 1,000회/일) | 기본 경량 사용 한정 |
| 멀티 에이전트 | ❌ | ✅ (Agent Teams) |
| 웹 검색 그라운딩 | ✅ (Google Search) | ❌ |
수치가 의미하는 것은 이렇습니다. Plan 모드의 진짜 강점은 “1M 토큰 컨텍스트 + Google 실시간 검색”의 조합입니다. 최신 라이브러리나 이제 막 나온 API를 다루는 작업에서는 Gemini CLI가 현재 문서를 실시간으로 참조하기 때문에 Claude Code보다 유리한 상황이 생깁니다. 반면 대규모 자율 리팩토링처럼 “한 번 시키고 결과물을 받아오는” 작업이라면 Claude Code의 정확도와 자율성이 더 적합합니다.
Plan 모드를 제대로 쓰는 흐름
생각보다 간단합니다. Gemini CLI를 열고 /plan을 입력하거나 자연어로 “이 기능 구현하기 전에 코드베이스 분석하고 계획 먼저 잡아줘”라고 말하면 됩니다. 그러면 Gemini CLI가 읽기 전용 상태에서 codebase_investigator 서브에이전트를 활용해 의존성을 파악하고, 중간에 ask_user를 통해 선택지를 제안합니다.
계획서가 완성되면 Ctrl+X를 눌러 외부 에디터(VS Code, Vim 등)에서 직접 수정할 수 있습니다. 단계를 바꾸거나, 특정 부분에 “여기서 기존 Logger 클래스를 재사용해야 하지 않을까?” 같은 코멘트를 남기면 Gemini CLI가 이를 반영해 계획을 다듬습니다. 승인하는 순간 자동으로 Auto-Edit 모드로 전환되면서 구현이 시작됩니다.
Plan 모드에서 작성된 계획서는 기본적으로 ~/.gemini/tmp/<project>/<session-id>/plans/에 저장되며, 30일간 보관됩니다. 팀 프로젝트에서 계획서를 버전 관리에 포함하고 싶다면 settings.json에서 plan.directory를 프로젝트 내 경로로 변경하면 됩니다. 단, 이 경우 custom policy도 함께 수정해야 쓰기 권한이 부여됩니다.
이 경우엔 Plan 모드보다 다른 방법이 낫습니다
💡 Plan 모드의 장점만 정리한 글들은 많은데, 실제로 쓰다 보면 이런 경우에는 오히려 더 느리고 비효율적입니다.
간단한 버그 수정이나 한두 줄 변경이라면 Plan 모드는 과잉입니다. Plan 모드는 분석-대화-계획서 승인의 단계를 거치는 구조이므로, 파일 하나의 함수 하나를 고치는 작업에서는 그냥 Default 모드로 바로 요청하는 게 훨씬 빠릅니다.
또 외부 API를 실시간으로 호출하거나 터미널 명령을 실행해야 하는 작업은 Plan 모드에서 불가능합니다. Plan 모드의 허용 도구 목록에 run_shell_command는 없습니다. Git 상태 확인(git status, git diff)조차 기본값에서는 허용되지 않고 custom policy를 직접 작성해야 합니다. 이 부분이 좀 아쉬웠습니다. (출처: Gemini CLI 공식 문서 — Custom Policies, 2026.03.11)
CI/CD 파이프라인에서 자동화 목적으로 쓰는 경우에도 주의가 필요합니다. Plan 모드는 ask_user 도구를 통해 사용자에게 질문하도록 설계돼 있어서, 완전한 비대화형(headless) 환경에서는 중간에 멈출 수 있습니다. 파이프라인에서 Plan 모드를 활용하려면 Conductor 같은 워크플로 확장을 추가로 구성해야 합니다.
Q&A — 자주 묻는 것들
마치며 — 솔직한 총평
Gemini CLI Plan 모드는 2026년 3월 기준으로 AI 코딩 도구 중 가장 뚜렷한 “안전 설계”를 가진 기능 중 하나입니다. 파일을 건드리기 전에 계획서를 만들고, 사용자가 검토 후 승인하는 구조는 실수를 줄이는 데 실질적으로 효과가 있습니다. Google 검색 그라운딩이 Plan 모드에서도 동작한다는 점, 그리고 무료로 시작할 수 있다는 점은 진입 장벽을 낮춰줍니다.
그렇지만 YOLO 모드에서는 아예 동작하지 않는다는 것, 무료 계정의 Pro 모델 한도가 생각보다 빠르게 소진된다는 것, Git 명령이나 셸 실행이 기본값에서는 허용되지 않는다는 점은 알고 시작하는 게 낫습니다. 모르고 쓰다가 “왜 안 되지?”에서 시간을 쓰는 경우를 줄일 수 있습니다. 1M 토큰 컨텍스트와 실시간 웹 검색의 조합이 필요한 작업이라면 Plan 모드는 분명히 써볼 만합니다.
기준 버전: Gemini CLI (2026.03.11 Plan 모드 정식 출시 / Gemini 3.1 Pro 자동 라우팅 기준)
본 포스팅 참고 자료
본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. Gemini CLI는 매주 화요일 안정 버전이 업데이트되며, Plan 모드 관련 정책 및 한도는 Google의 공지 없이 변경될 수 있습니다. 최신 정보는 공식 문서(geminicli.com/docs)에서 확인하시기 바랍니다.
댓글 남기기