IT/AI
Gemini CLI Plan 모드, 코딩 전에 읽는 게 맞습니다
2026년 3월 17일, v0.34.0 업데이트로 Plan 모드가 Gemini CLI의 기본값이 됐습니다. 이제 처음 터미널을 열면 자동으로 읽기 전용 계획 모드로 진입합니다. 그냥 쓰던 것과 뭐가 달라졌는지 — 공식 발표문과 실제 사용 흐름을 같이 놓고 보니 이런 차이가 보였습니다.
Plan 모드가 생긴 이유 — 누가 불편했나
Gemini CLI Plan 모드는 2026년 3월 11일 공식 발표됐고, 6일 후인 3월 17일 v0.34.0에서 모든 사용자의 기본값으로 전환됐습니다. (출처: Gemini CLI 공식 changelog, 2026.03.17)
AI 코딩 에이전트를 쓰다 보면 한 번쯤 겪는 상황이 있습니다. 무언가를 물어봤는데 AI가 질문에 답하는 대신 바로 파일을 수정하기 시작하는 것입니다. 이게 맞는 방향인지 확인도 안 됐는데 코드가 바뀌어 있습니다. 취소하려면 git restore를 써야 하고, 되돌아가는 것도 시간 낭비입니다.
이 문제가 쌓이다 보니 업계 전반에서 “먼저 계획하고, 승인 후 실행”하는 방향으로 흐름이 바뀌고 있습니다. Google이 Plan 모드를 기본값으로 밀어넣은 것도 같은 맥락입니다. DevOps.com의 분석에 따르면 “에이전트 도입에서 전사 구매 마찰을 일으키는 가장 큰 요인 중 하나가 자율 실행 기본값”이라고 짚고 있습니다. (출처: DevOps.com, 2026.03.16)
실제로 어떻게 작동하는가 — 4단계 흐름
v0.34.0 기준으로 Gemini CLI를 설치하면 첫 세션부터 Plan 모드가 켜진 상태로 시작됩니다. 진입 방법은 세 가지입니다.
| 진입 방법 | 명령어 또는 단축키 | 특이사항 |
|---|---|---|
| 키보드 단축키 | Shift + Tab | Default → Auto-Edit → Plan 순서로 순환 |
| 슬래시 명령어 | /plan | 입력창에 직접 타이핑 |
| CLI 실행 인자 | gemini –approval-mode=plan | 세션 단위로 Plan 모드 강제 진입 |
| 자연어 | “start a plan for …” | enter_plan_mode 툴 자동 호출 |
진입 후 작동 흐름은 다음과 같습니다.
목표 입력 — 하고 싶은 작업을 자연어로 설명합니다. 이 단계에서 AI는 파일을 건드리지 않습니다.
읽기 전용 탐색 — read_file, grep_search, glob 등 읽기 전용 툴만 사용해 코드베이스를 분석합니다. 쓰기 툴은 비활성화됩니다.
계획 초안 생성 — ~/.gemini/tmp/<project>/<session-id>/plans/ 경로에 Markdown 파일로 저장됩니다. 직접 편집하거나 Ctrl+X로 외부 에디터에서 수정할 수 있습니다.
승인 후 실행 — 계획을 승인하면 자동으로 편집 모드로 전환되어 실행이 시작됩니다. 취소하려면 Esc를 누르면 됩니다.
계획 파일은 기본적으로 30일 보존됩니다. 커스텀 경로를 설정하면 자동 삭제 대상에서 제외되므로 직접 관리해야 합니다. (출처: geminicli.com/docs/cli/plan-mode, 2026.03.17)
Pro 모델 자동 라우팅 — 생각보다 중요한 부분
Plan 모드에서 가장 눈에 띄지 않지만 실제로 꽤 중요한 기능이 모델 자동 라우팅입니다. 공식 문서에는 이렇게 나옵니다.
(출처: geminicli.com/docs/cli/plan-mode#automatic-model-routing, 2026.03.17)
계획 단계에는 Gemini 3.1 Pro가, 실행 단계에는 Flash 모델이 자동으로 쓰입니다. 바꿔 말하면 사용자가 모델을 따로 선택하지 않아도 됩니다.
이 라우팅을 끄고 싶다면 settings.json에서 "modelRouting": false를 설정하면 됩니다. 하지만 특별한 이유가 없는 한 기본값을 유지하는 편이 낫습니다. 직접 모델을 고를 때는 실수로 모든 작업에 Pro를 붙이게 되어 쿼터를 더 빨리 소모할 수 있습니다.
ask_user 툴 — 기존 AI 에이전트와 다른 점
Plan 모드와 함께 도입된 ask_user 툴은 말 그대로 AI가 먼저 물어보는 기능입니다. 기존에는 AI가 의도를 추측해서 작업을 진행했습니다. 틀린 방향으로 30분을 쓰고 나서 “이게 아니었나요?”를 들으면 허탈합니다.
ask_user 툴은 탐색 중간에 AI가 스스로 멈추고 선택지를 제시하거나 구체적인 정보를 요청합니다. 예를 들어 “DB 마이그레이션 계획을 짜달라”고 했을 때, 기존 스키마 파일 경로를 물어보거나 롤백 전략을 어떻게 처리할지 확인하는 식입니다.
단, YOLO 모드에서는 ask_user 툴이 비활성화됩니다. 자동화 스크립트나 CI/CD 파이프라인처럼 사람의 응답이 없는 환경에서는 이 툴이 작동하지 않는다는 점을 미리 알아야 합니다. (출처: geminicli.com/docs/cli/plan-mode, 2026.03.17)
MCP 읽기 연동 — 로컬 파일 너머의 계획
Plan 모드에서 쓸 수 있는 툴 목록 중에 MCP 읽기 툴이 포함돼 있습니다. 공식 문서에 나온 허용 툴 목록을 보면 다음과 같습니다.
| 툴 카테고리 | 허용 여부 | 예시 |
|---|---|---|
| 파일시스템 (읽기) | ✅ 허용 | read_file, glob, list_directory |
| 검색 | ✅ 허용 | grep_search, google_web_search |
| MCP 툴 (읽기 전용) | ✅ 허용 | github_read_issue, postgres_read_schema |
| 계획 파일 쓰기 | ⚠️ 제한적 허용 | plans/ 경로 내 .md 파일만 가능 |
| 파일 수정 / 셸 실행 | ❌ 차단 | write_file (비계획 경로), run_shell_command |
실용적으로 활용하면 이렇습니다. DB 마이그레이션을 계획할 때 postgres_read_schema로 현재 스키마를 읽어오고, github_read_issue로 관련 티켓을 확인한 다음 계획서를 작성합니다. 코드베이스와 외부 컨텍스트를 동시에 보는 계획이 가능해집니다.
다만 주의할 부분이 있습니다. 기본적으로 읽기 전용 MCP 툴도 Plan 모드에서 사용자 확인을 요청합니다. 자동 승인을 원한다면 ~/.gemini/policies/에 정책 파일을 직접 만들어야 합니다. 자동으로 되는 게 아닙니다. (출처: geminicli.com/docs/cli/plan-mode#custom-policies, 2026.03.17)
실제 사용자들이 말하는 한계 — 솔직하게
Plan 모드 자체는 잘 만들어진 기능이지만, Gemini CLI 전반에 대한 커뮤니티 평가는 냉정합니다. Reddit r/GeminiCLI 에서 2026년 3월 초에 올라온 글들을 보면 한계가 꽤 구체적으로 언급됩니다.
① 들여쓰기·기본 편집 오류: “Codex나 Claude는 이런 문제가 없는데 Gemini CLI는 기본적인 들여쓰기도 틀린다”는 지적이 반복됩니다. 복잡한 코딩 작업에서 루프에 빠지는 사례도 있었습니다.
② 세션 메모리 부재: “4~5개 메시지를 주고받으면 이전 맥락을 잊는다”는 불만이 있습니다. 긴 대화가 필요한 작업에서 맥락 끊김이 발생합니다.
③ 과부하 상황: 무료 티어 사용자 폭증의 부작용으로, 유료 사용자도 간헐적으로 429 에러(Too Many Requests)를 경험한다는 사례가 보고됩니다.
④ Plan 모드만으론 부족: 복잡한 프로젝트에서는 Conductor 익스텐션을 함께 써야 성과가 나온다는 의견이 많습니다. Plan 모드 단독으로는 긴 작업에서 중간에 방향이 흐려지는 경우가 있습니다.
개인적으로 이 부분이 좀 아쉬웠습니다. Plan 모드 자체는 구조가 탄탄한데, 그 아래에 있는 실행 엔진이 Claude Code나 Codex 대비 아직 격차가 있습니다. 대규모 코드 생성 작업보다는 DB 마이그레이션 사전 분석, 아키텍처 탐색, 레거시 코드 파악 같은 조사·설계 작업에서 Plan 모드의 가치가 더 크다고 느꼈습니다.
Plan 모드 끄는 법 + 커스텀 설정
Plan 모드가 기본값이라서 끄려면 명시적으로 설정해야 합니다. 공식 문서의 설정 방법은 간단합니다.
2. “Plan” 검색
3. 토글 OFF
→ Shift+Tab 순환에서 Plan 제거
→ enter_plan_mode / exit_plan_mode 툴 등록 해제
자주 Plan 모드로 시작하고 싶다면 settings.json에서 "defaultApprovalMode": "plan"으로 고정할 수 있습니다. 팀 단위 사용에서는 ~/.gemini/policies/ 폴더에 TOML 형식의 정책 파일을 두면 git 허용 명령어, MCP 자동 승인 등을 세밀하게 제어할 수 있습니다.
.gemini/plans로 지정하고 .gitignore에서 제외하면 됩니다. 단, 이 경로는 자동 삭제 대상에서 벗어나므로 수동으로 정리해야 합니다. (출처: geminicli.com/docs/cli/plan-mode#custom-plan-directory-and-policies, 2026.03.17)
자주 묻는 질문
마치며
Gemini CLI Plan 모드는 “AI가 먼저 생각하게 하는 구조”를 터미널 수준에서 강제한 실험입니다. 발표 6일 만에 기본값으로 올라간 것만 봐도 Google 내부에서 이 방향성에 꽤 확신이 있다는 걸 느낄 수 있습니다.
솔직히 말하면, 지금 단계에서 순수 코드 생성 능력은 Claude Code나 Codex에 비해 아직 격차가 있습니다. 루프, 들여쓰기 오류, 세션 메모리 문제 같은 것들이 실제 커뮤니티에서 계속 언급됩니다. Plan 모드가 아무리 잘 설계돼 있어도 실행 엔진이 그 계획을 따라가지 못하면 반쪽짜리입니다.
그럼에도 눈에 들어오는 부분은 세 가지입니다. 첫째, 무료 계정으로 Gemini 3.1 Pro 추론 능력을 계획 단계에서 쓸 수 있다는 점. 둘째, 외부 MCP 연동을 포함한 읽기 전용 탐색이 생각보다 강력하다는 점. 셋째, 정책 엔진 기반 커스터마이징이 팀 거버넌스에 실용적이라는 점입니다.
대규모 코딩 작업보다 아키텍처 탐색, 코드베이스 파악, DB 마이그레이션 사전 분석처럼 “먼저 읽고 이해해야 하는 작업”에 지금 당장 써볼 만한 도구입니다. 한 번 /plan 을 입력해 보면 그 감이 옵니다.
본 포스팅 참고 자료
- 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 (v0.34.0 기준)
https://geminicli.com/docs/cli/plan-mode/ - Gemini CLI Changelog — v0.34.0 (2026.03.17)
https://geminicli.com/docs/changelogs/latest/ - DevOps.com — Gemini CLI Plan Mode Separates Thinking From Doing (2026.03.16)
https://devops.com/gemini-cli-plan-mode-separates-thinking-from-doing-and-makes-read-only-the-default/ - Reddit r/GeminiCLI — Plan mode is now available in Gemini CLI (2026.03.11)
https://www.reddit.com/r/GeminiCLI/comments/1rr9f3i/
⚠️ 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. Gemini CLI는 활발히 개발 중인 오픈소스 프로젝트이며, 버전 업데이트에 따라 Plan 모드 동작 방식이나 툴 제한 사항이 달라질 수 있습니다. 최신 정보는 공식 문서(geminicli.com)에서 확인하세요.
댓글 남기기