Plan 모드가 뭔지, 결론부터 말씀드리면

Gemini CLI Plan 모드는 코드베이스를 읽고, 탐색하고, 설계안을 잡는 단계까지만 담당하는 읽기 전용 환경입니다. 파일을 수정하거나 명령을 실행하는 건 이 모드에서 아예 불가능합니다. 2026년 3월 11일, Gemini CLI v0.33.0 릴리스와 함께 공식 출시됐습니다. (출처: Google Developers Blog, 2026.03.11)

기존 AI 코딩 에이전트의 가장 흔한 실수는 “먼저 작성하고, 나중에 확인”하는 방식이었습니다. 에이전트가 맥락을 충분히 파악하기 전에 파일을 수정해버리는 상황이 실제 프로젝트에서 반복됐습니다. Plan 모드는 이 흐름을 정면으로 뒤집어, “먼저 파악하고, 나중에 실행”하는 구조로 바꿉니다.

진입 방법은 세 가지입니다. 입력창에 /plan을 입력하거나, Shift+Tab으로 모드를 순환하거나, 자연어로 “이 기능 구현 계획 잡아줘”라고 말하면 됩니다. 에이전트가 스스로 enter_plan_mode 도구를 호출합니다.

▲ 목차로 돌아가기

이미 켜져 있다는 사실, 대부분 모릅니다

솔직히 말하면, 처음에 “이게 벌써 기본값이라고?”라는 반응이 나왔습니다. Google Developers Blog의 공식 발표문에는 이렇게 명시돼 있습니다. “Plan mode is now enabled by default for all users!” — v0.33.0 출시와 동시에 모든 사용자에게 기본 활성화된 상태로 배포됐습니다. (출처: Google Developers Blog, 2026.03.11)

이게 왜 중요하냐면, 업데이트 직후 Gemini CLI를 켰을 때 이미 Shift+Tab 순환 목록에 Plan 모드가 포함돼 있습니다. 기존에 쓰던 워크플로가 있다면 모드 순환 순서가 바뀐 것을 체감할 수 있습니다. 끄고 싶으면 /settings에서 “Plan”을 검색해 토글을 끄면 됩니다. 그러면 Shift+Tab 순환에서 제거되고 관련 도구 등록도 해제됩니다.

특히 CI/CD 파이프라인처럼 비대화형 환경에서 --approval-mode=plan 플래그로 실행하면, Plan 모드 종료 후 자동으로 YOLO 모드(무중단 실행)로 전환되는 점도 눈여겨볼 만합니다. 헤드리스 환경에서 에이전트가 계획을 세운 뒤 바로 실행까지 이어지는 구조입니다.

▲ 목차로 돌아가기

Plan 모드에서 쓸 수 있는 도구와 쓸 수 없는 도구

Plan 모드는 정책 엔진(plan.toml)으로 허용 도구를 명시적으로 제한합니다. (출처: geminicli.com/docs/cli/plan-mode, 2026.03.11 기준) 공식 문서에 딱 이렇게 나와 있습니다.

MCP 도구 중 읽기 전용으로 표시된(readOnlyHint: true) 것들은 허용됩니다. 예를 들어 GitHub 이슈를 읽거나 Postgres 스키마를 조회하는 것은 Plan 모드 안에서 가능합니다. 데이터베이스 마이그레이션 계획을 세울 때 현재 스키마를 바로 조회하면서 설계안을 작성할 수 있습니다.

정책은 TOML 파일로 커스터마이징할 수 있습니다. ~/.gemini/policies/에 직접 규칙을 추가하면, 특정 모드에서만 git status나 git diff를 허용하는 식으로 fine-tuning이 가능합니다.

▲ 목차로 돌아가기

계획 단계와 실행 단계에서 모델이 달라집니다

