Gemini CLI v1.0 이상
TECH 테마
Gemini CLI Plan 모드, 기본 켜져 있다고요?
아무것도 설정 안 했는데 이미 Plan 모드입니다. 그리고 3월 25일 이후 무료 사용자는 이 모드의 핵심 모델을 못 씁니다.
Plan 모드가 이미 켜져 있다는 것을 모르는 이유
Gemini CLI를 설치하고 처음 실행했을 때, 별도 설정을 건드리지 않아도 이미 Plan 모드가 기본값입니다. 공식 문서에 딱 이렇게 나와 있습니다. “Plan Mode is enabled by default.” (출처: geminicli.com 공식 문서)
💡 공식 출시 발표문과 실제 CLI 동작을 같이 놓고 보니 이런 차이가 보였습니다. 많은 사용자가 Plan 모드를 “선택 기능”으로 인식하지만, 실제로는 아무것도 하지 않아야 Plan 모드입니다. 코드를 바꾸려면 오히려 Plan 모드에서 나가야 합니다.
이게 왜 중요하냐면, Plan 모드에서 AI는 파일을 읽기만 하고 절대 수정하지 않습니다. 실수로 중요한 파일을 덮어쓸 위험이 없습니다. 하지만 바로 코드 수정을 원한다면, 처음부터 gemini --approval-mode=autoEdit 옵션으로 실행해야 한다는 사실을 모르는 경우가 많습니다.
Plan 모드가 실제로 하는 일 — 공식 문서 기준
Plan 모드에서 Gemini CLI가 할 수 있는 작업과 절대 못 하는 작업이 명확하게 나뉩니다. 공식 문서에 허용 도구 목록이 그대로 정의돼 있습니다. (출처: geminicli.com/docs/cli/plan-mode)
| 구분 | 가능한 작업 | 불가능한 작업 |
|---|---|---|
| 파일 접근 | read_file, glob, list_directory | write_file (플랜 파일 제외), replace |
| 검색 | grep_search, google_web_search | 터미널 명령 실행 불가 |
| 외부 연동 | 읽기 전용 MCP 도구 (GitHub 이슈, DB 스키마 등) | 쓰기 MCP 도구 전면 차단 |
| 플랜 작성 | ~/.gemini/tmp/ 내 .md 파일 생성 | 프로젝트 파일 직접 수정 불가 |
실제 흐름을 따라가 보면, AI가 코드베이스를 읽고 의존성을 파악한 뒤 ask_user 도구로 질문을 던집니다. 그러면 사용자가 답변을 주고, AI는 그걸 반영해 마크다운 플랜 파일을 생성합니다. 플랜에 동의하면 그때서야 편집 모드로 전환됩니다. 한 줄 요약: AI가 먼저 물어보고 시작합니다. 일방적으로 코드를 건드리지 않습니다.
Plan 모드에서 생성된 플랜 파일은 기본적으로 ~/.gemini/tmp/<프로젝트>/<세션ID>/plans/ 경로에 저장됩니다. 30일 후 자동 삭제되고, 커스텀 경로로 변경하면 수동 관리해야 합니다. (출처: geminicli.com 공식 문서)
모델 자동 전환 — 계획엔 Pro, 실행엔 Flash
왜 이 구조가 실제 비용과 직결되는지
Plan 모드가 기본값인 이유 중 하나가 여기 있습니다. Auto 모델 설정을 사용하면 Gemini CLI가 현재 단계에 따라 모델을 자동으로 바꿉니다. 공식 문서에 이렇게 나옵니다. “Planning Phase: routes requests to a high-reasoning Pro model. Implementation Phase: automatically switches to a high-speed Flash model.” (출처: geminicli.com 공식 문서) 계획 단계에선 Gemini 3.1 Pro, 실행 단계에선 Gemini 3 Flash로 전환됩니다.
💡 공식 발표문과 실제 요금 구조를 교차해서 보니 이 부분이 보였습니다. “무료니까 느린 모델만 쓴다”고 생각하기 쉬운데, Plan 모드 중에는 Pro 모델이 자동으로 투입됩니다. 바로 이 지점이 3월 25일 무료 티어 차단과 맞물립니다.
DevOps.com의 분석을 보면 이 자동 전환을 이렇게 표현했습니다. “Strategy gets the reasoning model. Tactics get the speed model.” (출처: DevOps.com, 2026.03.16) 설계 품질은 Pro로 올리고 실행 속도는 Flash로 확보하는 구조입니다.
이 자동 전환을 끄고 싶으면 settings.json에서 "modelRouting": false로 설정하면 됩니다. 하지만 끄면 Plan 모드 전체에서 Pro 모델의 추론 이점을 포기하게 됩니다. 특별한 이유가 없으면 건드리지 않는 게 낫습니다.
무료 티어의 진짜 조건 — 3월 25일 이후 달라진 것
⚠️ 2026년 3월 25일부터 무료 티어에서 Gemini Pro 모델 접근이 차단됩니다. 무료 사용자는 Gemini Flash 모델만 사용 가능합니다.
GitHub Discussions(#22970)에 올라온 구글의 공식 업데이트 내용입니다. “Starting March 25, 2026, Gemini Pro models will only be accessible via paid subscriptions. Free tier users will be limited to Gemini Flash models.” (출처: google-gemini/gemini-cli GitHub Discussions #22970) Pro 모델을 계속 쓰려면 유료 플랜이 필요합니다.
Plan 모드는 계획 단계에서 자동으로 Pro 모델을 씁니다. 바로 위 섹션에서 다뤘듯이요. 그렇다면 결론은 명확합니다. 3월 25일 이후 무료 사용자는 Plan 모드를 실행해도 Pro 추론 대신 Flash 추론으로만 계획을 세우게 됩니다. Plan 모드는 유지되지만, 모델 라우팅의 핵심이 빠진 상태입니다.
| 구분 | 무료 (3.25 이후) | 유료 (Pro 이상) |
|---|---|---|
| Plan 모드 접근 | ✅ 가능 | ✅ 가능 |
| Plan 단계 모델 | Gemini Flash (제한) | Gemini 3.1 Pro (자동) |
| 일일 요청 한도 | 1,000회 (Flash) | 플랜별 상이 |
| 데이터 수집 동의 | 입출력 데이터 학습에 활용됨 (기본) | 별도 정책 적용 |
무료 티어 사용 시 입력 및 출력 데이터가 모델 학습에 활용될 수 있습니다. 코드에 민감한 정보가 포함된 경우 주의가 필요합니다. (출처: Shipyard.build 비교 분석, 2026.01.15)
Claude Code Plan 모드와 뭐가 다른가
같아 보이지만 출발점이 다릅니다
Claude Code에도 Plan 모드가 있습니다. 이름이 같아서 헷갈리는데, 실제로 꽤 다르게 동작합니다. 가장 큰 차이는 기본값입니다. Claude Code는 기본적으로 코드 편집 권한이 열려 있고, 사용자가 명시적으로 Plan 모드를 호출해야 합니다. Gemini CLI는 반대입니다. 설치 직후 기본값이 Plan(읽기 전용)입니다.
💡 두 도구의 Plan 모드를 나란히 두고 보니 이 차이가 보였습니다. Gemini는 “먼저 막고 풀어주는” 방식, Claude Code는 “먼저 열어두고 필요할 때 잠그는” 방식입니다. 어느 쪽이 더 낫다는 게 아니라, 팀의 코드 관리 문화에 따라 선호가 갈립니다.
| 항목 | Gemini CLI Plan 모드 | Claude Code (일반) |
|---|---|---|
| 기본값 | Plan 모드 (읽기 전용) | 편집 허용 (명시적 호출 필요) |
| 컨텍스트 창 | 100만 토큰 | 100만 토큰 (Sonnet 4.5 기준) |
| 플랜 파일 저장 | .md 파일로 로컬 저장 | 세션 내 메모리 (파일 미저장) |
| 무료 여부 | 무료 (Flash만, 3.25 이후) | 유료 ($20~$200/월) |
| 복잡한 코드베이스 분석 | 정밀한 지시 필요 | 자체 수정·방향 전환 더 능숙 |
Shipyard.build의 비교 분석(2026.01.15)에 따르면, Gemini CLI는 구체적인 지시를 줄수록 결과가 좋아지는 반면, Claude Code는 막힌 상황에서 스스로 방향을 바꾸는 능력이 더 낫습니다. 간단하고 명확한 작업이면 Gemini CLI가 충분하고, 수십 개 파일에 걸친 복잡한 리팩터링이면 Claude Code 쪽이 안전합니다. (출처: Shipyard.build, 2026.01.15)
Plan 모드를 쓸 때 놓치기 쉬운 조건 3가지
공식 문서를 꼼꼼히 읽다 보면 겉으로 드러나지 않는 조건들이 몇 가지 있습니다.
YOLO 모드에서는 Plan 모드 진입 불가
--yolo 옵션으로 Gemini CLI를 실행하면 모든 작업에 자동 승인이 적용됩니다. 이 모드에서는 enter_plan_mode 도구 자체가 비활성화됩니다. 자동화 파이프라인에서 YOLO 모드를 쓴다면 Plan 모드는 아예 작동하지 않습니다. (출처: geminicli.com 공식 문서)
커스텀 플랜 디렉터리는 프로젝트 루트 안에만 가능
플랜 저장 위치를 settings.json으로 변경할 수 있지만, 반드시 현재 프로젝트 루트 내부 경로여야 합니다. 외부 경로를 지정하면 Plan 모드의 안전 정책이 차단합니다. 중요 시스템 파일을 실수로 덮어쓰지 못하게 막는 설계입니다. (출처: geminicli.com 공식 문서)
비대화형(headless) 환경에서는 자동으로 YOLO로 전환됨
CI/CD 파이프라인처럼 대화가 불가능한 환경에서 --approval-mode plan으로 실행하면, 플랜 승인 후 자동으로 YOLO 모드로 전환되어 코드 변경이 실행됩니다. 보안 민감한 환경에서 의도치 않은 코드 변경이 발생할 수 있으므로 파이프라인 설계 시 주의가 필요합니다. (출처: geminicli.com 공식 문서)
자주 묻는 질문
마치며
Gemini CLI Plan 모드에서 생각보다 중요한 포인트가 두 가지였습니다. 하나는 기본값이라는 것. 설치하면 이미 Plan 모드입니다. 빠르게 코드를 바꾸고 싶다면 오히려 설정을 바꿔야 합니다. 다른 하나는 무료 티어 변경입니다. 3월 25일 이후 무료 사용자는 Plan 단계에서 Pro 모델을 못 쓰게 됐습니다. Plan 모드를 제대로 활용하려면 유료 플랜을 쓰거나, Flash 모델로 할 수 있는 작업의 범위를 파악해야 합니다.
솔직히 말하면, Plan 모드 자체는 잘 만들어진 기능입니다. “먼저 읽고, 물어보고, 실행한다”는 흐름이 실수를 줄이는 데 분명히 효과가 있습니다. 단, 이 기능의 핵심인 모델 자동 라우팅이 3월 25일 이후 무료에서는 반쪽짜리가 됐다는 점은 솔직하게 인정해야 합니다. 간단한 코드 읽기·문서 생성 정도라면 무료 Flash로도 Plan 모드가 쓸만하고, 복잡한 아키텍처 설계는 유료 Pro 모델이 필요합니다. 상황에 맞게 판단하시면 됩니다.
본 포스팅 참고 자료
- Gemini CLI 공식 문서 — Plan Mode (geminicli.com)
- ADTmag — Google Adds Plan Mode to Gemini CLI (2026.03.12)
- DevOps.com — Gemini CLI Plan Mode Separates Thinking From Doing (2026.03.16)
- Shipyard.build — Claude Code vs Gemini CLI 비교 분석 (2026.01.15)
- GitHub — google-gemini/gemini-cli Discussions #22970 무료 티어 변경 공지
⚠️ 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. Gemini CLI의 요금제 및 무료 티어 정책은 Google의 결정에 따라 언제든지 바뀔 수 있으므로, 최신 정보는 공식 요금 페이지에서 직접 확인하시기 바랍니다. 본 글의 내용은 2026년 4월 1일 기준 공개된 공식 자료를 바탕으로 작성됐습니다.
댓글 남기기