v0.33.0 기준
IT/AI
Gemini CLI Plan 모드, 써보니 달랐습니다
AI 코딩 도구의 가장 큰 불만은 늘 같았습니다. 뭔가를 물어보려고 했더니 이미 파일이 바뀌어 있는 상황. Gemini CLI v0.33.0(2026년 3월 11일 출시)이 Plan 모드를 기본 탑재한 건 바로 그 문제를 겨냥한 겁니다. 그런데 직접 공식 문서와 실사용 데이터를 같이 놓고 보니, 생각했던 것과 다른 부분이 두 군데 보였습니다.
Plan 모드란 정확히 무엇인가요?
결론부터 말씀드리면, Plan 모드는 Gemini CLI가 파일을 전혀 건드리지 않는 읽기 전용 상태입니다. 터미널에서 /plan을 입력하거나 Shift+Tab을 눌러 진입하는 순간, AI는 코드를 읽고 분석하고 의존성을 파악하는 것만 할 수 있습니다. 쓰기 권한이 있는 곳은 딱 한 군데 — ~/.gemini/tmp/<project>/<session-id>/plans/ 안의 마크다운 파일뿐입니다. (출처: Gemini CLI 공식 문서, 2026.03.11)
사용 가능한 도구도 명확히 제한됩니다. read_file, grep_search, glob, google_web_search 같은 읽기 전용 도구와 ask_user 도구만 쓸 수 있습니다. 특히 MCP 도구도 읽기 전용(readOnlyHint: true)인 것만 허용됩니다. 이 규칙은 plan.toml 정책 파일로 관리되며, 사용자가 커스텀 정책을 추가하는 것도 가능합니다.
계획이 완성되면 Gemini CLI는 마크다운 파일로 구현 계획서를 만들어줍니다. 승인하면 Plan 모드가 종료되고 실행 단계로 넘어갑니다. Ctrl+X를 누르면 외부 에디터(VS Code, Vim 등)에서 계획서를 직접 수정할 수도 있습니다.
플래시만 무료라는 사실, 놓치기 쉽습니다
Gemini CLI는 하루 1,000회 무료라고 알려져 있습니다. 맞습니다. 그런데 그게 전부 Flash 모델 기준이라는 건 별도로 확인해야 합니다. 개발자 비교 분석(Eric Murphy, Medium, 2026.03.16)에 따르면 Pro 모델은 대용량 프롬프트 기준 4~15개 요청 후 속도 제한이 걸리는 사례가 있었습니다. 즉, 무료 계정으로 Plan 모드를 쓰더라도 Pro 모델 배정을 계속 보장받지는 못합니다.
💡 공식 문서와 실제 사용 흐름을 같이 놓고 보니 이런 차이가 보였습니다. Plan 모드 진입 시 Pro 모델로 자동 라우팅된다고 공식 문서에는 나와 있지만, 무료 계정에서 이 라우팅이 항상 Pro 모델을 의미하지는 않습니다. Pro 모델 접근을 보장하려면 개인 API 키를 직접 설정해야 합니다.
| 구분 | 무료 계정 | 자체 API 키 |
|---|---|---|
| 일일 요청 한도 | 약 1,000회 (Flash 기준) | API 요금제에 따름 |
| Plan 모드 모델 | Flash (Pro 제한 가능) | Gemini 3.1 Pro 보장 |
| 모델 자동 라우팅 | 활성화 (한도 내) | 활성화 |
| YOLO 모드 자동 전환 | 비대화형 환경만 | 비대화형 환경만 |
(출처: Gemini CLI 공식 문서, geminicli.com/docs; Eric Murphy, Medium, 2026.03.16)
계획 단계에서 Pro 모델이 자동으로 바뀌는 이유
AI 코딩 도구에서 Plan 모드라고 하면 보통 응답이 느려질 거라고 생각합니다. 그런데 Gemini CLI의 설계는 반대 방향입니다. 공식 문서에는 이렇게 나옵니다: 자동 모델(auto model) 설정 시, Plan 모드 진입 후 요청은 고추론 Pro 모델로 라우팅되고, Plan 승인 후 실행 단계에서는 고속 Flash 모델로 자동 전환됩니다. (출처: Gemini CLI 공식 문서 “Automatic Model Routing”, 2026.03.11) 계획을 짜는 데 더 비싼 모델을 쓰고, 실행은 빠른 모델에게 맡기는 구조입니다.
💡 Plan 모드를 쓸수록 오히려 실행 품질이 올라가는 구조입니다. 계획서가 있는 상태에서 Flash가 실행하기 때문에, 무계획 상태의 Pro 모델 단독 실행보다 오류율이 낮아질 수 있습니다.
이 자동 전환을 끄고 싶다면 settings.json에서 "modelRouting": false로 설정하면 됩니다. (출처: Gemini CLI 공식 문서, 2026.03.11)
참고로 Gemini CLI가 사용하는 고추론 모델은 현재 Gemini 3.1 Pro(2026년 2월 19일 출시)입니다. 이 모델은 구글 역사상 처음 적용된 .1 증분 업데이트 모델로, 전작 대비 추론 성능이 크게 향상됐습니다.
ask_user 도구가 실제로 다른 점
기존 AI 코딩 도구는 맥락이 불분명해도 알아서 추측하고 실행해버렸습니다. Plan 모드의 ask_user 도구는 이 흐름을 바꿉니다. AI가 연구 중에 결정을 내리기 애매한 시점에 멈추고, 개발자에게 직접 질문을 던집니다. “이 마이그레이션에서 롤백 전략은 어떻게 할까요?” 같은 방식입니다. (출처: Google Developers Blog, 2026.03.11)
Plan 모드가 진행 중인 상태에서 Shift+Tab을 눌러 다시 Default 모드로 돌아올 수 있고, 자연어로 “플랜 모드 종료해줘”라고 말해도 됩니다. 계획서가 완성된 뒤에는 Ctrl+X로 외부 에디터에서 직접 수정도 가능합니다. 계획서 안에 주석으로 “여기서 기존 Logger 클래스를 쓰면 어떨까요?”라고 메모를 남기면, Gemini CLI가 저장 후 재검토 시 그 주석을 반영해 계획을 수정합니다.
이 양방향 소통 구조 덕분에 계획이 실제 의도와 어긋나는 상황을 사전에 걸러낼 수 있습니다. 기존 도구들이 실행 후 롤백을 고민했다면, Plan 모드는 실행 전에 방향을 정리하는 단계를 명확히 제공합니다.
CI/CD 파이프라인에서 쓸 수 있는 이유
💡 Plan 모드가 단순한 “안전 모드”가 아니라 자동화 파이프라인용으로 설계된 흐름을 공식 문서에서 확인했습니다. 이 부분은 한국어로 다룬 자료가 거의 없습니다.
비대화형(non-interactive) 환경, 즉 헤드리스 스크립트나 CI/CD 파이프라인에서 Gemini CLI를 --approval-mode=plan 옵션으로 실행하면 흥미로운 일이 생깁니다. Plan 단계가 끝나고 구현 단계로 전환될 때, 사용자 승인 없이 YOLO 모드로 자동 전환됩니다. (출처: Gemini CLI 공식 문서 “Non-interactive execution”, 2026.03.11)
예를 들어 이런 방식으로 쓸 수 있습니다:
gemini --approval-mode plan -p "텔레메트리 분석 후 개선안 적용해줘"이 명령 한 줄로 Gemini CLI는 코드베이스를 읽고 계획을 세운 뒤, 계획서를 자동 승인하고 실행까지 이어갑니다. 사람이 개입하지 않아도 됩니다. 계획 완료 후 생성되는 마크다운 계획서는 AfterTool 훅을 사용해 자동으로 GCS(Google Cloud Storage) 같은 외부 저장소에 아카이빙할 수도 있습니다.
주의: YOLO 모드는 모든 파일 수정을 자동 승인하므로, 파이프라인 환경에서 사용 시 정책 파일로 허용 범위를 명확히 제한할 것을 권장합니다.
Claude Code·Cursor와 뭐가 다른가요?
AI 코딩 도구 비교 분석(Eric Murphy, Medium, 2026.03.16)에서 직접 나온 수치를 기준으로 정리했습니다. 1M 컨텍스트 윈도우는 Claude Code, Gemini CLI, Codex CLI 모두 지원합니다. 반면 Windsurf는 광고 수치와 달리 실효 컨텍스트가 50~70K 토큰 수준에 그친다고 나와 있습니다. 컨텍스트 창 크기 자체보다 어떻게 사용하는지가 더 중요하다는 뜻입니다.
요금 구조도 다릅니다. Claude Code Max 플랜은 월 $100 고정 요금제로, 한 개발자가 8개월간 100억 토큰을 사용한 기록이 있습니다. API 토큰 단가로 계산하면 약 $15,000에 해당하는 사용량입니다. (출처: Eric Murphy, Medium, 2026.03.16) 예측 가능한 비용이 필요한 팀이라면 Claude Code Max가 유리하고, 무료 한도 안에서 가볍게 시작하고 싶다면 Gemini CLI가 현실적인 선택입니다.
Gemini CLI Plan 모드의 가장 뚜렷한 차이는 아키텍처 결정 단계에서의 MCP 연동입니다. GitHub 이슈, Postgres 스키마, Google Docs 같은 외부 데이터 소스를 읽기 전용으로 끌어와서 계획에 반영할 수 있습니다. 계획서를 짜면서 현재 이슈 트래커와 DB 구조를 동시에 참조하는 흐름은 순수 CLI 도구 중에서는 지금 Gemini CLI가 유일합니다.
Q&A
마치며
Plan 모드 자체는 간단한 아이디어입니다. 코드를 건드리기 전에 먼저 읽고, 계획 짜고, 승인받고, 그 다음에 실행한다. 이 흐름을 Gemini CLI v0.33.0이 기본 탑재한 건 의미 있는 변화입니다.
두 가지는 기억해두면 좋습니다. 첫째, 무료 한도 1,000회는 Flash 기준이고 Plan 모드에서 Pro 모델을 안정적으로 쓰려면 API 키가 필요합니다. 둘째, CI/CD 파이프라인에서 --approval-mode=plan으로 실행하면 계획 → 실행이 자동으로 이어지는데, 이 자동화 흐름을 의도적으로 활용할 수 있는 개발팀이라면 꽤 유용한 옵션입니다. 현재 버전은 v0.35.2(2026.03.27 기준)이며, 기능은 계속 업데이트되고 있습니다.
📚 본 포스팅 참고 자료
본 포스팅은 2026년 3월 27일 기준으로 작성되었습니다. 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 최신 정보는 Gemini CLI 공식 문서를 참고하세요.
댓글 남기기