Plan 모드, 3월 11일에 무엇이 바뀌었나

Gemini CLI v0.33.0 업데이트가 2026년 3월 11일에 배포됐습니다. 이 버전에서 처음으로 Plan 모드가 정식 기능으로 CLI 내부에 탑재됐습니다. (출처: Google Gemini CLI GitHub 릴리스 노트, 2026.03.11)

이전까지는 Conductor라는 별도 익스텐션을 설치해야만 비슷한 계획 수립 흐름을 쓸 수 있었습니다. Gemini CLI 커뮤니티에서 “플랜 모드 언제 나오냐”는 요청이 꾸준히 올라왔는데, 실제로 구글 팀원이 해당 스레드에 직접 댓글을 달며 개발 진행 상황을 공유했을 만큼 수요가 많았습니다.

Plan 모드의 핵심 설계 원칙은 하나입니다. 코드 변경 없이 탐색·설계·계획만 허용하는 읽기 전용 환경입니다. Shift+Tab으로 모드를 전환하거나 /plan 명령어로 바로 진입할 수 있습니다. (출처: Gemini CLI 공식 문서 — Plan Mode)

읽기 전용이라도 이 도구만은 쓸 수 있습니다

Plan 모드 진입 시 허용되는 도구 목록이 공식 문서에 명확히 나와 있습니다. 파일 시스템은 읽기(read_file, list_directory, glob)만 가능하고, 쓰기는 단 한 군데 — ~/.gemini/tmp/<project>/<session-id>/plans/ 경로 안의 .md 파일에만 허용됩니다.

그런데 여기서 놓치기 쉬운 부분이 있습니다. MCP(Model Context Protocol) 도구 중 읽기 전용으로 표시된 것은 Plan 모드에서도 연결 가능합니다. 예를 들어 GitHub 이슈 조회, PostgreSQL 스키마 읽기 같은 외부 데이터 소스를 끌어다 쓸 수 있습니다. 단, 기본값은 여전히 “사용자 확인 필요”이며, 자동 허용으로 바꾸려면 정책 파일을 직접 작성해야 합니다.

ask_user 도구도 허용 목록에 포함되어 있어, Plan 모드 중에 CLI가 먼저 질문을 던지며 방향을 잡을 수 있습니다. 단순히 파일을 훑는 게 아니라 양방향 대화로 설계 방향을 좁혀가는 구조입니다.

무료 계정에서 Pro 모델이 실제로 쓰이는지 확인했습니다

공식 문서는 Plan 모드 진입 시 “고추론 Pro 모델을 자동 배정한다”고 설명합니다. 구체적으로는 Auto 모델 설정을 사용하면 Plan 단계에서 Gemini 3.1 Pro, 구현 단계에서 Gemini 3.1 Flash로 자동 전환됩니다. (출처: Gemini CLI 공식 문서 — Automatic Model Routing)

공식 한도 구조는 다음과 같습니다. (출처: Gemini CLI 공식 문서 — Quota and Pricing)

API 키 무료 티어는 Flash 모델만 접근 가능합니다. Plan 모드 자동 라우팅이 “Pro로 올려준다”고 해도, 이 경우에는 라우팅 자체가 Flash 위에서만 동작합니다. 무료로 쓰면서 Plan 모드의 “고추론 설계”를 기대했다면, 실제 모델 수준이 다를 수 있습니다.

CI/CD에서 Plan 모드를 끝내는 순간 생기는 일

이 부분이 가장 놓치기 쉬운 지점입니다. 공식 문서의 비대화형(non-interactive) 실행 섹션에 명시된 내용인데, 일반 사용 안내에는 잘 드러나지 않습니다. (출처: Gemini CLI 공식 문서 — Non-interactive execution)

명확히 하면, 이 동작은 의도된 설계입니다. 공식 문서는 “헤드리스 환경에서 대화 승인 대기로 파이프라인이 멈추는 문제를 방지하기 위해” YOLO 전환이 자동으로 이루어진다고 설명합니다.

다만 이 설계는 “Plan 모드 → 검토 → 구현”이라는 흐름을 CI 자동화에 그대로 가져오면 기대했던 것과 다르게 작동한다는 뜻이기도 합니다. CI 파이프라인에서 Plan 모드를 쓰려면, 플랜 생성 단계와 실행 단계를 별도 스크립트로 분리해야 합니다.

