IT/AI
Gemini CLI Plan 모드, 빠르다고요? 이 조건 먼저 보세요
터미널에서 AI가 직접 코드를 짜주는 Gemini CLI가 3월 들어 Plan 모드를 기본값으로 바꿨습니다. “그냥 빠르게 코드 고쳐주는 도구”라고 생각하고 쓰다가 막히는 포인트가 딱 두 곳에 있습니다. 무료 한도와 모델 라우팅, 이 두 가지를 먼저 보지 않으면 예상치 못한 순간에 요청이 차단됩니다.
Plan 모드가 뭔지, 한 줄로 먼저
Gemini CLI Plan 모드는 코드를 건드리기 전에 AI가 먼저 읽기 전용으로 코드베이스를 훑고, 구체적인 실행 계획을 Markdown 파일로 뽑아주는 기능입니다. 쉽게 말하면 “설계도 먼저, 실행은 그다음”입니다. 기존에는 Gemini CLI에 무언가를 요청하면 AI가 바로 파일을 수정하거나 명령어를 실행했습니다. 그게 편하긴 한데, 실수가 생기면 되돌리기 까다로웠죠.
Plan 모드에서 허용된 도구는 공식 문서에 딱 이렇게 나옵니다. read_file, list_directory, glob, 검색류 도구, 그리고 계획 파일에만 쓰기가 가능합니다. (출처: Gemini CLI 공식 문서 Plan Mode — Tool Restrictions, geminicli.com)
정리하면 Plan 모드에서는 파일 삭제도, 코드 실행도, 패키지 설치도 없습니다. 오직 읽고 분석하고 계획서 쓰는 것만 됩니다.
3월에 뭐가 바뀌었나 — v0.34.0 변경 내역
Plan 모드 자체는 2026년 2월 17일 v0.29.0에서 처음 도입됐습니다. 그런데 당시에는 기본값이 아니었고, 직접 /plan 명령어를 치거나 설정에서 켜야 작동했습니다. (출처: geminicli.com/docs/changelogs/ — v0.29.0, 2026.02.17)
2026년 3월 17일 v0.34.0이 배포되면서 상황이 달라졌습니다. 공식 릴리스 노트에 “Plan Mode is now enabled by default to help you break down complex tasks and execute them systematically”라고 명시됐습니다. 이제 별도 설정 없이 Gemini CLI를 켜면 Plan 모드가 활성화된 상태로 시작됩니다. 복잡한 작업을 시작하면 AI가 실행 전에 계획서를 먼저 내놓습니다.
| 버전 | 날짜 | Plan 모드 관련 변경사항 |
|---|---|---|
v0.29.0 |
2026.02.17 | Plan 모드 최초 도입, 수동 활성화 |
v0.32.0 |
2026.03.03 | 외부 편집기로 계획서 직접 수정 가능 |
v0.33.0 |
2026.03.11 | 서브에이전트·애노테이션 피드백 추가 |
| v0.34.0 | 2026.03.17 | Plan 모드 기본값 전환 ← 지금 여기 |
v0.35.2 |
2026.03.26 | 키보드 단축키 커스텀, 샌드박싱 강화 |
출처: geminicli.com/docs/changelogs/ (2026.03.26 기준)
계획 단계에서 Pro 모델이 돌아가는 이유
💡 공식 발표문과 실제 모델 라우팅 동작을 같이 놓고 보니 이런 차이가 보였습니다. Plan 모드를 쓰면 “더 빠른 Flash로 처리하니 좋다”는 이야기가 많은데, 실제로는 계획 단계에서 더 무거운 Pro가 돌아갑니다.
Gemini CLI는 현재 자동 모델 라우팅을 기본으로 씁니다. 이 라우팅 방식이 Plan 모드와 맞물리면 실제로 이렇게 작동합니다.
공식 문서에서 확인한 자동 라우팅 흐름
- 계획 단계(Plan Mode 활성 중): 요청을 고추론 Pro 모델로 라우팅
- 구현 단계(계획 승인 후): 고속 Flash 모델로 자동 전환
출처: geminicli.com/docs/cli/plan-mode/ — Automatic Model Routing 섹션
이 말은 하나의 작업 안에서도 모델이 바뀐다는 뜻입니다. 설계 단계에서는 Gemini 3.1 Pro급이 구조를 분석하고, 실제 코드 작성 단계에서는 Flash가 처리합니다. 속도와 비용 면에서는 Flash가 낫지만, 아키텍처 판단은 Pro가 합니다. 즉, Plan 모드 없이 무조건 빠르게 구현만 시키면 설계 판단도 Flash가 하게 됩니다. 복잡한 작업일수록 Plan 모드가 켜져 있는 편이 품질에 유리합니다.
이 자동 스위칭은 설정에서 끌 수 있습니다. settings.json에서 "plan": {"modelRouting": false}를 추가하면 됩니다. 단, 이렇게 하면 계획 단계에서도 Flash가 돌 수 있다는 점을 감안해야 합니다.
무료로 쓸 수 있다고요? 로그인 방식부터 다릅니다
💡 “Gemini CLI는 무료”라는 말을 자주 보는데, 로그인 방식에 따라 하루 한도가 4배 차이 납니다. 공식 요금 문서와 실제 한도를 같이 보니 이 차이가 분명하게 보였습니다.
Gemini CLI는 무료로 쓸 수 있습니다. 다만 “어떤 방식으로 로그인하느냐”에 따라 하루에 쓸 수 있는 요청 횟수가 완전히 달라집니다. 공식 요금 페이지에 정리된 수치를 보면 이렇습니다.
| 로그인 방식 | 플랜 | 일일 최대 요청 | 사용 모델 |
|---|---|---|---|
| 구글 계정 | Code Assist (무료) | 1,000회 | Gemini 모델 전체 |
| 구글 계정 | Google AI Pro | 1,500회 | Gemini 모델 전체 |
| 구글 계정 | Google AI Ultra | 2,000회 | Gemini 모델 전체 |
| API Key | 무료 티어 | 250회 | Flash 모델만 |
| Vertex AI | Express Mode (무료) | 90일 한시 | 계정별 상이 |
출처: geminicli.com/docs/resources/quota-and-pricing/ (2026.03.26 기준)
수치가 의미하는 바는 간단합니다. API Key 무료 티어로 시작하면 구글 계정 무료 대비 하루 한도가 4분의 1에 불과합니다. Plan 모드가 기본값이 된 지금, 복잡한 작업 하나에 요청이 여러 번 소모될 수 있다는 점을 감안하면 API Key로는 하루에 대형 프로젝트 두세 개 처리하기가 빠듯합니다.
솔직히 말하면 처음엔 저도 API Key로 시작했다가 한도가 너무 빨리 찼습니다. 구글 계정 로그인으로 전환하니 1,000회가 되면서 훨씬 여유가 생겼습니다. 개인 사용이라면 구글 계정 로그인이 현실적으로 가장 합리적인 선택입니다.
실제로 막히는 조건 3가지
Plan 모드를 쓰다 보면 “왜 이게 안 되지?”라는 순간이 있습니다. 공식 도구 제한 문서와 실사용 흐름을 같이 보면 대부분 세 가지 이유입니다.
Plan 모드에서 npm install이 안 됩니다
Plan 모드는 읽기 전용 환경입니다. run_shell_command가 기본적으로 차단됩니다. 패키지 설치나 테스트 실행이 필요하면 먼저 계획을 승인해서 Plan 모드를 빠져나온 뒤 실행해야 합니다. 정책 파일에 예외를 추가하면 git status, git diff는 Plan 모드에서도 허용할 수 있습니다. (출처: geminicli.com/docs/cli/plan-mode/ — Custom Policies)
계획 파일은 프로젝트 루트 밖에 저장 안 됩니다
커스텀 플랜 디렉토리를 설정해도 프로젝트 루트 내부로만 제한됩니다. 공식 문서에 “user-configured paths for the plans directory are restricted to the project root”라고 명시돼 있습니다. 외부 경로로 설정하면 보안 정책으로 차단됩니다. 계획서를 다른 위치에 보관하고 싶다면 훅(hook)을 써서 GCS 같은 외부 스토리지로 자동 복사하는 방식을 써야 합니다.
YOLO 모드에선 Plan 모드 단축키가 없습니다
Shift+Tab으로 모드를 전환할 때 YOLO 모드가 활성화돼 있으면 Plan 모드가 순환에서 빠집니다. 공식 문서 기준으로 enter_plan_mode 도구 자체가 YOLO 모드에서는 사용 불가입니다. CI/CD 파이프라인에서는 반대로 Plan 모드가 자동으로 YOLO로 전환돼 계획 후 실행이 자동화됩니다.
이 세 가지는 “왜 안 되지?”로 시간 허비하는 대표적인 경우입니다. 각각 원인이 명확하고, 공식 문서에 우회 방법도 있습니다.
Plan 모드를 쓰면 진짜 달라지는 워크플로
💡 기존 AI 코딩 도구와 비교할 때 Plan 모드의 차이는 단순히 “계획서 하나 더 나온다”가 아닙니다. Pro 모델이 설계를 잡고 Flash가 구현한다는 구조가, 비용과 품질을 동시에 조율하는 방식이라는 점이 보입니다.
기존에 AI 코딩 도구를 쓸 때는 “이렇게 바꿔줘” 한 마디로 시작해서 AI가 즉시 코드를 수정하는 방식이었습니다. 빠르긴 한데, 의존성을 잘못 건드리거나 다른 모듈에 영향을 주는 경우가 생겼습니다. Plan 모드는 이 흐름을 바꿉니다.
실제 워크플로를 보면 이렇습니다. 목표를 입력하면 AI가 먼저 코드베이스를 읽기 전용으로 순회합니다. 그 과정에서 ask_user 도구를 통해 “A 방식과 B 방식 중 어느 쪽이 맞나요?” 같은 질문을 던집니다. 선택이 끝나면 Markdown 파일로 구체적인 실행 계획서가 나옵니다. 계획서를 Ctrl+X로 열어서 직접 수정하거나 피드백을 남기면 AI가 계획을 다듬습니다. 승인하면 그때부터 실행입니다.
이 구조가 만드는 실질적인 차이는 두 가지입니다. 첫째, 잘못된 실행을 사전에 막을 수 있습니다. 계획서 단계에서 “이 부분 틀렸다”고 피드백하면 코드를 한 줄도 건드리지 않고 수정됩니다. 둘째, 모델 비용이 구조적으로 최적화됩니다. 설계 판단은 Pro가 하지만 실제 코드 작성은 Flash가 처리하니, 전체를 Pro로 돌리는 것보다 토큰 비용이 줄어듭니다.
Cursor나 GitHub Copilot과의 차이점도 여기서 나옵니다. 두 도구는 편집기에 통합된 형태라 실시간으로 코드를 제안하는 방식에 초점이 맞춰져 있습니다. Gemini CLI Plan 모드는 반대로 “먼저 전략을 세우고 실행하라”는 철학을 기반으로 설계됐습니다. 터미널 기반이라 IDE 없이도 돌아간다는 점도 차이입니다.
Q&A
Q. Plan 모드를 끄고 싶으면 어떻게 하나요? ＋
설정에서 /settings를 열어 Default Approval Mode를 Plan 외 다른 옵션으로 바꾸면 됩니다. 또는 Shift+Tab으로 모드를 순환해 Default나 Auto-Edit로 전환할 수 있습니다. v0.34.0 이후로 기본값이 Plan 모드로 바뀌었지만 강제가 아니라 사용자가 언제든 변경 가능합니다. (출처: geminicli.com/docs/cli/plan-mode/)
Q. 무료로 쓰는 가장 좋은 방법은 뭔가요? ＋
구글 계정으로 로그인하는 방식이 하루 1,000회로 가장 넉넉합니다. API Key 무료 티어는 250회이고 Flash 모델만 돼서 Plan 모드에서 Pro 라우팅이 안 됩니다. 처음 시작한다면 구글 계정 로그인을 권장합니다. 그 이상이 필요하면 Google AI Pro(유료) 또는 Vertex AI Express Mode(90일 한시 무료)가 옵션입니다. (출처: geminicli.com/docs/resources/quota-and-pricing/)
Q. 계획서 파일이 어디에 저장되나요? ＋
기본 경로는 ~/.gemini/tmp/<project>/<session-id>/plans/입니다. 세션은 기본 30일 보관 후 자동 삭제됩니다. 커스텀 디렉토리를 설정하면 프로젝트 루트 내 원하는 위치로 바꿀 수 있습니다. 단, 이 경우 파일 자동 삭제가 적용되지 않으므로 직접 관리해야 합니다. (출처: geminicli.com/docs/cli/plan-mode/ — Custom plan directory)
Q. Cursor, GitHub Copilot이랑 뭐가 다른가요? ＋
Cursor와 GitHub Copilot은 편집기 안에서 실시간 코드 제안과 자동완성에 집중합니다. Gemini CLI는 터미널에서 돌아가는 에이전트 방식이라, IDE가 없어도 작동하고 대규모 코드베이스 전체를 한 번에 분석하는 데 더 유리합니다. Plan 모드는 특히 “설계 → 검토 → 실행” 워크플로를 강제하는 점에서 다른 도구와 성격이 다릅니다.
Q. Plan 모드 중에 AI가 질문을 너무 많이 해서 귀찮은데요? ＋
요청을 처음 넣을 때 충분히 구체적으로 목표와 방향을 써주면 ask_user 호출이 줄어듭니다. 반복적인 질문이 부담스럽다면 스킬(Skill)을 만들어 특정 작업 유형에 대한 기본 지침을 미리 등록해 두는 방법이 있습니다. 또는 단순한 작업은 Auto-Edit 모드를 써서 Plan 없이 바로 진행하는 편이 낫습니다.
마치며
Gemini CLI Plan 모드는 3월 이전에도 있었지만, v0.34.0이 되면서 처음 설치하는 사람도 기본으로 만나게 됐습니다. “왜 갑자기 코드를 안 짜고 계획서를 내놓지?”라는 반응이 나올 수 있는 이유가 바로 여기에 있습니다.
핵심 포인트 두 가지를 다시 정리하면 이렇습니다. 로그인 방식에 따라 무료 한도가 4배까지 차이 나고, Plan 모드에서는 계획 단계에 한해 Pro 모델이 자동으로 투입됩니다. 이 두 가지를 모르고 쓰면 한도가 생각보다 빨리 달리거나, “왜 Plan 모드에서 Pro 모델이 쓰이는 거지?”라고 헷갈릴 수 있습니다.
개인적으로는 Plan 모드가 귀찮다고 느껴질 때도 있습니다. 단순한 수정 하나에도 계획서가 나오니까요. 그런데 프로젝트 구조를 건드리는 작업에서는 실제로 실수를 두 번 막아줬습니다. 설계 단계에서 “이 방향으로 가면 저 모듈과 충돌합니다”를 잡아냈기 때문입니다. 간단한 작업은 Auto-Edit 모드로, 복잡한 리팩터링은 Plan 모드로 구분해서 쓰는 편이 실용적입니다.
본 포스팅 참고 자료
- Gemini CLI 공식 Plan 모드 문서 — geminicli.com/docs/cli/plan-mode/
- Gemini CLI 공식 릴리스 노트 — geminicli.com/docs/changelogs/
- Gemini CLI 요금·한도 공식 문서 — geminicli.com/docs/resources/quota-and-pricing/
- Google Adds Plan Mode to Gemini CLI (ADTmag, 2026.03.12) — adtmag.com
- Google for Developers Korea 위클리 업데이트 (2026.03.13) — developers-kr.googleblog.com
본 포스팅은 2026년 3월 27일 기준으로 작성됐습니다. Gemini CLI는 활발히 업데이트되는 오픈소스 프로젝트로, 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 최신 정보는 공식 문서(geminicli.com)에서 직접 확인하세요.
댓글 남기기