Plan 모드가 뭔지, 결론부터 말씀드리면

Gemini CLI Plan 모드는 AI가 코드를 수정하기 전에 먼저 읽기 전용 상태로 코드베이스를 분석하고, 실행 계획을 마크다운 파일로 작성해서 사용자 확인을 받은 뒤에야 실제 수정에 들어가는 방식입니다. 구글 개발자 블로그(2026.03.11)에는 이렇게 나옵니다. “Plan mode is a read-only mode that restricts Gemini CLI to a subset of its tools.” 파일을 건드리지 않고, 읽고, 분석하고, 물어보고, 계획서를 쓴다. 그 계획서를 검토한 뒤 승인하면 그제야 실행으로 넘어갑니다.

실제로 써보면 흐름이 꽤 자연스럽습니다. Shift+Tab을 눌러 모드를 전환하거나 /plan을 입력하면 Plan 모드로 진입합니다. 이후 AI가 ask_user 툴로 “이 부분은 어떻게 처리할까요?”라고 물어보는 방식으로 대화하면서 계획서를 완성해 나갑니다. 확인 후 승인하면 구현 단계로 자동 전환됩니다.

문제는 이 구조가 쿼터 소비와 연결되는 방식에 있습니다. 이게 홍보 글에서는 잘 안 나와 있습니다.

▲ 목차로 돌아가기

읽기 전용이라는 게 생각보다 빡빡합니다

공식 문서에 명시된 Plan 모드 허용 툴 목록을 보면, 생각보다 상당히 제한적입니다. 파일 읽기(read_file, list_directory, glob), 검색(grep_search, 구글 웹 서치), 서브에이전트 호출, MCP 읽기 전용 툴 정도입니다. 셸 명령 실행은 기본적으로 막혀 있습니다. 단, 사용자가 별도 정책 파일(~/.gemini/policies/)을 만들어서 git status, git diff 같은 읽기 명령은 허용할 수 있습니다.

MCP 읽기 전용 툴이 지원된다는 점은 실용적으로 꽤 중요합니다. 예를 들어 GitHub MCP로 이슈를 읽거나, Postgres 스키마를 읽어오는 것이 Plan 모드 안에서 가능합니다. 단, 기본 설정에서는 읽기 전용 MCP 툴에도 사용자 확인이 뜹니다. 자동 승인하려면 별도 정책 파일을 작성해야 합니다.

그리고 Ctrl+X를 누르면 현재 계획서를 외부 에디터(VS Code, Vim 등)에서 직접 편집할 수도 있습니다. 계획서 파일 자체에 코멘트를 남기면 AI가 그것을 읽고 반영합니다. 이건 막상 해보면 꽤 편합니다.

▲ 목차로 돌아가기

구글 계정 vs API 키 — 쿼터가 4배 차이 납니다

API 키 무료는 하루 250건이고 Flash 모델만 씁니다. 구글 계정 OAuth 무료는 하루 1,000건에 Pro와 Flash를 자동으로 섞어서 씁니다. 4배 차이가 납니다. Plan 모드를 제대로 활용하려면 구글 계정 로그인 방식을 써야 합니다. API 키 무료 플랜에서는 Plan 모드 자체는 작동하지만, Flash 모델만 사용하기 때문에 복잡한 아키텍처 분석의 질이 달라집니다.

분당 한도도 눈여겨봐야 합니다. API 키 무료는 분당 10건이라서, Plan 모드에서 AI가 codebase_investigator 서브에이전트를 여러 번 호출하다가 rate limit에 걸리는 상황이 생깁니다. 공식 쿼터 문서에 이 부분이 명시되어 있지만, 대부분의 사용법 안내글에는 나오지 않습니다.

▲ 목차로 돌아가기

Plan 모드에서 Pro 모델을 쓰면 쿼터가 더 빨리 줄어듭니다

공식 문서에 이런 내용이 나옵니다. “While in Plan Mode, the CLI routes requests to a high-reasoning Pro model to ensure robust architectural decisions and high-quality plans.” Plan 모드에서는 Pro 모델로 자동 라우팅됩니다. (출처: geminicli.com/docs/cli/plan-mode/ — Automatic Model Routing 섹션) 그리고 계획이 승인되어 구현 단계로 넘어가면 자동으로 Flash 모델로 바뀝니다.

