IT / AI
Gemini CLI Plan Mode 직접 써봤습니다 — 안 되는 게 있습니다
2026년 3월 11일, 구글이 Gemini CLI에 Plan Mode를 기본 활성화했습니다. 코드를 건드리기 전에 먼저 읽고 계획을 세우는 읽기 전용 안전망인데, 막상 써보면 “무조건 좋은 것”이라고 보기 어려운 지점이 꽤 있습니다.
Plan Mode가 뭔지부터 — 한 줄로 정리하면
Gemini CLI Plan Mode는 AI가 코드를 수정하기 전에 먼저 읽기만 하는 상태로 고정하는 기능입니다. 파일을 열어보고, 코드베이스 구조를 파악하고, 무엇을 어떻게 바꿀지 계획을 짠 다음에야 실행 단계로 넘어갑니다. 2026년 3월 11일 공식 블로그 발표 이후, 3월 17일 v0.34.0 업데이트에서 기본값이 켜진 상태로 바뀌었습니다. (출처: Google Developers Blog, 2026.03.11)
이 모드가 활성화된 동안은 read_file, grep_search, glob 같은 읽기 전용 도구만 쓸 수 있고, 파일 수정은 계획서(Markdown)를 저장하는 경우에만 예외적으로 허용됩니다. 쉽게 말해 AI가 먼저 손을 못 쓰게 묶어두고 설계도를 제출하게 만드는 방식입니다.
새로 추가된 ask_user 도구가 이 흐름의 핵심입니다. AI가 작업 중간에 멈추고 사용자에게 먼저 질문을 던지는 구조인데, 기존 CLI 툴에서 “사람이 명령하고 AI가 실행”하던 흐름과 반대로, AI가 먼저 확인을 요청합니다.
기본 활성화됐다는 게 실제로 어떤 의미인가
v0.34.0 이전까지는 Plan Mode가 실험적 기능이라 settings.json에서 직접 켜야 했습니다. 이제는 Gemini CLI를 그냥 실행하면 바로 Plan 모드가 기본값입니다. 프롬프트 입력창에서 /plan을 치거나, Shift+Tab으로 모드를 전환하거나, 그냥 “이 기능 계획 좀 짜줘”라고 자연어로 말해도 됩니다.
단 Windows 환경에서는 주의가 필요합니다. GitHub 이슈(#18730, 2026.02.10)에 따르면, 설정에서 Plan Mode를 꺼뒀어도 Shift+Tab이 제대로 작동하지 않아 강제로 Plan Mode에 갇히는 버그가 보고됐습니다. 공식 fix 여부는 별도 확인이 필요합니다.
Plan Mode를 쓰기 싫다면 /settings에서 “Plan”을 검색해 끄면 됩니다. 끄면 Shift+Tab 로테이션에서도 빠지고, enter_plan_mode / exit_plan_mode 도구도 등록 해제됩니다. 선택적으로 쓸 수 있다는 점은 명확합니다.
💡 공식 발표문과 실제 업데이트 흐름을 같이 놓고 보니 이런 차이가 보였습니다 — 3월 11일 공식 발표에서는 “이제 Plan Mode를 쓸 수 있다”고 했지만, 실제로 기본값이 켜진 건 6일 뒤인 3월 17일 v0.34.0입니다. 발표 날짜와 실제 적용 날짜가 다르다는 사실을 모르면 “왜 내 CLI는 아직 안 바뀌었지?”라는 혼란이 생길 수 있습니다.
Pro 모델이 Flash로 바뀌는 순간이 있습니다
이 부분을 대부분의 소개 글에서 빠트립니다. Gemini CLI의 공식 문서 “Automatic Model Routing” 항목에 이렇게 나와 있습니다. Plan Mode 진행 중에는 Gemini 3.1 Pro처럼 고추론 Pro 계열 모델이 라우팅되고, 계획을 승인하고 실행 단계로 넘어가는 순간 Gemini 2.5 Flash 같은 고속 경량 모델로 자동 교체됩니다. (출처: geminicli.com/docs/cli/plan-mode, 2026.03.11 기준)
계획은 Pro가 짜고, 실제 코드 수정은 Flash가 합니다. 계획의 품질이 아무리 좋아도 실행 모델이 달라지면 결과가 달라질 수 있습니다. 이 자동 교체를 막으려면 settings.json에서 "modelRouting": false로 직접 설정해야 합니다.
📊 모델 라우팅 흐름 (공식 문서 기준)
| 단계 | 사용 모델 | 역할 |
|---|---|---|
| Plan Mode (계획) | Gemini 3.1 Pro | 구조 분석, 계획 수립 |
| 실행 단계 (코드 수정) | Gemini 2.5 Flash (자동 전환) | 실제 파일 수정 |
계획 단계와 실행 단계에 다른 모델이 쓰입니다. 끄고 싶다면 modelRouting: false 설정이 필요합니다.
Pro와 Flash의 성능 차이는 작지 않습니다. 구글 공식 자료 기준으로 Gemini 3 Pro는 VS Code 환경에서 Gemini 2.5 Pro 대비 소프트웨어 엔지니어링 문제 해결 정확도가 35% 높습니다. (출처: Google Cloud Blog, 2025.11.19) 실행 단계에서 Flash가 쓰인다는 건, 그 35% 갭이 다시 좁혀질 수 있다는 뜻입니다.
무료라고 믿었다면 이 조건은 꼭 보세요
더 중요한 조건이 있습니다. 무료 티어에서 개인 구글 계정으로 로그인하면, 입출력 데이터가 구글의 수집 대상에 포함됩니다. 공식 비교 자료에 “유료 티어와 달리 무료 플랜은 opt-in data collection에 동의하게 된다”고 명시돼 있습니다. (출처: shipyard.build/blog/claude-code-vs-gemini-cli, 2026.01.15) 업무 코드베이스를 올릴 예정이라면 이 부분을 먼저 확인해야 합니다.
💡 “무료 = 조건 없음”이라고 생각하기 쉽지만, 실제로는 데이터 수집 동의가 묶여 있습니다. Gemini Ultra 유료 구독자도 Gemini CLI 고사용량에서는 제한을 받습니다 — Google 지원 포럼에 따르면 소비자 Ultra 구독은 Gemini CLI 개발자 툴의 고용량 사용량을 포함하지 않는다고 공식 답변이 올라와 있습니다. (출처: Google Gemini 지원 포럼, 2025.09.21)
Claude Code, Codex와 실제로 다른 부분
셋 다 터미널에서 자연어로 명령하는 AI 에이전트지만, 써보면 체감 차이가 납니다. Gemini CLI가 가장 두드러지는 부분은 컨텍스트 창입니다. 100만 토큰 창 덕분에 대형 코드베이스 전체를 한 번에 읽을 수 있습니다. Claude Code(Sonnet 4.5)도 100만 토큰을 지원하지만, 실제로 창 끝에 가까워질수록 모델이 좁게 생각하는 경향이 있다는 현장 피드백이 있습니다.
응답 형식도 다릅니다. Claude Code는 짧은 문장, 글머리표, 목록 위주로 출력하고, Gemini CLI는 긴 단락과 번호 목록을 씁니다. 좁은 터미널 창에서 작업할 때는 Claude의 포맷이 더 읽기 편하다는 평가가 많습니다. Gemini는 정밀한 지시를 줄수록 결과가 좋아지는 반면, 방향을 잃었을 때 스스로 경로를 바로잡는 능력은 Claude Code 쪽이 낫다는 게 실제 사용 비교에서 반복해서 나오는 결론입니다. (출처: shipyard.build/blog/claude-code-vs-gemini-cli, 2026.01.15)
| 항목 | Gemini CLI | Claude Code | Codex (GPT-5.3) |
|---|---|---|---|
| 기본 요금 | 무료 (조건 있음) | $20~100+/월 | API 종량제 |
| 컨텍스트 창 | 100만 토큰 | 100만 토큰 | 약 20만 토큰 |
| Plan Mode | 기본 ON (v0.34+) | opusplan 모드 | 별도 없음 |
| 오류 후 자가복구 | 상대적 약세 | 강세 | 강세 (디버깅) |
수치 출처: shipyard.build (2026.01.15), optijara.ai (2026.02.12), geminicli.com 공식 문서
Plan Mode가 막는 것과 못 막는 것
Plan Mode는 의도치 않은 코드 수정은 막습니다. 읽기 전용 모드라 실행 단계에서 발생하는 파일 변경이나 셸 명령 실행이 차단됩니다. gVisor(runsc) 기반 샌드박싱도 v0.34.0에서 추가됐기 때문에, 컨테이너 격리 레벨의 보안도 갖췄습니다.
그런데 GitHub Discussion(2025.11.14 기록)에 올라온 실사용 케이스를 보면, Plan Mode와 무관하게 일반 실행 단계에서 write_file이 append가 아닌 overwrite로 동작해 기존 파일 전체를 덮어쓴 사례가 기록돼 있습니다. Plan Mode는 계획 단계만 읽기 전용으로 보호할 뿐, 승인 후 실행 단계에서 발생하는 문제까지 막지는 못합니다. 그 사례에서는 22단계에 걸쳐 작성한 개발 로그 전체가 Phase 23 내용 하나로 덮여 삭제됐습니다.
⚠️ 공식 문서에서 별도 이유를 밝히지 않은 부분
write_file이 overwrite 전용으로만 작동하는 이유는 아직 공개되지 않았습니다. Plan Mode가 계획 단계를 보호해도, 실행 단계 승인 후에는 이 제약이 그대로 적용됩니다. 중요한 파일은 작업 전 백업을 따로 해두는 것이 안전합니다.
또 한 가지 — Windows 환경에서 셸 명령 파싱이 유독 까다롭습니다. 단순한 Python 한 줄 명령(python -c "...")이나 PowerShell 기본 명령도 “Command rejected because it could not be parsed safely” 오류로 튕기는 케이스가 있고, 이는 보안 파서가 지나치게 엄격하게 작동하기 때문으로 보입니다.
결국 어떤 상황에서 쓸 만한가
솔직히 말하면, Plan Mode가 가장 빛나는 건 대형 코드베이스 마이그레이션이나 처음 보는 프로젝트 구조 파악입니다. 100만 토큰 컨텍스트 창으로 프로젝트 전체를 읽고, codebase_investigator 서브에이전트가 의존성 구조를 짚은 뒤 계획서를 내놓는 흐름은 실제로 유용합니다. “데이터베이스 마이그레이션 방법 리서치해줘” 같은 요청에 파일을 건드리지 않고 안전하게 분석 결과만 받을 수 있습니다.
반면 소규모 버그 픽스나 짧은 파일 수정처럼 속도가 중요한 작업에서는 Plan Mode가 오히려 불필요한 대화를 추가합니다. ask_user 도구가 중간에 끼면 계획 하나 승인받는 데 왔다 갔다가 늘어납니다. 이런 상황에선 Plan Mode를 끄거나 Auto-Edit 모드를 쓰는 게 낫습니다.
한국어 기준으로 조심해야 할 부분도 있습니다. Gemini는 정밀한 지시에 잘 반응하지만, 방향이 어긋났을 때 스스로 복구하는 능력이 Claude Code보다 약하다는 현장 평가가 반복됩니다. 이미 잘 아는 코드베이스에서 명확한 작업을 줄 때는 좋고, 탐색적으로 “뭔가 문제 찾아줘” 식의 요청에는 클로드가 더 안정적입니다.
💡 CI/CD 파이프라인에서 Gemini CLI를 비대화형으로 실행할 때 Plan Mode는 자동으로 YOLO 모드로 전환됩니다 — 공식 문서에 “헤드리스 스크립트 환경에서 Plan Mode 종료 시 자동으로 사용자 확인 없이 실행”이라고 나와 있습니다. 자동화 파이프라인에서 쓸 때는 이 동작을 미리 이해하고 있어야 의도치 않은 실행을 막을 수 있습니다.
Q&A
마치며
그런데 “Plan Mode가 켜졌으니 안전하다”는 생각은 과합니다. 계획을 승인한 뒤 실행 단계에서 벌어지는 일은 Plan Mode가 막지 못합니다. 모델이 Pro에서 Flash로 자동 교체되는 것도 기본값이고, 무료 사용에는 데이터 수집 동의가 묶여 있습니다.
결론은 단순합니다. 대형 구조 변경, 마이그레이션, 의존성 분석처럼 시간이 걸려도 정확하게 가야 하는 작업에는 쓸 만합니다. 빠른 단순 수정은 꺼두는 게 낫고, 중요한 파일은 항상 백업 후에 시작하는 습관이 Plan Mode보다 더 확실한 안전장치입니다.
본 포스팅 참고 자료
본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 본문 내 정보는 Gemini CLI v0.34.0 / 2026.03.24 기준이며, Google의 공식 업데이트에 따라 내용이 달라질 수 있습니다. 정확한 최신 정보는 geminicli.com 공식 문서에서 확인하세요.
댓글 남기기