플랜 파일은 30일 뒤 사라집니다 — 직접 관리가 필요한 이유

Plan 모드가 생성하는 .md 플랜 파일은 기본값으로 30일 보관됩니다. 세션이 만료되거나 gemini --delete-session으로 삭제하면 연관 플랜 파일도 함께 지워집니다. (출처: Gemini CLI 공식 문서 — Session Retention)

기본 저장 경로는 ~/.gemini/tmp/<project>/<session-id>/plans/로, 프로젝트 디렉토리 밖입니다. 팀 작업에서 플랜을 공유하거나 Git 리포지토리에 함께 커밋하려면, settings.json에서 플랜 저장 경로를 프로젝트 내부로 변경해야 합니다.

커스텀 경로를 설정하면 자동 삭제가 적용되지 않습니다. 직접 관리해야 하는 쪽으로 책임이 넘어오는 구조이므로, 팀 운영 정책을 미리 정해두는 게 좋습니다.

Plan 모드가 어울리는 작업과 어울리지 않는 작업

공식 문서는 데이터베이스 마이그레이션 검토, 신규 기능 설계, 보안 감사 계획 등을 Plan 모드의 적합 사례로 소개합니다. 코드베이스를 망가뜨릴 위험 없이 “지금 건드리면 어디까지 영향이 가는가”를 사전에 파악하는 용도로 씁니다.

반면 아래 상황에서는 Plan 모드 단독으로는 기대와 다를 수 있습니다.

• API 키 무료 티어 사용자: Flash 모델만 쓸 수 있어, “고추론 계획”을 기대하기 어렵습니다.
• CI/CD 파이프라인 자동화: Plan 종료 후 YOLO 전환이 자동으로 일어납니다. 단계를 분리하지 않으면 코드 변경이 승인 없이 실행됩니다.
• 플랜을 팀과 공유하는 경우: 기본 저장 경로가 개인 홈 디렉토리 안이라, 별도 설정 없이는 Git에 올릴 수 없습니다.
• YOLO 모드를 이미 쓰는 환경: YOLO 모드에서는 Plan 모드 자체로 진입이 불가합니다. (enter_plan_mode 도구 비활성화)

솔직히 말하면, Plan 모드는 아직 “완벽히 안전한 검토 환경”이라기보다 “기본 동작은 막아뒀지만, 설정에 따라 언제든 열릴 수 있는” 구조입니다. 기본 정책 파일(plan.toml)을 이해하고 직접 커스터마이즈할 준비가 된 팀에게 훨씬 효과적입니다.

Q&A

마치며

Gemini CLI Plan 모드는 분명히 유용한 기능입니다. “코드를 건드리기 전에 생각부터 하자”는 방향 자체는 맞습니다. 특히 대형 마이그레이션이나 복잡한 리팩터링 전에 쓰면 실수를 줄이는 데 도움이 됩니다.

다만 “Plan 모드 쓰면 안전하다”는 말을 그대로 믿으면 세 군데에서 막힙니다. 무료 API 키 환경에서는 Pro 라우팅이 제한되고, CI/CD에서는 Plan 종료 후 YOLO 전환이 자동으로 일어나며, 플랜 파일은 30일이면 기본 경로에서 사라집니다. 이 세 가지를 알고 설정에 반영하는 것과 모른 채 쓰는 것은 결과가 다릅니다.

기능을 쓸 준비가 됐다면, 공식 문서의 plan.toml 예시와 settings.json 설정부터 살펴보는 걸 권합니다. 공식 문서에 예시 코드가 그대로 나와 있습니다.

본 포스팅 참고 자료

1. Gemini CLI 공식 문서 — Plan Mode: https://geminicli.com/docs/cli/plan-mode/
2. Gemini CLI 공식 문서 — Quota and Pricing: https://geminicli.com/docs/resources/quota-and-pricing/
3. Google Gemini CLI GitHub 릴리스 노트 v0.33.0: https://github.com/google-gemini/gemini-cli/discussions/22078
4. ADTmag — “Google Adds Plan Mode to Gemini CLI” (2026.03.12): https://adtmag.com/articles/2026/03/12/google-adds-plan-mode-to-gemini-cli-to-support-safer-code-planning.aspx
5. Google for Developers Korea Blog — 3월 둘째 주 업데이트: https://developers-kr.googleblog.com/2026/03/weeklyupdate-week2.html