공식 레퍼런스: Gemini CLI 개요 · GEMINI.md 컨텍스트 · 토큰 캐싱 · Sub-agents
학습 경로
- Gemini CLI 시작하기 — 설치, 인증, 메모리 기초
- 100만 토큰의 장점 — 전체 코드베이스로 작업하기 — 저장소 단위 분석을 낭비 없이 ← 현재 문서
- Gemini Extensions & MCP — 커스텀 워크플로 만들기 — 명령, MCP, 스킬 패키징
- Gemini CLI MCP 연동 — 외부 도구와 데이터 연결하기
- Trusted Folders, Sandboxing, 그리고 Restore — 신뢰, 격리, 복구
- Gemini Task Decomposition — 복잡한 작업을 성공적으로 완수하기
- Gemini CLI Headless Automation — 스크립트, CI, 구조화 출력
- Gemini Git Worktrees — 병렬 작업 최적화
- 서브 에이전트와 스킬 오케스트레이션 — 위임과 전문가 워크플로
- GEMINI.md Mastery — 계층적 컨텍스트 설계
- Gemini 첫날 안전 루프
- Multi-Agent Orchestration — 서브 에이전트와 스킬 조합
- Gemini 주간 단위 딜리버리 플레이북
- Gemini GitHub Actions — CI 자동화와 리뷰
- Gemini 고위험 변경 통제 모델
- Gemini Effective Prompting — 100만 토큰을 지배하는 프롬프팅
- Gemini 운영 매뉴얼 — 팀 단위 CLI 딜리버리 리듬
- Gemini Hooks Automation — 로컬 자동화의 방패
- Gemini 사고 복구 플레이북
- Mid-size Refactor Playbook — 중규모 리팩터링
- Gemini 사고 후 하드닝 루프
- Gemini 카오스 복원력 드릴
- Human-Agent Handoffs — 인간과 AI의 릴레이
- Ralph Persistence Loops — 끝까지 물고 늘어지는 자가 치유
- Gemini 복원력 지표와 SLO
- Release Readiness Automation — 배포 자동화
- ADR Automation — 아키텍처 결정 기록 자동화
이 문서에서 참고한 공식 문서
GEMINI.md로 반복 지시를 줄이는 방법 — GEMINI.md 컨텍스트- 토큰 캐싱이 언제 적용되는지와 인증 경로의 중요성 — 토큰 캐싱
- 넓은 아키텍처 탐색에 sub-agent를 쓰는 방식 — Sub-agents
100만 토큰 자체보다 중요한 건 쓰는 방식이다
Gemini CLI의 큰 컨텍스트는 실제로 강력합니다. 작은 컨텍스트 도구가 자주 놓치는 저장소 단위 질문을 한 번에 다룰 수 있게 해 주기 때문입니다.
예를 들어 이런 질문이 쉬워집니다.
- 수정 전에 저장소 전체 구조를 먼저 그리기
src, 문서, 설정, 로케일 파일을 함께 보고 판단하기- 멀리 떨어진 파일 사이의 패턴을 한 세션에서 비교하기
- 상위 아키텍처 맥락을 유지한 채 세부 파일을 읽기
하지만 실전 베스트 프랙티스는 “매번 repo 전체를 넣어라”가 아닙니다. 큰 창은 더 좋은 지도를 만드는 데 쓰고, 그다음부터는 의도적으로 좁혀 가는 게 핵심입니다.
broad → narrow → delegate 루프를 습관으로 만들자
가장 안정적인 패턴은 아래 세 단계입니다.
1) broad pass
먼저 저장소 단위 질문으로 전역 지도를 그립니다.
gemini "@src @content @messages 이 앱의 콘텐츠 아키텍처, 로케일 전략, 유지보수 리스크를 정리해줘"이 단계는 구현 요청이 아닙니다. 구조 파악 요청입니다.
2) narrow pass
지도 초안이 생기면 위험한 영역만 좁혀서 봅니다.
- slug 해석을 실제로 누가 담당하는가?
- frontmatter drift는 어디서 페이지를 깨뜨리는가?
- article card를 렌더링하는 핵심 컴포넌트는 무엇인가?
큰 컨텍스트의 장점은 여기서 드러납니다. Gemini가 전체 구조를 이미 기억한 상태에서 로컬 결정을 내릴 수 있습니다.
3) delegate
그래도 탐색 범위가 넓으면 메인 세션을 태우지 말고 codebase_investigator 같은 sub-agent에 넘깁니다. 넓고 시끄러운 검색을 메인 대화 이력 밖으로 밀어내는 것이죠.
큰 컨텍스트라고 해서 타겟팅이 불필요해지지는 않는다
1M 토큰이 있다고 해서 아무 파일이나 다 읽으면 오히려 손해입니다.
- 응답 지연이 커지고
- 비용이 늘고
- 답이 산만해지고
- 중요하지 않은 파일에 주의가 분산됩니다
그래서 여전히 공식 도구 설계가 중요합니다. @ 포함 범위를 신중하게 고르고, 안정적인 규칙은 GEMINI.md로 빼고, 넓은 탐색은 sub-agent에 맡기는 편이 좋습니다.
GEMINI.md는 반복 프롬프트를 줄이는 최고의 레버리지다
큰 컨텍스트의 가치를 오래 유지하려면, 세션마다 반복되는 규칙을 컨텍스트 파일로 옮겨야 합니다.
예를 들면:
- locale parity 규칙
- 콘텐츠 톤 규칙
- frontmatter 불변 조건
- "MDX 수정 후 링크 검증 필수" 같은 운영 규칙
- 저장소 고유 용어와 명령
이렇게 하면 두 가지 효과가 동시에 생깁니다.
- 매 세션 프롬프트 길이가 줄어든다
- 서로 다른 작업에서도 일관성이 생긴다
안정적인 규칙일수록 ad-hoc 프롬프트보다 GEMINI.md에 있는 편이 낫습니다.
토큰 캐싱은 큰 컨텍스트의 경제성을 바꾼다
공식 문서는 토큰 캐싱이 인증 경로와 연결된다고 분명히 설명합니다. 즉 API key / Vertex 기반 인증일수록 큰 컨텍스트 워크플로를 반복적으로 돌릴 때 비용 구조가 훨씬 좋아집니다.
같은 아키텍처 감사 작업을 CI나 주기 점검으로 반복할 계획이라면, 캐싱이 가능한 인증 경로를 쓰는 것만으로도 "흥미로운 실험"이 아니라 운영 가능한 루틴이 됩니다.
큰 컨텍스트와 잘 맞는 프롬프트 형태
좋은 예: 구조 질문
@src @content @messages
MDX frontmatter가 페이지 렌더링과 SEO까지 어떻게 흐르는지 설명해줘.좋은 예: 영향도 분석
@src @content @package.json
콘텐츠 네비게이션을 바꾸려 한다. routes, loaders, UI, localization 중 어디가 영향을 받는지 정리해줘.나쁜 예: 총체적이고 모호한 요청
전부 읽고 중요한 걸 말해줘.나쁜 예는 판단 기준을 모델이 추측하게 만듭니다. 좋은 예는 어떤 렌즈로 읽어야 하는지 먼저 정해 줍니다.
큰 창이 가장 빛나는 순간
다음처럼 레이어를 가로지르는 작업에서 특히 효과가 큽니다.
- content + routing
- localization + SEO
- docs + generated artifacts
- scripts + repo structure
- architecture + implementation risk
그래서 Gemini CLI는 코드만 있는 저장소보다, 코드·콘텐츠·운영이 섞인 중대형 저장소에서 더 인상적인 경우가 많습니다.
반대로 굳이 전체 저장소를 읽을 필요가 없는 일
- 기사 제목 하나 바꾸기
- 오타 하나 수정하기
- 컴포넌트 클래스 한 줄 고치기
- 플래그 하나만 확인하기
이런 작은 작업은 여전히 좁은 프롬프트가 더 빠르고 명확합니다.
다음에 읽으면 좋은 글
- 큰 조사 작업을 안전하게 실행하는 법은 Trusted Folders, Sandboxing, 그리고 Restore
- 넓은 탐색을 위임하는 법은 서브 에이전트와 스킬 오케스트레이션