이 자동 전환 기능은 settings.json에서 "modelRouting": false로 꺼버릴 수 있습니다. 그러면 Plan 모드에서도 Flash만 씁니다. 쿼터가 부족한 상황이라면 이 설정을 끄는 게 낫습니다.

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

(출처: geminicli.com/docs/cli/plan-mode/ — Automatic Model Routing)

▲ 목차로 돌아가기

Google AI Pro 구독해도 CLI 쿼터는 그대로입니다

이 부분을 모르고 넘어가는 분이 많습니다. 구글의 공식 쿼터 문서(geminicli.com/docs/resources/quota-and-pricing/)에 아래 내용이 명시되어 있습니다.

정리하면, Google One을 통한 Google AI Pro(월정액) 구독은 gemini.google.com 웹 앱의 쿼터를 올려줄 뿐, Gemini CLI의 쿼터와는 별개입니다. CLI 쿼터를 올리려면 Google AI Pro가 아니라 Gemini Code Assist 구독이나 유료 API 키(PAYG)로 전환해야 합니다.

개인 사용자 기준으로 CLI 쿼터를 올리는 실질적인 방법은 Gemini API 키를 유료로 전환(PAYG)하는 것입니다. 그러면 사용한 만큼 과금되는 방식으로 한도가 올라갑니다. 쿼터 현황은 Gemini CLI 안에서 /stats model 명령으로 실시간 확인이 가능합니다.

▲ 목차로 돌아가기

Claude Code나 Cursor와 비교하면 어떻습니까

솔직히 말하면, Plan 모드의 개념 자체는 Cursor의 Composer나 Claude Code의 작업 방식과 비슷합니다. “먼저 분석하고, 확인 받고, 실행한다”는 흐름은 공통적입니다. 차이는 구조적인 안전장치를 툴 레벨에서 강제한다는 점입니다. Claude Code는 유저가 요청하면 바로 실행에 들어가는 경향이 있지만, Gemini CLI Plan 모드는 읽기 전용 제약을 시스템 정책으로 걸어둡니다.

가장 실용적인 차이는 무료 한도입니다. Gemini CLI는 구글 계정만 있으면 하루 1,000건을 무료로 씁니다. Claude Code는 Anthropic Pro 구독 없이는 의미 있는 작업이 어렵습니다. 개인 개발자가 부담 없이 터미널 AI 코딩을 시작하기에는 Gemini CLI 쪽이 접근성이 높습니다. 대신 다중 파일 편집의 안정성이나 에이전트 완성도는 Claude Code가 앞선다는 평가가 많습니다.

▲ 목차로 돌아가기

Q&A — 직접 검색해봤습니다

▲ 목차로 돌아가기

마치며 — 쓸 만하지만, 이 두 가지는 꼭 먼저 확인하세요

그런데 막상 써보기 전에 이 두 가지는 확인해두는 게 좋습니다. 첫째, 로그인 방식에 따른 쿼터 차이. API 키 무료는 하루 250건 Flash 전용이고, 구글 계정 OAuth는 하루 1,000건 Pro+Flash 자동입니다. 둘째, Google AI Pro 구독이 CLI 쿼터를 올려주지 않는다는 점. 공식 문서에 명확히 나와 있지만, 쉽게 눈에 안 띄는 위치에 있습니다.

Plan 모드가 기본값으로 켜지면서 Pro 모델 사용이 자동으로 늘어나는 구조, 그리고 쿼터가 초과되면 유료 전환이 필요한데 올바른 유료 경로를 선택해야 한다는 점. 이 두 가지를 파악하고 시작하면 훨씬 덜 당황합니다.

📎 본 포스팅 참고 자료

1. Google Developers Blog — Plan mode is now available in Gemini CLI
   https://developers.googleblog.com/plan-mode-now-available-in-gemini-cli/
2. Gemini CLI 공식 Plan Mode 문서
   https://geminicli.com/docs/cli/plan-mode/
3. Gemini CLI 공식 GitHub — README 및 Changelog
   https://github.com/google-gemini/gemini-cli
4. Gemini CLI 쿼터 및 가격 공식 문서
   https://geminicli.com/docs/resources/quota-and-pricing/