Plan 모드가 뭔지 30초 요약

Gemini CLI Plan 모드는 2026년 3월 11일 Google이 공식 발표한 기능으로, AI가 코드 수정에 손대기 전에 먼저 코드베이스를 탐색하고 계획서를 작성하도록 강제하는 읽기 전용 실행 환경입니다. (출처: Google Developers Blog, 2026.03.11)

기존에는 Gemini CLI가 프롬프트를 받으면 바로 파일을 수정하거나 명령을 실행하려 했습니다. Plan 모드에서는 read_file, grep_search, glob 같은 읽기 전용 툴만 허용되고, 파일 수정은 ~/.gemini/tmp/ 아래 플랜 Markdown 파일에만 가능합니다. (출처: geminicli.com 공식 문서)

진입 방법은 세 가지입니다. 터미널에서 /plan을 입력하거나, Shift+Tab으로 모드를 순환하거나, 자연어로 “이 기능 계획 잡아줘”라고 말하면 됩니다. 별도 설정 없이 기본값으로 켜져 있습니다.

▲ 목차로 돌아가기

읽기 전용인데 Pro 한도가 왜 빨리 줄어들까

Plan 모드가 읽기만 하니까 가벼울 거라고 생각하기 쉽습니다. 막상 쓰면 다릅니다. 공식 문서에 이렇게 나옵니다. “계획 단계에서는 높은 추론 능력을 가진 Pro 모델, 구체적으로 Gemini 3.1 Pro로 자동 라우팅된다.” (출처: geminicli.com Plan Mode 공식 문서, Automatic Model Routing 항목)

그리고 여기서 중요한 점이 하나 더 있습니다. 1,500이라는 숫자는 메시지 횟수가 아니라 API 호출 횟수입니다. Gemini CLI는 한 번의 메시지 처리 중에 루프 감지, 모델 라우팅 판단, 내부 서브에이전트 호출 등을 위해 여러 번의 API 요청을 내부적으로 발생시킵니다. 실제 사용자 메시지 1건이 API 요청 3~5건으로 바뀐다는 뜻입니다. 결국 Pro 한도 200 API 호출은 실제 대화 기준으로 40~60회 수준에서 소진됩니다. Pro로 수십 번 대화하면 끝납니다.

Plan 모드는 구조상 탐색 → 설계 → 계획서 작성까지 여러 단계를 거칩니다. 단계마다 Pro 모델이 호출되니 일반 대화보다 API 요청이 훨씬 많이 쌓입니다. 읽기만 한다는 게 오히려 한 세션에서 더 많은 추론 단계를 돌린다는 의미입니다.

▲ 목차로 돌아가기

실제로 쓸 수 있는 도구 목록과 막히는 지점

Plan 모드에서 허용되는 도구는 공식 문서에 명확하게 열거되어 있습니다. 파일 읽기(read_file, list_directory, glob), 검색(grep_search, google_web_search), 서브에이전트(codebase_investigator), 사용자 질문(ask_user), 그리고 읽기 전용으로 표시된 MCP 도구입니다. (출처: geminicli.com 공식 문서, Tool Restrictions 항목)

여기서 실제로 많이 막히는 부분이 MCP입니다. GitHub 이슈 읽기, Postgres 스키마 조회처럼 외부 데이터를 당겨오는 MCP 도구는 readOnlyHint = true로 표시된 것만 Plan 모드에서 작동합니다. 그런데 기본 설정 상태에서는 이 도구들도 매번 사용자 확인을 요구합니다. 정책 파일(~/.gemini/policies/)에 별도 규칙을 추가해야 자동 승인이 됩니다. 데이터베이스 마이그레이션 계획을 세우려는데 스키마 조회조차 매번 승인해야 한다면 사실상 쓰기 어렵습니다. (출처: geminicli.com 공식 문서 Custom Policies 항목)

▲ 목차로 돌아가기

ask_user 툴, 기존 방식과 달라진 점

Plan 모드와 함께 추가된 ask_user 툴은 구조가 기존 대화와 다릅니다. 기존 Gemini CLI는 프롬프트를 받으면 가정을 세우고 바로 실행에 들어갔습니다. ask_user가 도입되면서 에이전트가 탐색 중간에 자발적으로 멈추고 “이 의존성을 새 라이브러리로 교체할까요, 아니면 기존 구조를 유지할까요?”처럼 선택지를 제시합니다. (출처: Google Developers Blog, 2026.03.11)

이 구조의 의미는 생각보다 큽니다. AI 코딩 도구에서 가장 흔한 실패 패턴이 “에이전트가 잘못된 방향을 확신하고 구현한 다음 사후에 수정하는 것”이었습니다. ask_user는 그 실패를 계획 단계에서 차단합니다. 계획이 완성된 뒤에는 Ctrl+X로 외부 에디터에서 직접 플랜 Markdown을 수정할 수도 있고, 피드백을 채팅으로 전달하면 계획을 다시 세웁니다.

다만 실사용에서 언급되는 한계도 있습니다. Reddit 사용자들의 공통된 피드백은 Gemini CLI가 복잡한 작업에서 “작업을 끝냈다”고 선언하고 멈추는 패턴이 반복된다는 것입니다. Plan 모드가 이 문제를 줄여줄 수는 있지만, 기저 모델의 특성 자체가 달라지지는 않습니다. (출처: Reddit r/GeminiCLI, 2026.03.11)

