Gemini CLI Plan 모드, 안전하다는 말이 맞는 조건이 있습니다

2026년 3월 11일, Google이 Gemini CLI에 Plan 모드를 추가했습니다. 코드베이스를 건드리지 않고 먼저 분석·계획한 뒤 실행하는 구조라 “사고를 막아준다”는 평가가 많습니다. 맞는 말이긴 한데, 직접 뜯어보면 그 안전함이 생각보다 조건부입니다.

Plan 모드가 뭔지, 왜 나왔는지

기존 Gemini CLI는 요청을 받으면 곧바로 파일을 수정하거나 코드를 실행하는 방식으로 동작했습니다. 빠르다는 장점이 있었지만, AI가 의도를 잘못 파악했을 때 돌이키기 어려운 변경이 생기는 문제가 반복됐습니다. Google이 공식 블로그(2026.03.11)에서 밝힌 것도 이 맥락입니다 — “에이전트들이 너무 빨리 움직이다가 실제 저장소에서 문제를 만들었다(agents often started editing before fully understanding the problem)”고 적었습니다.

Plan 모드는 이 문제를 구조적으로 막는 방식입니다. 모드가 활성화되면 Gemini CLI는 파일 읽기·검색·문서 조회만 할 수 있고, 파일 수정은 자체 계획 파일(~/.gemini/tmp/<project>/plans/ 아래 .md 파일)을 작성하는 것만 허용됩니다. (출처: Gemini CLI 공식 문서, geminicli.com/docs/cli/plan-mode/)

Plan 모드가 기본값으로 켜진다는 점도 눈에 띕니다. 별도 설정 없이 Gemini CLI를 실행하면 Plan 모드가 회전 목록에 포함돼 있어서, Shift+Tab으로 모드를 바꾸다 보면 Plan 모드로 진입하게 됩니다. 켜져 있는지 모르고 쓰는 사람도 생길 수 있습니다.

실제로 어떻게 켜고 끄는지

Plan 모드에 진입하는 방법은 세 가지입니다. 첫 번째는 터미널에서 /plan을 입력하는 것, 두 번째는 Shift+Tab으로 모드를 순환하는 것, 세 번째는 자연어로 “이 기능 구현 계획부터 짜줘”라고 말하면 CLI가 자동으로 enter_plan_mode 도구를 호출합니다. 세션 시작부터 Plan 모드로 열고 싶다면 gemini --approval-mode=plan 플래그를 쓰면 됩니다.

반대로 Plan 모드를 회전 목록에서 아예 빼고 싶다면 /settings에서 “Plan”을 검색해 토글을 끄면 됩니다. 이렇게 하면 enter_plan_mode·exit_plan_mode 도구가 아예 등록 해제됩니다. (출처: Gemini CLI 공식 문서, geminicli.com/docs/cli/plan-mode/)

계획이 완성되면 CLI가 Markdown 파일로 저장하고 승인을 요청합니다. 이때 Ctrl+X를 누르면 외부 편집기(VS Code, Vim 등)에서 계획 파일을 직접 수정할 수 있습니다. 수정 후 저장하면 CLI가 변경 사항을 읽어들여 계획을 다시 다듬습니다.

계획 승인 후 벌어지는 일 — 안전의 경계

공식 문서에는 이렇게 나와 있습니다 — 계획을 “Yes, automatically accept edits”로 승인하면 구현이 즉시 시작되고, 이때 CLI는 Auto-Edit 모드로 동작합니다. (출처: geminicli.com/docs/cli/plan-mode/) 비대화형 환경(CI/CD 파이프라인 등)에서는 더 극단적입니다. Plan 모드 실행 후 승인이 이뤄지면 자동으로 YOLO 모드로 전환돼 이후 모든 도구 실행이 사람 확인 없이 진행됩니다.

즉, Plan 모드가 보장하는 안전함은 계획을 세우는 단계에 한정됩니다. 계획 내용이 잘못 짜여 있어도 승인 버튼 하나로 전부 실행됩니다. 계획서를 꼼꼼히 읽지 않고 “일단 승인” 하는 습관이 있다면 Plan 모드의 안전 장치가 거의 작동하지 않는 것과 같습니다.

Pro 모델 자동 라우팅, 무료 티어엔 내일부터 안 됩니다

Plan 모드의 핵심 기능 중 하나는 자동 모델 라우팅입니다. 공식 문서에 직접 나와 있습니다 — “계획 단계에서는 CLI가 Gemini 3.1 Pro처럼 고추론 Pro 모델로 라우팅하고, 계획 승인 후 구현 단계에서는 속도가 빠른 Flash 모델로 자동 전환된다.” (출처: geminicli.com/docs/cli/plan-mode/ — Automatic Model Routing 항목) 계획의 품질을 높이기 위해 의도적으로 Pro 모델을 쓰는 구조입니다.

Plan 모드의 강점 자체가 “복잡한 아키텍처 결정을 Pro 모델이 처리”하는 것이었는데, 무료 티어에서는 이 전제가 빠지는 셈입니다. Flash 모델로도 계획을 짤 수 있지만, 복잡한 의존성 분석이나 아키텍처 제안의 깊이가 달라질 수 있습니다.

