Gemini CLI 최신 버전
TECH
Gemini CLI Plan 모드, 안전하다더니 이 조건엔 다릅니다
결론부터 말씀드리면 — Plan 모드가 기본값으로 켜져 있고 읽기 전용이라 “사고가 날 일이 없다”는 말은 절반만 맞습니다. 인증 방식에 따라 모델 자동 라우팅이 통째로 빠지고, write_file 설계 특성 때문에 특정 상황에선 오히려 더 위험합니다. 공식 문서에서 직접 확인한 내용입니다.
Plan 모드가 생긴 이유 — 기존 방식의 실제 문제
Gemini CLI에는 원래 세 가지 승인 모드가 있었습니다. 매번 확인을 요청하는 Default, 자동으로 파일을 수정하는 Auto-Edit, 그리고 아무것도 확인 없이 실행하는 YOLO 모드입니다. 문제는 Auto-Edit이나 YOLO를 쓰다 보면 AI가 코드를 잘못 수정해도 이미 파일이 바뀐 뒤라는 점입니다.
구글이 2026년 3월 11일 공식 블로그에서 밝힌 Plan 모드의 도입 취지는 이 문제를 해결하기 위함입니다. “요청을 분석하고, 복잡한 변경사항을 계획하고, 코드베이스나 의존성을 파악하는 작업을 먼저 읽기 전용 상태에서 처리한다”고 명시했습니다. (출처: Google Developers Blog, 2026.03.11)
생각보다 중요한 변화는 출시 방식에 있습니다. Plan 모드는 선택 기능이 아니라 기본값(Default)으로 배포됐습니다. 즉 새로 설치하거나 업데이트하면 별도 설정 없이 Plan 모드가 켜져 있습니다. AI 코딩 도구가 “실행 전 계획 수립”을 기본 흐름으로 강제한 건 이번이 처음입니다.
Plan 모드가 실제로 하는 일 — 공식 문서 기준
Plan 모드에서 Gemini CLI가 사용할 수 있는 도구는 공식 문서에 정확히 나열돼 있습니다. 허용 도구는 파일 읽기(read_file, glob, list_directory), 검색(grep_search, google_web_search), 사용자 질문(ask_user)입니다. 파일 수정 도구는 플랜 파일(.md)에 한해서만 허용됩니다. (출처: geminicli.com/docs/cli/plan-mode, 2026.03)
새로 추가된 ask_user 도구가 실제로 어떻게 작동하는지 공식 블로그에 잘 설명돼 있습니다. AI가 추측 대신 사용자에게 직접 묻습니다. “이 아키텍처 선택지 중 어느 걸 원하세요?”, “설정 파일 위치를 알려주세요” 같은 식으로 중간에 멈추고 확인합니다. 그냥 AI가 마음대로 구현하는 게 아니라 계획 단계에서 사용자가 직접 방향을 잡아주는 구조입니다.
Plan 모드 진입 방법은 세 가지입니다. 입력창에 /plan을 입력하거나, Shift+Tab으로 모드를 순환하거나, “이 기능 계획 잡아줘”처럼 자연어로 요청해도 됩니다. 계획이 완성되면 ~/.gemini/tmp/ 경로에 Markdown 파일로 저장되고, Ctrl+X로 외부 에디터에서 직접 수정도 가능합니다.
Plan 모드에서도 MCP 읽기 전용 도구는 허용됩니다. GitHub 이슈 읽기, Postgres 스키마 조회 등이 가능합니다. 단, 기본 설정에서는 MCP 읽기 도구도 사용자 확인이 필요합니다. 자동 허용을 원하면 ~/.gemini/policies/에 별도 정책 파일을 만들어야 합니다. (출처: geminicli.com/docs/cli/plan-mode, 2026.03)
모델 자동 라우팅 — 인증 방식이 다르면 작동도 다릅니다
이 부분이 대부분의 소개 글에서 빠져 있습니다. Plan 모드에는 자동 모델 라우팅 기능이 내장돼 있습니다. 공식 문서에 정확히 이렇게 나옵니다.
Plan 모드 중에는 Gemini 3.1 Pro가, 구현 중에는 Flash 계열이 자동으로 붙습니다. Plan 모드에서 높은 추론 능력이 필요하고, 구현은 속도가 중요하다는 판단입니다.
문제는 이 라우팅이 Google 계정 로그인 또는 Gemini Code Assist 구독 사용자에게만 온전히 적용된다는 점입니다. 공식 요금 문서를 교차해서 확인하면 이렇게 정리됩니다.
| 인증 방식 | 무료 한도 | Plan 모드 Pro 라우팅 | 사용 가능 모델 |
|---|---|---|---|
| Google 계정 로그인 | 1,000회/일 60회/분 |
✅ 지원 | Gemini 계열 전체 |
| API Key (무료) | 250회/일 10회/분 |
⚠️ Flash만 가능 | Flash 계열만 |
| Code Assist Standard | 1,500회/일 120회/분 |
✅ 지원 | Gemini 계열 전체 |
| Code Assist Enterprise | 2,000회/일 120회/분 |
✅ 지원 | Gemini 계열 전체 |
(출처: geminicli.com/docs/resources/quota-and-pricing, 2026.03)
API Key로만 쓰는 사람은 Plan 모드에서도 Flash 모델이 그대로 사용됩니다. 추론 품질이 낮은 상태로 “계획”을 세우는 셈입니다. “Plan 모드 = 더 정교한 계획”이라는 공식은 Google 계정 사용자 기준입니다.
읽기 전용인데도 파일이 사라진 사례 — 왜 이런 일이 생기는가
Plan 모드가 읽기 전용이라 해도, Plan 모드 바깥 즉 구현 단계에서는 여전히 파일 수정이 일어납니다. 그리고 Gemini CLI의 write_file 도구는 추가(append) 기능 없이 덮어쓰기(overwrite)만 지원합니다. 이 두 가지가 만나면 어떤 일이 생기는지 GitHub 공개 토론에서 실사례가 기록됐습니다.
AI가 “Phase 23 내용을 journal.md에 추가하겠다”고 말한 뒤, write_file로 Phase 23만 담긴 새 파일을 덮어썼습니다. 기존에 있던 Phase 1~22 전체가 삭제됐습니다. 모델은 나중에야 파일이 사라진 걸 알아챘습니다. (출처: github.com/google-gemini/gemini-cli/discussions)
이 사례의 핵심은 Plan 모드 자체의 문제가 아니라 구현 단계 도구 설계의 문제라는 점입니다. Plan 모드로 안전하게 계획을 세웠더라도, 계획 승인 후 구현 단계에서 write_file이 append 대신 overwrite로 동작하면 데이터가 사라집니다. Plan 모드를 쓴다고 이 위험이 없어지는 건 아닙니다.
공식 문서에는 Plan 모드가 “안전 탐색”을 위한 것이라고 나오지만, Plan 모드를 통과한 이후의 구현 단계에 대한 안전 장치 설명은 없습니다. Plan 모드는 계획을 잘못 세우는 위험을 줄이는 것이지, 구현 중 파일 손상 위험을 막는 기능이 아닙니다. 이 두 가지는 다른 문제입니다.
Claude Code와 뭐가 다른가 — 요금·기능 직접 비교
현재 터미널 AI 코딩 도구 시장에서 Gemini CLI와 가장 많이 비교되는 건 Claude Code입니다. 핵심 차이점을 공식 자료 기준으로 정리하면 이렇습니다.
| 항목 | Gemini CLI | Claude Code |
|---|---|---|
| 오픈소스 | ✅ GitHub 공개 | ❌ 비공개 |
| Plan 모드 | ✅ 기본 탑재 | ❌ 없음 |
| 컨텍스트 윈도우 | 약 100만 토큰 | 약 20만 토큰 |
| 무료 한도 | 1,000회/일 (Google 계정) | 제한적 |
| MCP 지원 | ✅ 전체 지원 | 부분 지원 |
| 모델 자동 라우팅 | ✅ Plan→Pro, 구현→Flash | ❌ 단일 모델 |
(출처: geminicli.com/docs, netcomlearning.com/blog/gemini-cli, 2026.03)
컨텍스트 윈도우 100만 토큰이 실제로 의미하는 건 대형 레거시 코드베이스 전체를 한 번에 올릴 수 있다는 뜻입니다. 파일 수백 개를 분할해서 보내지 않아도 됩니다. Claude Code가 더 정교한 추론으로 평가받지만, 대형 프로젝트 단위 작업에서 컨텍스트 제약은 실제 병목이 됩니다.
Plan 모드 제대로 쓰는 조건 3가지
지금까지 확인한 내용을 바탕으로 Plan 모드를 온전히 활용하려면 아래 조건을 갖추는 게 낫습니다.
Google 계정으로 인증하기 — API Key 무료 플랜이면 모델 라우팅이 빠집니다
Plan 모드에서 Gemini 3.1 Pro 수준의 추론을 쓰려면 Google 계정 로그인이 필요합니다. API Key 무료 플랜은 Flash 계열만 허용되므로 “계획 단계 = 더 똑똑한 모델”이라는 공식이 적용되지 않습니다. Google 계정으로 전환하면 하루 1,000회 요청까지 무료이고 Pro 라우팅도 살아납니다. (출처: geminicli.com/docs/resources/quota-and-pricing, 2026.03)
구현 전 Git 커밋 또는 백업 필수 — Plan 모드는 구현 중 손상을 막지 않습니다
Plan 모드는 계획 수립 단계를 안전하게 해주지만, 계획 승인 후 구현 단계에서 write_file은 여전히 덮어쓰기 방식으로 동작합니다. 실사용 사례에서 확인됐듯 AI가 “추가”라고 말해도 실제론 덮어쓸 수 있습니다. Plan 모드를 승인하기 전 git commit 또는 파일 백업을 먼저 해두는 게 현실적인 안전망입니다.
플랜 디렉토리를 프로젝트 안으로 옮기면 이력 관리가 됩니다
기본적으로 플랜 파일은 ~/.gemini/tmp/에 저장되고 30일 후 자동 삭제됩니다. settings.json에서 "directory": ".gemini/plans"로 바꾸면 프로젝트 디렉토리 안에 플랜이 쌓입니다. git 이력에 계획 파일까지 포함되므로 나중에 “왜 이렇게 구현했나”를 추적하기 훨씬 쉬워집니다. 단, 커스텀 디렉토리를 쓰면 자동 삭제가 안 되므로 수동으로 관리해야 합니다. (출처: geminicli.com/docs/cli/plan-mode, 2026.03)
자주 나오는 질문 5가지
마치며
Gemini CLI Plan 모드는 분명 의미 있는 업데이트입니다. AI 코딩 도구가 “일단 실행”에서 “계획 먼저”로 기본 흐름을 바꾼 건, 실제 개발 현장에서 AI가 일으키는 사고를 구글이 진지하게 인식하고 있다는 신호입니다.
다만 막상 써보면 다릅니다. Plan 모드가 켜져 있다고 해서 모든 게 안전한 건 아닙니다. 인증 방식에 따라 Plan 모드에서 쓰이는 모델이 달라지고, Plan 모드를 통과한 이후 구현 단계에서도 여전히 데이터 손상 위험이 있습니다. “읽기 전용 = 안전”이라는 공식은 계획 단계에만 해당됩니다.
개인적으로는 Google 계정 인증 + 구현 전 git commit을 한 세트로 묶어서 습관처럼 쓰는 게 현실적인 사용법이라고 봅니다. 이렇게 하면 Plan 모드의 장점인 Pro 모델 라우팅도 살리고, 구현 단계의 위험도 줄일 수 있습니다.
- 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
https://geminicli.com/docs/cli/plan-mode/ - Gemini CLI 공식 문서 — Quotas and Pricing
https://geminicli.com/docs/resources/quota-and-pricing/ - GitHub — Gemini CLI 사용자 토론 (실사용 사례)
https://github.com/google-gemini/gemini-cli/discussions/7432
※ 본 포스팅은 2026년 3월 23일 기준으로 작성됐습니다. Gemini CLI는 활발하게 업데이트 중인 오픈소스 프로젝트이며, 본 포스팅 작성 이후 서비스 정책·UI·기능·요금이 변경될 수 있습니다. 최신 정보는 공식 문서(geminicli.com/docs)에서 확인하세요.
댓글 남기기