Plan 모드 공식 출시
Gemini CLI Plan 모드 직접 써봤습니다
— 되는 것과 안 되는 것
2026년 3월 11일, 구글이 Gemini CLI에 Plan 모드를 추가했습니다. “읽기 전용으로 안전하게 분석부터”라는 설명만 보면 꽤 든든해 보이는데, 실제로는 모드 승인 직후 자동으로 YOLO 모드로 전환되는 구조가 숨어 있습니다. 공식 문서를 직접 파고들었을 때 비로소 보이는 것들을 정리했습니다.
Plan 모드가 뭔지부터 — 공식 설명과 실제 작동 방식
Gemini CLI에 Gemini CLI Plan 모드가 추가된 건 2026년 3월 11일입니다. 구글 공식 개발자 블로그에서 직접 발표한 내용이고, 출시와 동시에 모든 사용자에게 기본값으로 켜졌습니다. (출처: Google Developers Blog, 2026.03.11)
작동 방식은 이렇습니다. Plan 모드로 진입하면 Gemini CLI는 파일을 읽고, 코드베이스를 탐색하고, 문서를 검색할 수 있지만, 파일을 직접 수정하거나 명령어를 실행하지 않습니다. 대신 ~/.gemini/tmp/ 경로 아래 플랜 폴더에만 Markdown 파일을 쓸 수 있습니다. 계획만 적어두는 것이죠.
진입 방법은 세 가지입니다. 터미널에 /plan을 타이핑하거나, Shift+Tab을 눌러 모드를 전환하거나, 자연어로 “이 기능 어떻게 만들지 계획 세워줘”라고 물으면 됩니다. 기본값이 Plan 모드로 설정돼 있으니 설치 직후 별도 설정 없이도 바로 작동합니다.
추가로 눈에 띄는 건 ask_user라는 도구입니다. 기존 AI 코딩 에이전트는 맥락을 혼자 판단해서 실행했는데, Plan 모드의 Gemini CLI는 모르는 부분이 생기면 직접 물어봅니다. 아키텍처 결정이나 설정 파일 위치를 묻는 식이죠. 계획과 사람 사이의 대화가 생기는 겁니다.
Plan 모드 안에서 실제로 쓸 수 있는 것들
공식 문서에서 확인한 허용 도구 목록을 실용 기준으로 정리하면 이렇습니다. (출처: geminicli.com/docs/cli/plan-mode, 2026.03.11 기준)
| 도구 유형 | 허용 여부 | 예시 |
|---|---|---|
| 파일 읽기 | ✅ 허용 | read_file, list_directory, glob |
| 코드 검색 | ✅ 허용 | grep_search, google_web_search |
| 서브에이전트 | ✅ 허용 | codebase_investigator |
| MCP 읽기 도구 | ⚠️ 조건부 허용 | github_read_issue, postgres_read_schema |
| 파일 쓰기(일반) | ❌ 차단 | 프로젝트 내 코드 파일 수정 불가 |
| 쉘 명령 실행 | ❌ 기본 차단 | 정책 파일로 일부 허용 가능 |
| 플랜 파일 쓰기 | ✅ 허용 | ~/.gemini/tmp/…/plans/*.md 만 가능 |
주목할 부분은 MCP 읽기 도구입니다. GitHub 이슈 읽기나 PostgreSQL 스키마 조회처럼 외부 시스템 연동도 Plan 모드 안에서 가능하지만, 기본 설정에서는 매번 사용자 확인을 요구합니다. 자동으로 허용하려면 정책 파일(~/.gemini/policies/)을 직접 작성해야 합니다.
여기서 걸립니다 — 승인 누르는 순간 벌어지는 일
💡 공식 문서의 비대화형 실행 항목과 플랜 모드 문서를 같이 읽어보니 이런 흐름이 보였습니다.
“Plan 모드 = 읽기 전용이니까 안전하다”라고 생각했다면, 이 부분이 중요합니다. 계획이 완성되고 사용자가 승인하는 순간 Plan 모드에서 자동으로 빠져나오는데, 이때 기본 모드가 아닌 YOLO 모드로 전환됩니다.
공식 문서의 해당 문장을 그대로 가져오면 이렇습니다.
“When exiting Plan Mode to execute the plan, Gemini CLI automatically switches to YOLO mode instead of the standard Default mode. This allows the CLI to execute the implementation steps automatically without hanging on interactive tool approvals.”
— Gemini CLI 공식 문서 (geminicli.com/docs/cli/plan-mode), 2026.03.11
즉, 헤드리스 환경(스크립트나 CI/CD 파이프라인)에서 플랜 모드로 시작하면 계획 승인 후 코드 실행까지 사람 확인 없이 자동으로 처리됩니다. 이것이 의미하는 건 Plan 모드의 안전성은 계획 단계에만 적용된다는 점입니다. 막상 실행 단계에서는 기존 기본 모드보다 더 자동화된 YOLO 모드가 가동됩니다.
인터랙티브 세션에서는 승인 방식을 고를 수 있습니다. “자동으로 편집 수락” 또는 “수동으로 편집 수락” 중 하나를 고르면 되고, 취소하려면 Esc입니다. 그러나 스크립트로 자동화해서 쓴다면 이 선택지가 사라진다는 점을 미리 알아야 합니다.
모델이 자동으로 바뀐다는 걸 몰랐습니다
💡 공식 발표문과 요금/쿼터 문서를 같이 놓고 보니 이 흐름이 보였습니다.
Plan 모드를 쓰면 자동 모델 라우팅(Automatic Model Routing)이 작동합니다. 이것도 공식 문서에 명시된 내용입니다.
계획 단계에서는 고추론 Pro 모델, 즉 Gemini 3.1 Pro를 사용해 아키텍처 결정의 품질을 높입니다. 계획이 승인되고 구현 단계로 넘어가면 자동으로 고속 Flash 모델로 전환합니다. (출처: Gemini CLI 공식 문서 — Automatic Model Routing, 2026.03.11)
이 구조가 의미하는 건 두 가지입니다. 첫째, 계획 품질을 높이기 위해 Pro 모델 쿼터를 소모합니다. 무료 계정으로 API 키 방식을 쓰고 있다면 Flash 모델만 허용되는 구간에서 Plan 모드가 예상대로 작동하지 않을 수 있습니다. 둘째, 자동 전환을 원하지 않는다면 설정에서 직접 끄면 됩니다.
// settings.json — 자동 모델 전환 끄기
{
“general”: {
“plan”: {
“modelRouting”: false
}
}
}
API 키 무료 등급을 쓰고 있다면 쿼터 구조도 확인이 필요합니다. Google 계정으로 로그인하면 하루 1,000회, 분당 60회지만, Gemini API 키 무료 등급은 하루 250회, 분당 10회로 훨씬 적습니다. Plan 모드에서 Pro 모델이 라우팅될 때 해당 쿼터를 소모한다는 점을 미리 알고 있어야 합니다. (출처: geminicli.com/docs/resources/quota-and-pricing, 2026.03.11)
Claude Code의 /plan과 뭐가 다른가
Reddit의 GeminiCLI 커뮤니티에서 실사용자 의견 중 가장 눈에 띈 건 이 댓글이었습니다.
“Plan 모드가 Claude Code가 원래 갖고 있던 기능을 따라잡고 있는 건 좋은데, MCP 제한이 실제 격차입니다. 플래닝의 가치 절반은 외부 상태(로그, DB 스키마, API 응답)를 쿼리해서 계획에 반영하는 건데.”
— Reddit r/GeminiCLI (germanheller, 2026.03.11)
비교해 보면 이렇습니다. Gemini CLI Plan 모드는 읽기 전용 MCP 도구를 지원하지만 기본값은 매번 사용자 확인을 요구합니다. 자동 허용하려면 정책 파일을 직접 작성해야 합니다. Claude Code의 경우 계획 단계에서 외부 컨텍스트 쿼리가 더 유연하게 작동한다고 알려져 있습니다.
반면 Gemini CLI만의 강점은 있습니다. 모델 라우팅 자동화(계획에 Pro, 실행에 Flash), Conductor 익스텐션을 통한 멀티트랙 개발 워크플로우, 그리고 Google Cloud·Workspace와의 통합입니다. Claude Code가 심층 추론에 강하다면, Gemini CLI는 Google 생태계와의 연결에서 앞섭니다. (출처: emergent.sh — Gemini CLI vs Claude Code 비교, 2026.03.15)
한 가지 더, ARC-AGI-2 벤치마크에서 Gemini 3.1 Pro는 77.1%를 기록했습니다. 이전 버전 Gemini 3 Pro 대비 2배 이상 향상된 수치입니다. (출처: Google 공식 블로그 — Gemini 3.1 Pro 발표, 2026.02.19) Plan 모드가 계획 단계에서 이 모델을 사용한다는 건, 추론 품질 면에서 이전보다 확실히 달라졌다는 의미입니다.
무료로 쓸 수 있지만, 이 조건에서 한도가 달라집니다
Gemini CLI는 무료로 쓸 수 있습니다. 하지만 인증 방식에 따라 쿼터가 크게 다릅니다. 이 차이를 모르면 Plan 모드가 갑자기 작동을 멈추는 이유를 모를 수 있습니다.
| 인증 방식 | 일일 한도 | 분당 한도 | 모델 범위 |
|---|---|---|---|
| Google 계정 로그인 | 1,000회 | 60회 | Gemini 전체 모델군 |
| Gemini API 키 (무료) | 250회 | 10회 | Flash 모델만 |
| Google AI Pro 구독 | 더 높음 | 더 높음 | Pro·Ultra 포함 |
| Vertex AI (Express) | 90일 무료 후 유료 | 가변 | 계정별 상이 |
중요한 점이 있습니다. Google AI Plus(월 5,500원)는 Gemini CLI 유료 플랜으로 지원되지 않습니다. 공식 요금 및 쿼터 문서에 명시되어 있습니다. “Tiers not listed above, including Google AI Plus, are not supported.” (출처: geminicli.com/docs/resources/quota-and-pricing, 2026.03.11)
따라서 Plan 모드에서 Gemini 3.1 Pro 모델 라우팅을 원한다면, Google 계정 로그인(무료) 또는 Google AI Pro(월 29,000원) 이상이 필요합니다. AI Plus 구독자가 Gemini CLI를 쓸 경우 기본 무료 쿼터(하루 1,000회)가 적용됩니다. 구독료를 내고 있는데 혜택이 적용되지 않는 케이스입니다.
Q&A
마치며
Gemini CLI Plan 모드는 “먼저 읽고, 나중에 실행한다”는 방향성 자체는 맞습니다. AI 코딩 에이전트가 먼저 판단하고 바로 파일을 수정해버리는 방식에 불안함을 느꼈다면 이 기능이 도움이 됩니다.
다만 써보면서 체감한 건, Plan 모드의 안전성은 계획 단계에 한정된다는 점입니다. 승인 직후 YOLO 모드로 자동 전환되는 부분, Pro 모델이 라우팅되면서 쿼터를 소모하는 구조, AI Plus 구독자에게 혜택이 없다는 점 — 이 세 가지는 공식 문서 안에 있지만 단순 소개 글에서는 잘 안 나오는 내용입니다.
인터랙티브하게 직접 쓰는 개발자라면 설정에서 수동 편집 수락으로 바꾸고 쓰는 게 제일 안전합니다. CI/CD 파이프라인에 붙이려는 경우라면 자동 YOLO 전환이 의도치 않은 변경으로 이어질 수 있다는 점을 미리 설계에 반영하는 게 좋습니다.
📚 본 포스팅 참고 자료
- Google Developers Blog — Plan mode is now available in Gemini CLI (developers.googleblog.com, 2026.03.11)
- Gemini CLI 공식 문서 — Plan Mode (geminicli.com/docs/cli/plan-mode, 2026.03.11)
- Gemini CLI 공식 문서 — Quotas and Pricing (geminicli.com/docs/resources/quota-and-pricing)
- Google Blog — Gemini 3.1 Pro 발표 (blog.google, 2026.02.19)
- DevOps.com — Gemini CLI Plan Mode Separates Thinking From Doing (devops.com)
- Reddit r/GeminiCLI — Plan mode launch discussion (reddit.com, 2026.03.11)
※ 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. Gemini CLI는 빠른 속도로 업데이트되는 오픈소스 프로젝트이며, 본문에 기재된 쿼터·모델·요금 정보는 2026년 3월 20일 기준입니다. 최신 정보는 공식 문서(geminicli.com/docs)에서 확인하시기 바랍니다.
댓글 남기기