▲ 목차로 돌아가기

Claude Code 플랜 기능과 비교하면

Gemini CLI Plan 모드와 Claude Code의 플랜 접근 방식은 핵심 철학부터 다릅니다. Gemini CLI는 Plan 모드를 명시적으로 분리된 실행 환경으로 구현했습니다. 모드 전환, 읽기 전용 강제, 모델 라우팅 자동 변경이 모두 구조적으로 묶여 있습니다. Claude Code는 이와 달리 계획 지시를 일반 대화 흐름 안에서 처리하는 방식을 기본으로 합니다. (출처: Shipyard.build 비교 분석, 2026.01.15)

비용 구조만 보면 Gemini CLI가 유리합니다. 그런데 여기서 놓치기 쉬운 지점이 있습니다. Plan 모드가 Pro 한도를 집중 소모하는 구조라, 하루에 대형 작업을 여러 건 처리하려면 Pro 한도 200건이 예상보다 빨리 소진됩니다. 반면 Claude Code는 5시간 주기로 한도가 리셋되는 구조라 장시간 작업에서 리듬 관리가 다릅니다. 어느 쪽이 유리한지는 작업 패턴에 따라 갈립니다.

▲ 목차로 돌아가기

Pro 한도 아끼면서 쓰는 방법이 따로 있습니다

방법 1. 자동 모델 라우팅 비활성화. settings.json에 아래 설정을 추가하면 Plan 모드에서도 Pro를 자동 선택하지 않습니다. Pro 소모 속도가 줄어드는 대신 계획 품질이 낮아질 수 있어 절충이 필요합니다. (출처: geminicli.com 공식 문서, Automatic Model Routing 항목)

{
"general": {
"plan": {
"modelRouting": false
}
}
}

방법 2. 현재 사용량 실시간 확인. 세션 중 /stats session을 입력하면 Pro, Flash 각 모델별 API 호출 횟수가 표시됩니다. 한도가 얼마나 남았는지 감 없이 쓰다가 Pro 소진 후 Flash로 떨어지는 상황을 피할 수 있습니다. (출처: Reddit r/GeminiCLI 실사용 제보, 2026.03.08)

방법 3. 기본 모드를 Plan으로 고정하고 싶을 때는 신중하게. /settings에서 Default Approval Mode를 Plan으로 바꾸면 세션 시작부터 Plan 모드가 됩니다. 이렇게 하면 항상 Pro 모델이 먼저 붙는 구조가 되니 한도 소모가 가속됩니다. 큰 리팩터링 전에만 켜는 게 현실적입니다.

방법 4. MCP 읽기 전용 자동 승인 정책 추가. 데이터베이스 스키마나 GitHub 이슈 조회를 매번 승인하지 않으려면 ~/.gemini/policies/mcp-read-only.toml에 아래 규칙을 추가합니다. (출처: geminicli.com 공식 문서 Custom Policies 항목)

[[rule]]
mcpName = "*"
toolAnnotations = { readOnlyHint = true }
decision = "allow"
priority = 100
modes = ["plan"]

▲ 목차로 돌아가기

Q&A 5가지

▲ 목차로 돌아가기

마치며

Gemini CLI Plan 모드는 AI 코딩 도구가 “일단 실행하고 나중에 수정”이라는 패턴에서 벗어나려는 시도입니다. 생각보다 잘 설계된 기능입니다. 읽기 전용 강제, 계획서 파일 생성, ask_user를 통한 양방향 소통, 그리고 계획 단계에서만 Pro 모델을 붙이는 자동 라우팅까지 구조적으로 맞물려 있습니다.

그런데 그 자동 라우팅이 Pro 한도를 가장 빠르게 소모하는 요인이기도 합니다. “읽기만 하니까 가볍겠지”라는 예상과 달리, Plan 모드는 Pro 모델이 가장 집중적으로 투입되는 단계입니다. 하루 한도가 API 요청 약 200건으로 제한되어 있고, 실제 메시지 기준으로는 40~60회 수준입니다. Plan 모드를 자주 쓸 계획이라면 /stats session으로 사용량을 수시로 확인하고, 큰 작업 전에만 켜는 방식을 추천합니다.

Claude Code와 비교하면 Plan 모드의 구조적 분리는 Gemini CLI만의 강점입니다. 다만 MCP 제약, 작업 미완료 패턴, 복잡한 작업에서의 신뢰성은 아직 지켜봐야 할 부분입니다. 기저 모델이 더 강해지는 것과 함께 개선되어야 할 영역입니다.

▲ 목차로 돌아가기

본 포스팅 참고 자료

1. ① Google Developers Blog — Plan mode is now available in Gemini CLI (developers.googleblog.com)
2. ② Gemini CLI 공식 문서 — Plan Mode (geminicli.com)
3. ③ DevOps.com — Gemini CLI Plan Mode Separates Thinking From Doing (devops.com)
4. ④ Shipyard.build — Claude Code vs Gemini CLI (2026.01.15) (shipyard.build)
5. ⑤ Reddit r/GeminiCLI — Plan mode is now available / Pro limits 실사용 스레드 (2026.03)