Plan 모드의 핵심은 단순히 “파일을 못 건드리는 모드”가 아닙니다. 자동 모델 라우팅이 함께 작동합니다. 공식 문서에 정확히 이렇게 나와 있습니다: Plan 모드(계획 단계)에서는 Gemini 3.1 Pro(고추론 모델)로 자동 라우팅되고, 계획 승인 후 실행 단계로 전환되면 Gemini Flash(고속 모델)로 자동 전환됩니다. (출처: geminicli.com/docs/cli/plan-mode, Automatic Model Routing 섹션)

전략 수립에는 추론 능력이 높은 모델, 실제 코드 작성에는 속도가 빠른 모델. 이 조합은 비용과 품질을 동시에 최적화합니다. 같은 세션에서 두 개의 모델을 단계별로 쓰는 것이므로, 단일 모델로만 작동하는 다른 CLI 도구들과는 구조가 다릅니다.

기본값은 자동 라우팅이지만, settings.json에서 "modelRouting": false로 설정하면 수동 모드로 고정할 수도 있습니다. 특정 모델에 고정해야 하는 팀 환경에서 유용한 옵션입니다.

계획 파일은 ~/.gemini/tmp/<project>/<session-id>/plans/에 Markdown 파일로 저장됩니다. Ctrl+X를 누르면 외부 에디터(VS Code, Vim 등)에서 직접 편집 가능하며, 저장하면 Gemini CLI가 변경사항을 자동 감지해 계획을 수정합니다. 세션 데이터 기본 보존 기간은 30일입니다. (출처: Gemini CLI GitHub Discussion v0.33.0, 2026.03.11)

▲ 목차로 돌아가기

보안 취약점, 패치 전 상황 정리

Gemini CLI가 “안전한” read-only 모드를 내세우고 있지만, 보안 연구 기관 Cyera Research Labs가 기존 Gemini CLI에서 두 가지 취약점을 발견해 공개했습니다. Google의 취약점 보상 프로그램(VRP)을 통해 패치가 완료됐습니다. (출처: Cyera Research Labs, cyera.com/research)

이 두 취약점은 Plan 모드가 read-only를 표방하더라도, CLI 도구 자체의 구현 계층에서 보안 허점이 있으면 그 안전망이 의미 없어질 수 있다는 점을 보여줍니다. Cyera의 연구팀이 발견한 것도, 정작 분석하는 파일 안에 프롬프트가 숨어 있으면 read-only 모드 안에서도 에이전트가 그 프롬프트를 처리하면서 악성 명령이 실행될 수 있다는 시나리오였습니다. Google이 패치한 이후의 최신 버전에서는 해당 취약점이 닫혀 있습니다.

▲ 목차로 돌아가기

Conductor 확장과 조합하면 달라지는 것들

Conductor는 Gemini CLI의 공식 확장 프로그램으로, Plan 모드를 적극 활용하도록 설계됐습니다. Google이 향후 Gemini CLI에 내장 모드로 통합할 예정이라고 공식 블로그에서 밝혔습니다. (출처: Google Developers Blog, 2026.03.11)

Conductor는 작업을 “트랙” 단위로 관리하고, 진행 상황을 Markdown 파일로 프로젝트 내 conductor/ 디렉토리에 저장합니다. 대화 기록이 아니라 파일로 남기 때문에 세션이 끊겨도 이어서 작업할 수 있고, git으로 버전 관리도 됩니다. 복잡한 마이그레이션이나 멀티 서비스 기능 구현에서 유용한 구조입니다.

한 가지 더 눈여겨볼 것은 AfterTool 훅입니다. Plan 모드 종료 시점에 훅을 연결하면, 승인된 계획 파일을 Google Cloud Storage에 자동으로 아카이브할 수 있습니다. 공식 문서에 예시 셸 스크립트가 그대로 나와 있습니다. 조직 감사 정책상 모든 실행 계획을 보존해야 하는 팀이라면, 이 훅 하나로 에이전트의 행동 이력 전부를 GCS에 남길 수 있습니다. 별도 로깅 시스템 없이 터미널 워크플로에 그대로 얹히는 구조입니다.

