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

Gemini CLI Plan 모드는 AI가 코드를 수정하기 전에 반드시 읽기 전용으로 먼저 탐색하도록 강제하는 기능입니다. 2026년 3월 11일 구글 개발자 블로그를 통해 공식 출시됐고, 현재는 모든 사용자에게 기본값으로 활성화돼 있습니다. (출처: Google Developers Blog, 2026.03.11)

핵심 구조는 세 단계입니다. 먼저 연구(Research) — read_file, grep_search, glob 같은 읽기 전용 도구만 써서 코드베이스를 탐색합니다. 그 다음 설계(Design) — ask_user 도구로 사용자에게 선택지를 제시하고, 필요한 정보를 역으로 질문합니다. 마지막으로 계획(Plan) — 마크다운 파일 형태의 실행 계획을 생성하고 사용자 승인을 받은 뒤에야 구현 단계로 넘어갑니다.

이 구조가 생긴 이유는 분명합니다. AI 코딩 에이전트가 “합의되지 않은 방향으로 먼저 코드를 바꿔버리는” 문제를 업계 전체가 겪어왔고, Plan 모드는 이를 구조적으로 막는 방식입니다.

▲ 목차로 돌아가기

어떻게 쓰는 건지 — 진입 방법과 흐름

Gemini CLI가 이미 설치돼 있다면 Plan 모드 진입은 세 가지 방법 중 하나로 합니다. 타이핑으로 /plan을 입력하거나, Shift+Tab을 눌러 승인 모드를 전환하거나, “start a plan for …”처럼 자연어로 요청하면 됩니다. 기본 승인 모드 사이클은 Default → Auto-Edit → Plan 순서입니다. (출처: geminicli.com/docs/cli/plan-mode, 2026.03.11)

처음부터 Plan 모드로 시작하고 싶다면 gemini --approval-mode=plan으로 실행하거나, /settings에서 “Default Approval Mode”를 Plan으로 설정하면 매번 새 세션이 Plan 모드로 열립니다.

계획 파일을 검토하면서 직접 편집도 가능합니다. Ctrl+X를 누르면 외부 에디터(VS Code, Vim 등)로 계획 파일이 열리고, 단계를 수정하거나 인라인 코멘트를 남기면 Gemini CLI가 그 내용을 반영해 계획을 업데이트합니다. 계획이 마음에 들지 않으면 Esc로 취소하고 다시 요청하면 됩니다.

▲ 목차로 돌아가기

1,500 요청이 실제로 어떻게 쪼개지는가

공식 문서에 나오는 수치부터 짚고 넘어갑니다. Google AI Pro 구독 기준 하루 최대 1,500 API 요청이 할당됩니다. 무료(Google 계정 로그인)는 1,000 요청, API 키 무료는 250 요청입니다. (출처: geminicli.com/docs/resources/quota-and-pricing, 2026.03)

여기서 생각보다 중요한 사실이 있습니다. 이 “요청 수”는 사용자가 보내는 메시지 수가 아닙니다. 메시지 하나를 보낼 때 Gemini CLI가 내부적으로 여러 번 API를 호출하기 때문에, 실제 대화 가능 횟수는 훨씬 적습니다. r/GeminiCLI 커뮤니티의 실사용 데이터를 보면 더 선명합니다.

(출처: geminicli.com/docs/resources/quota-and-pricing, r/GeminiCLI 실사용 데이터, 2026.03.08 기준 / 약 수치)

Google AI Pro 기준으로 Gemini 3.1 Pro 메시지는 하루 50~60개가 실제 한도입니다. 나머지 약 1,300 API 요청은 Gemini 3 Flash 배정입니다. 1,500 요청을 메시지 수로 바로 대입하면 크게 착각하게 됩니다.

▲ 목차로 돌아가기

Plan 모드가 Pro 쿼터를 빠르게 소진하는 이유

이 부분이 핵심입니다. Plan 모드에서 Gemini CLI는 자동 모델 라우팅으로 계획 단계에는 Gemini 3.1 Pro를 우선 배정합니다. 고추론 모델로 아키텍처 결정과 복잡한 의존성 분석을 처리하는 것이 목표이기 때문입니다. (출처: Google Developers Blog 공식 발표문, 2026.03.11)

구현 단계로 넘어가면 Gemini CLI는 Flash 모델로 자동 전환됩니다. 빠른 실행이 필요한 구현에는 속도 모델을, 판단이 필요한 계획에는 추론 모델을 쓰는 구조입니다. 전략적으로는 합리적이지만, 무료 또는 Pro 구독 사용자 입장에서는 Pro 쿼터 배분이 Plan 모드에 집중적으로 소비된다는 뜻이기도 합니다.

모델 라우팅을 끄고 싶다면 settings.json에 아래 설정을 추가하면 됩니다. 그러면 Plan 모드에서도 수동으로 모델을 선택할 수 있습니다.

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

현재 세션의 모델별 사용량은 /stats session 명령으로 확인할 수 있습니다. 남은 Pro 쿼터를 체크하는 유일한 실시간 방법입니다.

▲ 목차로 돌아가기

Claude Code Auto-Edit과 뭐가 다른가