유료 플랜 옵션은 Google AI Pro(약 월 19.99달러)와 Ultra 플랜이 있으며, AI Studio API 키를 직접 발급해 사용하는 방법도 있습니다. API 키 방식은 사용량 기반 과금이 적용됩니다. (출처: Gemini CLI GitHub Discussion #22970)

파일 덮어쓰기 함정 — write_file의 미공개 한계

Plan 모드를 벗어나 실행 단계로 넘어간 뒤 발생하는 문제인데, Plan 모드를 쓴다고 피해갈 수 있는 건 아닙니다. Gemini CLI의 write_file 도구는 파일 추가(append)를 지원하지 않고 전체 덮어쓰기만 가능합니다. GitHub 공식 토론(#7432)에 실제 사례가 기록돼 있습니다 — AI 에이전트가 “파일에 추가하겠다”고 말한 뒤 write_file을 호출해 기존 내용 전체가 삭제된 케이스입니다. 모델이 “Phase 23을 추가하겠다”고 선언했지만 실제로는 Phase 1~22가 전부 사라졌습니다.

이 문제는 Plan 모드 자체의 결함이 아니라 Gemini CLI 전반의 설계 방식에서 비롯됩니다. 하지만 Plan 모드를 쓰면 AI가 더 신중하게 동작할 거라는 기대를 갖고 중요한 파일을 다루다가 같은 문제를 만날 수 있습니다. 중요한 파일에 무언가를 “추가”하는 작업을 시킬 때는, 계획서에 정확히 어떤 방식으로 파일을 수정하는지 확인하고 승인하는 것이 필요합니다.

실 사용자들의 GitHub 피드백에는 이 외에도 대형 파일 편집 시 regex 스택 오버플로 문제, shell 명령 파싱 실패 등이 언급돼 있습니다. Google 팀은 이 이슈들이 공개된 상황입니다.

ask_user 도구와 Conductor 확장의 실제 가치

Plan 모드에서 새로 도입된 ask_user 도구는 단순히 “질문하는 기능”이 아닙니다. AI가 가정하는 대신 실제 목표를 명확히 하기 위해 계획 진행을 멈추고 선택지를 제시하는 구조입니다. 예를 들어 DB 마이그레이션을 계획할 때 어떤 ORM을 쓸지, 롤백 전략이 필요한지 등을 물어볼 수 있습니다. 이 양방향 소통이 계획의 품질을 실질적으로 높이는 부분입니다.

Conductor 확장은 Plan 모드와 ask_user를 기반으로 만들어진 외부 확장입니다. 복잡한 마이그레이션이나 다단계 구현 작업을 트랙으로 나눠 관리하고, 각 마일스톤마다 결정 사항을 확인하는 방식으로 동작합니다. GitHub 저장소(gemini-cli-extensions/conductor)에서 설치할 수 있으며, Google이 Conductor를 향후 Gemini CLI 내장 모드로 통합할 계획이라고 밝혔습니다. (출처: Google Developers Blog, 2026.03.11)

Plan 모드 쓸 때 알아두면 좋은 것들

실사용에서 놓치기 쉬운 포인트를 정리했습니다.

자주 묻는 질문 (Q&A)

마치며

Gemini CLI Plan 모드는 분명히 좋은 방향의 업데이트입니다. 코드베이스를 먼저 파악하고 계획을 세운 뒤 구현으로 넘어가는 흐름은 AI 코딩 도구의 고질적인 “빠른 실수” 문제를 줄이는 데 실질적으로 기여합니다.

다만 “읽기 전용이라 안전하다”는 말이 그대로 믿어지는 수준은 아닙니다. 계획 승인 즉시 Auto-Edit 모드로 전환되는 구조, 무료 티어에서의 Pro 모델 제한(내일부터 적용), 실행 단계의 파일 덮어쓰기 위험 — 이 세 가지를 알고 쓰는 것과 모르고 쓰는 것은 체감 경험이 꽤 다릅니다.

솔직히 말하면, 지금 Gemini CLI는 아직 안정성 측면에서 Claude Code나 다른 CLI 도구와 비교해 부족한 부분이 있습니다. Plan 모드 자체는 괜찮은 기능이지만, 도구 전반의 신뢰성이 올라와야 이 기능의 가치가 온전히 느껴질 것 같습니다. 지금은 가볍게 시도해 보되, 중요한 작업엔 수동 확인을 유지하는 게 현실적입니다.

1. Google Developers Blog — Plan mode is now available in Gemini CLI (2026.03.11) · developers.googleblog.com
2. Gemini CLI 공식 문서 — Plan Mode · geminicli.com/docs/cli/plan-mode/
3. Google Gemini CLI GitHub Discussion #22970 — Service update: mitigating abuse and prioritizing traffic (2026.03.22) · github.com/google-gemini/gemini-cli
4. Google for Developers Korea Blog — 3월 둘째 주 위클리 업데이트 (2026.03.13) · developers-kr.googleblog.com