Gemini CLI 실전 — 대규모 코드베이스 분석과 자동화

처음 보는 거대한 레거시 프로젝트에 투입되었다. 수백 개의 파일, 꼬여있는 의존성... 예전 같으면 구조 파악에만 며칠이 걸렸겠지만, 이제는 커피 한 잔 내리는 시간이면 충분하다. Gemini CLI의 1M 토큰 윈도우가 있기 때문이다.

이번 글에서는 Gemini CLI를 단순한 코딩 어시스턴트가 아닌, 대규모 아키텍처 분석기와 자동화 봇으로 활용하는 실전 테크닉을 다룬다.

1. 1M 토큰의 힘: 프로젝트 통째로 집어삼키기

Gemini CLI의 가장 큰 무기는 단연 100만(1M) 토큰에 달하는 방대한 컨텍스트 윈도우다. 이는 책 수십 권 분량의 텍스트, 즉 일반적인 웹 서비스의 프론트엔드와 백엔드 코드를 한 번에 메모리에 올릴 수 있는 크기다.

실전 시나리오: 낯선 저장소 분석하기

GitHub에서 처음 보는 오픈소스 프로젝트나, 인수인계받은 레거시 코드를 클론 받았다고 가정해보자. 터미널을 열고 바로 이렇게 묻는다.

> 프로젝트 전체를 깊이 읽고, 아키텍처 구조와 데이터 흐름을 markdown 문서로 요약해 줘.
> 특히 인증(Authentication) 처리가 어느 파일에서 시작되어 어떻게 DB까지 도달하는지 추적해 줘.

Gemini CLI는 폴더 트리를 훑고, 주요 파일들을 읽어들인 뒤, 전체적인 청사진을 그려낸다. 컨텍스트가 작았다면 "파일 내용이 너무 길어 다 읽지 못했습니다"라며 포기했겠지만, Gemini는 프로젝트의 맥락을 놓치지 않는다.

실시간 지식 보강: Google Search Grounding

만약 레거시 코드에 내가 모르는 오래된 사내 라이브러리나 낯선 프레임워크가 섞여 있다면? Gemini CLI는 막히지 않는다. 내장된 Google Search Grounding 기능 덕분이다.

명령어 창에 검색을 허용하면, Gemini는 스스로 구글링을 해서 최신 문서를 읽고 답변에 반영한다. 에이전트가 "몰라서 멈추는" 상황을 극적으로 줄여준다.

2. MCP 연동: 에이전트에 손과 발 달아주기

1편에서 설명한 MCP(Model Context Protocol) 를 Gemini CLI에 연결해보자. 코드를 읽는 것을 넘어, 외부 도구를 직접 조작하게 만들 수 있다.

설정 방법

Gemini CLI는 .gemini/settings.json (또는 전역 ~/.gemini/settings.json) 파일을 통해 MCP 서버를 설정한다.

예를 들어, GitHub MCP 서버와 로컬 PostgreSQL 데이터베이스 MCP 서버를 연결한다고 해보자.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:pass@localhost:5432/mydb"]
    }
  }
}

연동 후 워크플로우

설정을 저장하고 CLI를 재시작하면, Gemini는 새로운 도구(Tool)를 획득한다. 이제 이런 명령이 가능해진다.

> 현재 열려있는 JIRA 티켓 번호 PROJ-123의 내용을 읽어오고,
> 그 요구사항에 맞춰서 src/api/user.ts 파일의 쿼리를 수정한 다음,
> 로컬 postgres DB에서 테스트 쿼리를 날려서 정상 작동하는지 확인해 줘.

AI가 기획서(JIRA)를 읽고, 코드(로컬 파일)를 고치고, 테스트(DB 조회)까지 원스톱으로 처리한다. 이것이 MCP가 가져온 진정한 자동화의 힘이다.

3. Headless 모드와 CI/CD 자동화

대화형 프롬프트가 사람을 위한 기능이라면, Headless 모드는 기계와 파이프라인을 위한 기능이다. 대화창을 띄우지 않고, 명령 한 번으로 스크립트처럼 Gemini를 실행할 수 있다.

비대화형 실행 (Headless)

터미널에서 직접 프롬프트를 인자로 넘기면 된다.

gemini --prompt "tests/ 폴더의 모든 실패하는 테스트를 분석하고 고치는 코드를 작성해" --approval-mode=yolo

여기서 --approval-mode=yolo 플래그는 중요한 역할을 한다. CI/CD 환경에서는 사람이 파일 수정을 "y/n"으로 승인해 줄 수 없으므로, 에이전트가 묻지 않고 바로 코드를 수정하도록 허락(Auto-approve)하는 옵션이다.

GitHub Actions에 코드 리뷰 봇 붙이기

이 Headless 모드를 활용하면, 누군가 Pull Request를 올릴 때마다 Gemini가 자동으로 코드를 리뷰하고 코멘트를 남기는 봇을 쉽게 만들 수 있다.

# .github/workflows/gemini-review.yml
name: Gemini AI Code Review

on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Gemini CLI
        run: npm install -g @google/gemini-cli

      - name: Run Review
        env:
          GOOGLE_API_KEY: ${{ secrets.GEMINI_API_KEY }}
          GEMINI_CLI_TRUST_WORKSPACE: "true"
        run: |
          gemini --prompt "이 PR의 diff를 읽고, 잠재적인 버그나 성능 이슈가 있는지 JSON 형식으로 출력해 줘." \
                 --output-format=json > review.json

      # 이후 파이프라인에서 review.json을 파싱하여 PR 코멘트로 자동 등록

이렇게 파이프라인에 통합해 두면, 동료가 코드를 리뷰하기 전에 AI가 먼저 기본적인 1차 방어선을 구축해 준다.

📝 정리

[x] 대규모 분석: 1M 토큰의 이점을 활용해 거대한 레거시 프로젝트의 구조와 맥락을 단숨에 파악한다.
[x] 지식 확장: Google Search Grounding으로 모르는 기술이나 최신 문서도 알아서 검색해 학습한다.
[x] MCP 확장: settings.json에 외부 서버(DB, GitHub 등)를 연결하여 에이전트의 작업 반경을 무한히 넓힌다.
[x] CI/CD 자동화: Headless 모드와 --approval-mode=yolo를 결합하여 자동 코드 리뷰 파이프라인을 구축할 수 있다.

Gemini CLI가 "넓고 포괄적인" 작업에 강하다면, 다음 편에서 소개할 Claude Code는 "좁고 깊은, 정교한 외과 수술" 같은 리팩토링에 특화되어 있다. 4편에서는 현존 최고의 추론 능력을 자랑하는 Claude Code의 세계로 들어가 보자.