Claude Code에는 Auto-Edit 모드가 있습니다. AI가 판단하는 즉시 파일을 수정하고, 사용자는 결과를 사후에 검토하는 방식입니다. Gemini CLI의 Plan 모드는 반대입니다. 수정 전에 계획을 제시하고 승인을 받습니다. 어느 쪽이 낫다는 게 아니라, 원하는 통제 수준에 따라 선택하는 기준이 다릅니다.

(출처: geminicli.com, shipyard.build/blog, 2026.01.15 기준)

실사용 비교에서 Claude Code는 오류 로그를 주면 자체적으로 방향을 수정하는 복원력이 높다고 평가됩니다. Gemini CLI는 정밀한 지시를 주면 더 강하게 반응하지만, 방향이 틀렸을 때 스스로 수정하는 능력은 Claude Code보다 약하다는 것이 실사용자들의 공통된 평가입니다. (출처: shipyard.build/blog, 2026.01.15)

▲ 목차로 돌아가기

MCP 연동과 codebase_investigator의 실질적 의미

Plan 모드는 로컬 파일뿐 아니라 읽기 전용 MCP 도구도 사용할 수 있습니다. 예를 들어 github_read_issue로 GitHub 이슈를 읽거나, postgres_read_schema로 DB 스키마를 확인하거나, Google Docs 문서를 탐색하는 것이 Plan 모드 안에서 가능합니다. 코드베이스 외부 컨텍스트를 계획에 반영하면서도 실제 시스템은 건드리지 않는 구조입니다. (출처: Google Developers Blog, 2026.03.11)

Plan 모드에서 허용된 연구 서브에이전트 중 codebase_investigator는 단순 파일 읽기와 다릅니다. 복잡한 시스템 의존성을 추적하고 워크플로를 분석하는 전용 역할로, 대규모 마이그레이션이나 멀티 서비스 기능 추가 작업에서 탐색 깊이가 달라집니다. 커스텀 서브에이전트를 policy 파일에 추가해 Plan 모드에서 활성화하는 것도 가능합니다.

데이터베이스 마이그레이션을 예로 들면, Plan 모드가 현재 스키마를 읽고, 관련 GitHub 이슈를 확인하고, 기존 문서를 검토한 뒤 — 코드 한 줄 바꾸지 않고 — 마이그레이션 계획서를 제출합니다. DevOps 환경에서 실질적으로 유용한 지점입니다.

▲ 목차로 돌아가기

실제로 쓸 만한 상황과 피해야 할 상황

솔직히 말하면, Plan 모드가 빛을 발하는 상황과 오히려 방해가 되는 상황이 꽤 명확합니다.

간단한 작업에 Plan 모드를 쓰면 탐색 → 질문 → 계획 사이클이 과도한 오버헤드가 됩니다. 실제로 GitHub 이슈에는 Plan 모드 활성화 이후 단순 작업에서 10분 이상 “thinking” 상태가 지속된다는 보고가 있습니다. (출처: google-gemini/gemini-cli GitHub Issues #23795, 2026.03.25)

계획이 필요 없는 간단한 작업에는 /settings에서 Plan 모드를 Shift+Tab 사이클에서 제거하거나, Auto-Edit 모드를 기본값으로 설정해 두는 게 더 실용적입니다.

▲ 목차로 돌아가기

Q&A

▲ 목차로 돌아가기

마치며

Gemini CLI Plan 모드는 방향이 맞습니다. AI 에이전트가 “먼저 생각하고, 합의 후에 실행”하도록 구조화하는 흐름은 업계 전반의 방향이기도 합니다. 특히 대규모 리팩터링이나 DB 마이그레이션처럼 실수가 비싼 작업에서는 읽기 전용 탐색 단계가 진짜 보험 역할을 합니다.

다만 무료 사용자라면 한 가지만 기억하면 됩니다. Plan 모드 기본 활성화 + 자동 Pro 모델 라우팅 조합이 하루치 Gemini 3.1 Pro 쿼터를 예상보다 빠르게 소진합니다. 광고 문구의 “1,500 요청”은 메시지 수가 아니라 API 호출 수이고, Pro 모델 메시지로 환산하면 50~60개가 현실적인 한도입니다.

가볍게 쓸 때는 Plan 모드를 끄거나 Auto-Edit으로 돌아가고, 중요한 작업에만 Plan 모드를 켜는 방식이 쿼터 배분에 현명합니다. /stats session을 습관적으로 체크하면 쿼터 소진 타이밍을 미리 파악할 수 있습니다.

📚 본 포스팅 참고 자료

1. Google Developers Blog — Plan mode now available in Gemini CLI (2026.03.11)
2. Gemini CLI 공식 문서 — Plan Mode (2026.03.11)
3. Gemini CLI 공식 문서 — Quotas and Pricing (2026.03)
4. InfoWorld — Gemini CLI introduces plan mode (2026.03.12)
5. DevOps.com — Gemini CLI Plan Mode (2026.03.16)
6. Shipyard — Claude Code vs Gemini CLI (2026.01.15)
7. GitHub Issues — Gemini CLI thinking timeout (2026.03.25)