Gemini CLI Plan 모드
IT/AI
Gemini CLI Plan 모드 직접 써봤습니다 — 되는 것과 안 되는 것
결론부터 말씀드리면, Plan 모드는 기본값으로 켜져 있습니다. 설치 직후부터 AI가 코드를 건드리기 전에 먼저 “계획”을 세웁니다. 근데 막상 써보면 이게 생각보다 많이 제한적입니다. 어디서 막히는지, 뭘 할 수 있는지 공식 문서를 직접 확인했습니다.
Plan 모드가 뭔지, 한 줄로 정리하면
Gemini CLI Plan 모드는 AI가 코드를 건드리기 전에 먼저 읽기만 하는 단계입니다. 2026년 3월 11일, 구글이 공식 출시하면서 모든 사용자에게 기본값으로 적용됐습니다. (출처: Google Developers Blog, 2026.03.11)
터미널에서 /plan을 입력하거나, Shift+Tab을 눌러 진입합니다. 이 모드에 들어가면 Gemini CLI는 파일을 읽고, 코드 패턴을 검색하고, 문서를 확인하지만 단 하나의 파일도 수정하지 않습니다. 계획 파일(Markdown)만 예외적으로 기록됩니다.
정확히 말하면 코드베이스 분석 → 질문 → 전략 제안 → 사용자 승인 → 구현 순서입니다. AI가 멋대로 코드를 바꿔놓는 상황을 막기 위해 설계된 구조입니다. 특히 DB 마이그레이션이나 대규모 리팩터링처럼 실수 하나가 치명적인 작업에서 쓰임이 뚜렷합니다.
기본값으로 켜져 있다는 게 실제로 어떤 의미인가
💡 공식 발표문과 실제 사용 흐름을 같이 놓고 보니 이런 차이가 보였습니다. 기존 AI 에이전트는 “실행 후 승인” 방식이었는데, Plan 모드는 전체 흐름의 시작점이 바뀐 겁니다.
많은 분들이 “Plan 모드는 직접 켜야 하는 선택 기능”으로 알고 있을 것 같은데, 사실이 아닙니다. 2026년 3월 11일 이후 설치된 Gemini CLI는 처음부터 Plan 모드가 기본값으로 활성화돼 있습니다. 공식 문서에 “Plan Mode is enabled by default”라고 명시돼 있습니다. (출처: geminicli.com 공식 문서)
즉, 아무 설정도 바꾸지 않은 채로 “새 기능 추가해줘”라고 입력하면, Gemini CLI는 먼저 코드베이스를 읽고, 필요하면 질문을 던지고, Markdown 계획 파일을 작성한 뒤 승인을 기다립니다. 코드를 즉시 수정하지 않습니다. 이 흐름이 싫다면 /settings에서 끄거나, Auto-Edit 모드로 전환해야 합니다.
기본값 전환이 중요한 이유는 하나입니다. 기존에는 “승인해야 적용”이었고, 이제는 “승인해야 시작”입니다. 실행의 기준점이 앞당겨진 것입니다. 데이터베이스 마이그레이션 같은 위험한 작업에서 이 차이가 실질적 사고를 막습니다.
Plan 모드에서 절대 안 되는 것들
읽기 전용이라는 말이 무슨 뜻인지 구체적으로 짚어보겠습니다. Plan 모드에서 허용되는 도구는 공식 문서에 명시돼 있습니다. (출처: geminicli.com/docs/cli/plan-mode)
| 도구 유형 | 허용 여부 | 예시 |
|---|---|---|
| 파일 읽기 | ✅ 가능 | read_file, list_directory, glob |
| 코드 검색 | ✅ 가능 | grep_search, google_web_search |
| 읽기 전용 MCP | ✅ 가능 | github_read_issue, postgres_read_schema |
| 파일 쓰기/수정 | ❌ 불가 | write_file, replace (계획 .md 파일 제외) |
| 셸 명령 실행 | ❌ 불가 | npm test, git commit 등 기본 불가 |
| 계획 Markdown 저장 | ✅ 가능 | ~/.gemini/tmp/…/plans/ 내 .md만 |
셸 명령이 기본적으로 차단된다는 점이 실제로 가장 많이 걸리는 부분입니다. 예를 들어 git status나 git diff는 읽기 전용 성격이지만, Plan 모드 기본 정책에서는 차단됩니다. 이를 허용하려면 ~/.gemini/policies/ 디렉토리에 직접 TOML 파일을 작성해야 합니다. 꽤 번거롭습니다.
또 하나, 읽기 전용 MCP 도구도 기본적으로 사용자 확인이 필요합니다. 자동 승인하려면 별도 정책 파일을 만들어야 합니다. “읽기 전용이니까 알아서 허용되겠지”라는 기대와 다른 부분입니다. 이 부분은 이유를 공개하지 않은 부분입니다.
모델이 자동으로 바뀐다 — 계획할 때와 구현할 때가 다릅니다
💡 대부분의 비교 글이 “Gemini CLI는 어떤 모델을 쓰느냐”에 집중하는데, 정작 Plan 모드에서 모델 자체가 바뀐다는 사실은 거의 언급되지 않습니다.
Gemini CLI에서 자동 모델 설정을 사용하면, Plan 모드 진입 시 자동으로 Gemini 3.1 Pro로 라우팅됩니다. 구조적 결정과 고품질 계획 수립에는 고추론 모델이 필요하다는 이유입니다. 그리고 계획이 승인되면서 구현 단계로 전환될 때는 자동으로 빠른 Flash 모델로 전환됩니다. (출처: geminicli.com 자동 모델 라우팅 문서)
전략은 Pro, 실행은 Flash. 이 전환이 자동이라는 게 핵심입니다. 별도로 모델을 지정하지 않아도 됩니다. 단, 이 자동 전환을 원하지 않으면 settings.json에서 "modelRouting": false로 끄면 됩니다.
이게 실질적으로 중요한 이유는 토큰 비용 때문입니다. Plan 모드에서 Gemini 3.1 Pro를 더 많이 쓴다는 건, 자유 요금제 사용자에게 Pro 할당량 소모가 더 빠를 수 있다는 뜻입니다. 계획 단계에서 복잡한 질의응답을 반복하면 Pro 쿼터가 예상보다 빨리 소진됩니다.
Claude Code와 비교했을 때 진짜 차이
AI 코딩 도구를 비교한 Shipyard 자료(2026.01.15)에서 실제로 써본 내용을 정리했습니다. (출처: shipyard.build, 2026.01.15)
| 항목 | Gemini CLI | Claude Code |
|---|---|---|
| 계획 기능 | Plan 모드 (기본값, 3월 출시) | TodoWrite 기반 내부 계획 |
| 무료 기본 모델 | Gemini 3 Pro 일일 한도 + Flash | 5시간마다 초기화 (Pro $20/월) |
| 컨텍스트 윈도우 | 100만 토큰 | 100만 토큰 |
| 자가 수정 능력 | 상대적으로 약함 (정밀 지시 필요) | 오류 로그 기반 재시도 강함 |
| MCP 연동 | 읽기 전용 MCP Plan 단계 지원 | MCP 전면 지원 |
| 출력 형식 | 단락형 (가독성 낮음) | 목록형 (가독성 높음) |
가장 체감되는 차이는 자가 수정 능력입니다. Claude Code는 오류 로그를 던져주면 다음 시도에서 방향을 바꾸는 편이고, Gemini CLI는 정확한 지시가 없으면 같은 방향으로 반복하는 경향이 있습니다. 초보자보다 아키텍처를 이해하는 개발자에게 Gemini CLI가 더 잘 맞는 이유가 여기 있습니다.
반면 무료 티어 접근성에서는 Gemini CLI가 압도적입니다. Google OAuth로 하루 1,000 요청이 기본 제공됩니다. Claude Code는 무료 플랜이 없고 최소 월 $20입니다.
Conductor 확장, 지금 써야 할까요
Plan 모드와 함께 소개된 Conductor는 복잡한 개발 프로젝트를 트랙(track) 단위로 나눠 관리하는 확장 도구입니다. 단순한 Plan 모드에 비해 훨씬 구조화된 방식으로, 각 트랙마다 스펙 문서와 계획 파일을 저장하고 단계별로 실행합니다. (출처: github.com/gemini-cli-extensions/conductor)
지금 당장 쓸 만한지 솔직히 말하면, 아직 분리된 외부 확장입니다. 구글은 Conductor를 Gemini CLI 내장 모드로 통합할 예정이라고 밝혔지만 출시 날짜는 아직 공개하지 않은 상태입니다. 단순 기능 추가나 단일 프로젝트 수준이라면 기본 Plan 모드로 충분합니다. 반복되는 복잡한 마이그레이션이나 여러 팀이 쓰는 서비스라면 Conductor를 검토해볼 만합니다.
Conductor의 핵심 장점은 대화가 끝나도 계획 파일이 프로젝트 디렉토리에 남는다는 점입니다. 기본 Plan 모드는 세션이 끝나면 계획이 임시 디렉토리에 저장되고 기본 30일 후 자동 삭제됩니다. 팀 단위 협업에서는 이 차이가 큽니다.
자주 묻는 질문
Q. Plan 모드를 끄고 예전처럼 바로 코드 수정하게 할 수 있나요?
네, 가능합니다. /settings 명령에서 “Plan” 항목을 검색해 토글을 끄면 됩니다. 또는 Shift+Tab으로 Auto-Edit 모드로 전환할 수도 있습니다. 이 경우 기존처럼 AI가 직접 파일을 수정합니다.
Q. Plan 모드에서 git 명령어가 안 된다고 하셨는데, 꼭 써야 할 경우는요?
~/.gemini/policies/ 경로에 직접 TOML 정책 파일을 만들면 됩니다. 예를 들어 git status, git diff만 허용하는 정책을 작성하면 Plan 모드에서도 이 두 명령이 실행됩니다. 정책 문서는 공식 사이트에 예시 코드가 포함되어 있습니다.
Q. Plan 모드에서 작성된 계획 파일은 어디에 저장되나요?
기본값은 ~/.gemini/tmp/<project>/<session-id>/plans/입니다. 세션은 기본 30일 후 자동 삭제됩니다. 프로젝트 디렉토리 내 원하는 경로로 바꾸고 싶다면 settings.json에서 "plan.directory"를 지정하면 됩니다.
Q. Plan 모드를 쓰면 토큰 소모가 더 많아지나요?
그렇습니다. 계획 단계에서 Gemini 3.1 Pro가 자동 사용되므로, 복잡한 계획을 세울수록 Pro 쿼터 소모가 빨라집니다. mlearning.substack 자료(2026.01.12)에서도 “Plan 모드는 더 많은 토큰을 쓰지만 비용이 큰 실수를 막는다”고 명시하고 있습니다. 자동 모델 라우팅을 끄면 토큰 소모를 직접 제어할 수 있습니다.
Q. CI/CD 파이프라인에서도 Plan 모드를 쓸 수 있나요?
비대화형(non-interactive) 환경에서는 gemini --approval-mode plan -p "작업 내용" 형식으로 실행합니다. 이 경우 계획과 구현 전환이 자동으로 처리되고, 구현 단계에서는 YOLO 모드로 자동 전환돼 사람의 승인 없이 진행됩니다. 완전 자동화 파이프라인에서 쓸 수 있지만, YOLO 모드의 특성상 사전 테스트를 충분히 한 뒤 적용해야 합니다.
마치며 — 실제로 써보니 이렇습니다
Gemini CLI Plan 모드는 방향이 맞습니다. “AI가 먼저 생각하고, 사람이 승인한 뒤 실행”이라는 흐름은 지금 코딩 에이전트 업계 전체가 가려는 방향이고, 그 걸음을 기본값으로 박아버린 건 용기 있는 결정입니다. 기대했던 것과 달랐던 건 제한의 세밀함입니다. git 명령어 하나 허용하는 데도 정책 파일을 직접 써야 하고, 읽기 전용 MCP도 자동 허용이 아닙니다.
솔직히 말하면, DB 마이그레이션이나 대형 리팩터링처럼 실수가 비싼 작업에는 꽤 쓸 만합니다. 반면 빠르게 프로토타입을 만들거나 단순한 기능 하나를 추가할 때는 Plan 모드가 오히려 흐름을 끊습니다. 상황에 따라 켜고 끄는 법을 익혀두는 게 현실적입니다.
이 부분이 좀 아쉬웠습니다. 기본값으로 켜놓으면서 커스터마이징 진입 장벽은 여전히 높습니다. Conductor가 내장되면 달라질 것 같습니다. 그때 다시 써보고 정리해 오겠습니다.
📎 본 포스팅 참고 자료
본 포스팅은 2026년 3월 23일 기준으로 작성되었습니다. 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. Gemini CLI는 지속적으로 업데이트되는 서비스로, 기재된 기능·제한·가격은 달라질 수 있습니다. 최신 정보는 공식 문서에서 직접 확인하세요.
댓글 남기기