DevOps.com의 분석에 따르면 Futurum Group의 VP가 이 구조를 “에이전트 거버넌스의 전환점”으로 평가했습니다. Plan-first 실행을 엔터프라이즈 채택의 기본 조건으로 삼는 구매자들에게 직접 대응하는 구조라는 해석입니다. (출처: DevOps.com, 2026.03.12)

▲ 목차로 돌아가기

불편한 점, 솔직히 말하면

기대했던 것과 달랐던 부분이 있습니다. Plan 모드에서 MCP 도구의 읽기 전용 여부를 수동으로 정책에 등록해야 하는 경우가 있습니다. 기본적으로 읽기 전용 MCP 도구도 Plan 모드에서 사용자 확인을 요구하도록 설정돼 있습니다. 이걸 자동 승인으로 바꾸려면 ~/.gemini/policies/에 직접 TOML 규칙을 작성해야 합니다. 비개발자에게는 진입장벽이 있는 부분입니다.

커스텀 Plans 디렉토리를 쓰는 경우엔 30일 자동 정리 대상에서 제외됩니다. 계획 파일이 쌓여도 수동으로 관리해야 하므로, 프로젝트 단위로 계획을 보존하고 싶을 때는 주기적 정리 루틴이 필요합니다.

또 Plan 모드 안에서 ask_user 도구가 질문을 던질 때, 복수의 옵션 중 선택을 요구하는 흐름이 꽤 길어질 수 있습니다. 빠르게 코드를 작성하고 싶은 상황에서는 계획 단계가 오히려 병목이 됩니다. Plan 모드가 “구조화된 안전함”을 원하는 사람에게 맞고, 빠른 반복 작업에는 기존 Default 모드나 Auto-Edit 모드가 여전히 더 적합합니다.

Reddit의 Gemini CLI 사용자 커뮤니티에서도 Pro 구독자 일부가 주간 한도 초과로 응답 지연을 경험했다는 보고가 있었습니다. Plan 모드가 Gemini 3.1 Pro를 기본으로 사용하기 때문에, 고추론 모델의 할당량 소모가 더 빠를 수 있습니다. 이 부분은 Google이 공식 답변을 내놓지 않은 상태입니다.

▲ 목차로 돌아가기

자주 묻는 질문 5가지

▲ 목차로 돌아가기

마치며

Plan 모드의 핵심은 “안전한 탐색”이 아니라 탐색 단계와 실행 단계를 물리적으로 분리한다는 데 있습니다. 어떤 도구를 쓸 수 있는지 정책으로 명시하고, 모델도 단계별로 자동 전환됩니다. 그 위에 훅과 Conductor 같은 확장을 얹으면 개인 개발 도구에서 팀 단위 거버넌스 도구로 성격이 달라집니다.

이게 부담스럽다면 /settings에서 토글 하나로 끄면 됩니다. 하지만 이미 기본값으로 켜져 있다는 사실을 모르고 쓰는 것과, 알고 쓰는 것은 결과가 달라집니다. 특히 규모 있는 코드베이스나 팀 환경이라면 Plan 모드가 어떻게 작동하는지 한 번은 직접 확인해볼 만합니다.

이 부분이 좀 아쉬웠습니다 — MCP 정책 커스터마이징은 TOML 문법을 직접 써야 해서 비개발자에게는 여전히 허들이 있습니다. 향후 UI에서 관리할 수 있도록 개선되면 더 많은 사람이 활용할 수 있을 것 같습니다.

▲ 목차로 돌아가기

본 포스팅 참고 자료

1. Google Developers Blog — Plan mode is now available in Gemini CLI (2026.03.11)
2. Gemini CLI 공식 문서 — Plan Mode Documentation (geminicli.com)
3. GitHub Gemini CLI — v0.33.0 Weekly Update Discussion (2026.03.11)
4. DevOps.com — Gemini CLI Plan Mode Separates Thinking From Doing (2026.03.12)
5. Cyera Research Labs — Command & Prompt Injection Vulnerabilities in Gemini CLI