Gemini CLI v최신
TECH
Gemini CLI Plan 모드, 쓰기 전에 이것 먼저 보세요
Gemini CLI Plan 모드가 2026년 3월 11일 공식 출시됐습니다. “읽기 전용이라 안전하다”는 설명이 먼저 눈에 들어오지만, 두 가지 상황에서 그 전제가 조용히 무너집니다. API Key로 무료 사용하는 경우, 그리고 CI/CD 파이프라인에 연결한 경우입니다. 공식 문서를 직접 뜯어보고 나서야 이 부분이 보였습니다.
Plan 모드가 생긴 이유, 핵심만 짚으면
Gemini CLI Plan 모드는 2026년 3월 11일 구글 개발자 블로그를 통해 공식 출시됐습니다. (출처: Google Developers Blog, 2026.03.11) 배경은 단순합니다. AI 코딩 에이전트가 코드를 너무 빨리, 너무 많이 건드리는 문제가 반복됐기 때문입니다.
기존 Gemini CLI의 기본 동작은 요청을 받으면 즉시 파일을 수정합니다. 리팩터링을 시키면 시키는 대로 파일 수십 개를 바꿔버리죠. 실수할 여지가 크고, 되돌리기도 번거롭습니다. Plan 모드는 그 흐름을 끊어줍니다. 먼저 읽고, 분석하고, 계획을 글로 써서 승인을 받은 뒤에야 실행에 들어갑니다.
기본값으로 활성화돼 있어서 별도 설치 없이 바로 쓸 수 있습니다. 터미널에서 /plan을 입력하거나 Shift+Tab으로 모드를 전환하면 됩니다. “start a plan for…” 식으로 자연어로 말해도 자동으로 진입합니다.
읽기 전용이 실제로 막는 것과 안 막는 것
Plan 모드에서 허용되는 도구는 공식 문서에 명확하게 적혀 있습니다. 파일 읽기(read_file), 디렉토리 탐색(list_directory), 패턴 검색(grep_search), 웹 검색, MCP 읽기 전용 도구가 전부입니다. (출처: Gemini CLI 공식 문서, Tool Restrictions 섹션) 파일 수정은 한 곳에서만 됩니다. ~/.gemini/tmp/<project>/<session-id>/plans/ 안의 마크다운 파일에 한해서만 write_file과 replace가 허용됩니다.
그러니까 프로젝트 코드는 절대 건드리지 않습니다. 대신 계획 파일(.md)만 씁니다. ask_user 도구를 통해 중간에 질문도 던집니다. “이 DB를 마이그레이션하려면 롤백 전략이 필요한데, 어떤 방식을 선호하세요?” 같은 식으로 선택지를 제시하고 대기합니다. 계획이 완성되면 Ctrl+X로 직접 계획 파일을 수정할 수도 있습니다.
단, MCP 읽기 전용 도구는 기본적으로 Plan 모드에서도 사용자 확인을 요구합니다. GitHub 이슈를 읽거나 PostgreSQL 스키마를 조회하는 작업도 마찬가지입니다. 자동 허용이 필요하면 별도 정책 파일(~/.gemini/policies/)을 만들어야 합니다. 공식 문서에 예시가 나와 있지만, 이 설정을 빠뜨리면 MCP 연동이 매번 확인 팝업으로 끊깁니다.
무료로 쓰면 Pro 모델이 아닙니다
💡 공식 발표문과 요금제 문서를 같이 놓고 보니 이런 차이가 보였습니다. Plan 모드 소개에서 강조하는 “Pro 모델 자동 라우팅”은 인증 방식에 따라 실제로 작동 안 할 수 있습니다.
공식 블로그는 Plan 모드를 소개하면서 이렇게 썼습니다. “플랜 단계에서는 고추론 Pro 모델인 Gemini 3.1 Pro가 사용되어 견고한 아키텍처 결정과 고품질 계획을 보장합니다.” (출처: Google Developers Blog, 2026.03.11) 좋게 읽히는 문장입니다. 그런데 이건 “Auto 모델을 사용할 때” 전제가 붙어 있습니다.
그리고 Auto 모델 + Pro 라우팅이 실제로 동작하는 건 구글 계정으로 로그인(OAuth)한 경우뿐입니다. API Key 무료 사용자는 다릅니다. Gemini CLI 공식 요금 문서에 딱 이렇게 나옵니다. “API Key 무료 티어는 Flash 모델에만 요청이 갑니다.” (출처: Gemini CLI 공식 문서, Quota and Pricing) Plan 모드를 써도 Plan 모드가 아닌 겁니다. 아키텍처 분석에 Flash가 들어갑니다.
| 인증 방식 | 일일 요청 | Plan 모드 모델 | Pro 자동 라우팅 |
|---|---|---|---|
| Google OAuth (무료) | 1,000건 | Gemini 3.1 Pro | ✅ 작동 |
| API Key (무료) | 250건 | Flash 모델만 | ❌ 미작동 |
| API Key (유료) | 종량제 | Pro 가능 | ✅ 작동 |
그래서 Plan 모드를 제대로 써보려면 Google 계정 OAuth 로그인이 기본입니다. 일일 1,000건 무료에 Pro 모델 자동 라우팅까지 됩니다. API Key로 무료 사용하는 경우엔 일일 250건인 데다 Flash만 씁니다. 두 조건이 동시에 불리합니다.
CI/CD에서 Plan 모드를 쓰면 생기는 일
💡 공식 문서의 비대화형 실행 섹션을 읽고서야 이 동작이 보였습니다. Plan 모드를 파이프라인에 붙이면 안전하게 계획만 세운다는 가정이 무너집니다.
공식 문서에 “비대화형 실행(Non-interactive execution)” 섹션이 따로 있습니다. 내용이 중요합니다. CI/CD 파이프라인처럼 사람이 없는 환경에서 Gemini CLI를 Plan 모드로 실행하면, 계획 승인 단계가 자동으로 처리됩니다. 여기까지는 납득됩니다. 문제는 다음 줄입니다.
“Plan 모드를 빠져나와 구현을 시작할 때, Gemini CLI는 자동으로 YOLO 모드로 전환됩니다.” (출처: Gemini CLI 공식 문서, Non-interactive execution) YOLO 모드는 사용자 확인 없이 모든 도구를 실행하는 모드입니다. 파일 수정, 명령어 실행이 자동 승인됩니다.
다시 말해, 파이프라인에서 Plan 모드로 시작한 작업이 계획 단계가 끝나면 자동으로 코드 수정 단계로 넘어가고, 거기서는 YOLO 모드로 작동합니다. 안전하게 계획만 세우려고 Plan 모드를 선택했는데, 파이프라인에서는 계획 이후 실행까지 자동으로 이어지는 겁니다. 이 동작은 gemini --approval-mode plan -p "..." 형태로 실행할 때 적용됩니다.
Claude Code Plan 모드와 다른 점
Claude Code에도 Plan 모드(/mode plan)가 있습니다. 둘의 방향은 비슷하지만 실제 동작 방식이 다릅니다. (출처: Shipyard, Claude Code vs Gemini CLI, 2026.01.15)
Gemini CLI Plan 모드는 계획서(.md 파일)를 ~/.gemini/tmp/ 경로에 실제 파일로 씁니다. 세션 데이터는 기본 30일 보관 후 자동 삭제됩니다. 반면 Claude Code의 Plan 모드는 계획을 파일로 떨구지 않고 대화 흐름 안에서 처리합니다. Gemini의 방식이 더 투명하지만, 계획 파일이 프로젝트 외부 경로에 쌓인다는 점을 모르고 있으면 나중에 디스크 용량에서 의외의 상황을 만날 수 있습니다.
모델 품질 면에서 실제 사용 후기들은 엇갈립니다. Claude Code는 에러 로그를 주면 스스로 방향을 수정하는 편이고, Gemini CLI는 구체적인 지시가 없으면 막히거나 작업 일부를 사용자에게 돌려보내는 경향이 있다고 여럿이 보고합니다. 이건 기술적 우열이 아니라 접근 방식의 차이로 보는 게 적절합니다.
실제로 쓸 때 챙겨야 할 설정 3가지
공식 문서 전체를 훑고 나서 정리한 설정 포인트입니다. 발표 내용만 보면 놓치기 쉬운 부분들입니다.
Google OAuth로 로그인하세요. API Key 무료 사용은 Flash 모델에 일일 250건으로 제한됩니다. Plan 모드의 고추론 계획 기능을 제대로 쓰려면 Google 계정 로그인(gemini auth login)이 필요합니다. 일일 1,000건에 Gemini 3.1 Pro 자동 라우팅이 적용됩니다. 현재 세션 사용량은 /stats model로 확인할 수 있습니다.
계획 파일을 프로젝트 안에 두려면 설정이 필요합니다. 기본 저장 경로는 홈 디렉토리 아래 임시 폴더입니다. 팀 프로젝트에서 계획 이력을 공유하거나 버전 관리에 넣으려면 settings.json에서 plan.directory를 프로젝트 내부 경로로 바꾸고, 그 경로에 맞는 정책 파일도 함께 만들어야 합니다.
파이프라인에서 Plan 모드만 실행하고 싶다면 별도로 막아야 합니다. 비대화형 환경에서는 Plan 모드 완료 후 자동으로 YOLO 모드 실행이 이어집니다. 계획 작성까지만 하고 싶다면 훅(AfterTool)을 활용하거나, 구현 단계를 명시적으로 분리해야 합니다. 계획서를 GCS 같은 외부 저장소에 아카이빙하는 훅 예시도 공식 문서에 나와 있습니다.
Q&A
Q. Plan 모드에서 작성된 계획서는 어디에 저장되나요?
기본 저장 경로는 ~/.gemini/tmp/<project>/<session-id>/plans/입니다. 세션 데이터와 함께 30일 기본 보관 후 자동 삭제됩니다. settings.json에서 plan.directory를 설정하면 프로젝트 내부 경로로 변경 가능하지만, 이 경우 자동 삭제가 적용되지 않아 직접 관리해야 합니다.
Q. Plan 모드를 아예 끄고 싶으면 어떻게 하나요?
/settings에서 “Plan”을 검색하면 토글 옵션이 나옵니다. 끄면 Shift+Tab 순환에서 Plan 모드가 빠지고, enter_plan_mode와 exit_plan_mode 도구가 등록 해제됩니다.
Q. MCP 도구를 Plan 모드에서 자동 허용하려면 어떻게 하나요?
~/.gemini/policies/ 경로에 정책 파일을 만들어야 합니다. 읽기 전용 MCP 도구를 일괄 허용하려면 toolAnnotations = { readOnlyHint = true } 규칙을 적용하고 모드를 ["plan"]으로 지정하면 됩니다. 공식 문서 Custom Policies 섹션에 예시 코드가 있습니다.
Q. Conductor 확장이란 무엇이고, 지금 쓸 수 있나요?
Conductor는 Plan 모드와 ask_user를 조합해 대규모 개발 트랙을 관리하는 확장 프로그램입니다. 현재 GitHub(gemini-cli-extensions/conductor)에서 외부 익스텐션으로 설치할 수 있습니다. 구글이 곧 Gemini CLI 빌트인 모드로 통합할 예정이라고 밝혔지만, 시기는 아직 공개되지 않았습니다.
Q. Gemini CLI 전체가 매우 느려지는 버그가 보고됐는데, Plan 모드에도 영향이 있나요?
GitHub 이슈(#22141)에 따르면 Auto 모델 + 브라우저 로그인 환경에서 작은 작업에도 13~14분이 걸리는 사례가 2026년 3월에 보고됐습니다. Auto 모드에서 모델 라우팅이 걸리는 상황으로 추정되며, Plan 모드도 Auto 모델을 사용하므로 같은 환경이라면 동일하게 영향을 받을 수 있습니다. 공식 답변은 아직 나오지 않았습니다.
마치며
Gemini CLI Plan 모드는 방향 자체는 맞습니다. AI 에이전트가 코드를 먼저 뜯어보고 질문하고 계획서를 쓴 뒤에 실행하는 흐름은, 지금까지 너무 많이 경험한 “멋대로 수정 후 후회” 패턴을 실제로 줄여줄 수 있습니다.
다만 “읽기 전용이라 안전하다”는 한 줄 요약이 만드는 오해가 있습니다. API Key 무료 사용자는 계획 단계에 Pro 모델이 쓰이지 않고, 비대화형 파이프라인에서는 계획 완료 후 자동으로 YOLO 모드 실행이 이어집니다. 솔직히 두 조건 모두 공식 문서에 적혀 있는 내용이고, 발표 자료만 훑었으면 몰랐을 겁니다.
당장 써볼 생각이라면 Google OAuth 로그인부터 확인하는 게 먼저입니다. 거기서 출발해야 Plan 모드가 설명대로 작동합니다.
본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. Gemini CLI는 지속적으로 업데이트되는 오픈소스 프로젝트로, 이 글의 내용은 2026.03.11 기준 공식 문서와 발표 자료를 바탕으로 작성됐습니다.
댓글 남기기