Gemini CLI 서브에이전트 — 전문 AI 팀을 터미널에서 구성하는 법

Claude Code에 서브에이전트가 있다면, Gemini CLI에도 생겼다.

Google이 Gemini CLI에 서브에이전트(Subagents) 기능을 공식 출시했다. 마크다운 파일 하나로 전문화된 AI 에이전트를 정의하고, @에이전트명 으로 호출하거나 병렬로 실행할 수 있다.

서브에이전트가 필요한 이유

큰 프로젝트를 하나의 AI 세션에서 다루면 문제가 생긴다. 컨텍스트 윈도우가 빠르게 차고, 관련 없는 내용이 섞이면서 답변 품질이 떨어진다.

비유하면 팀 프로젝트를 혼자 처리하는 것과 같다. 디자인, 백엔드, QA를 한 사람이 동시에 담당하면 각 분야의 깊이가 얕아진다. 서브에이전트는 "전문가 팀"을 만드는 방식이다.

각 서브에이전트는 다음을 독립적으로 가진다.

• 전용 컨텍스트 윈도우
• 커스텀 시스템 프롬프트
• 접근 가능한 도구 목록

서브에이전트 정의하기

.gemini/agents/ 디렉토리에 마크다운 파일을 만들면 된다.

---
name: frontend-specialist
description: React, CSS, 번들러 관련 프론트엔드 전문가. 컴포넌트 구조와 성능 최적화에 특화됨.
tools:
  - read_file
  - grep_search
  - glob
  - run_shell_command
---
 
당신은 프론트엔드 전문 엔지니어입니다. React 컴포넌트 설계, CSS 최적화,
번들 크기 분석을 주로 담당합니다. 코드 리뷰 시 접근성과 성능 관점을 항상 포함해주세요.

---
name: security-auditor
description: 보안 취약점 분석 전문가. OWASP Top 10 및 의존성 취약점 스캔에 특화됨.
tools:
  - read_file
  - grep_search
  - run_shell_command
---
 
당신은 보안 감사 전문가입니다. 코드에서 SQL 인젝션, XSS, 취약한 의존성을
우선적으로 확인합니다. 발견한 취약점은 심각도(Critical/High/Medium/Low)로 분류해주세요.

[💡 잠깐! 이 용어는?] 서브에이전트(Subagent): 주 에이전트(오케스트레이터)로부터 특정 작업을 위임받아 독립적으로 처리하는 전문화된 AI 에이전트. 각자의 컨텍스트와 도구를 가진다.

호출 방법

명시적 위임

@에이전트명 으로 특정 에이전트를 직접 호출한다.

@frontend-specialist src/components/ 디렉토리 전체 코드 리뷰해줘

@security-auditor package.json 의존성에서 취약점 스캔해줘

병렬 실행

오케스트레이터가 여러 에이전트를 동시에 실행하도록 지시할 수 있다.

frontend-specialist와 security-auditor를 병렬로 실행해서
각 패키지를 동시에 리뷰해줘

서브에이전트들이 수십 개의 파일을 읽고 분석하는 동안, 주 컨텍스트 윈도우는 깨끗하게 유지된다. 결과만 단일 응답으로 통합되어 돌아온다.

기본 제공 에이전트

Gemini CLI는 세 가지 빌트인 에이전트를 제공한다.

대규모 리포지토리를 처음 파악할 때 @codebase_investigator를 먼저 돌리고, 이후 작업을 나머지 전문 에이전트에게 위임하는 패턴이 효율적이다.

Claude Code와의 비교

Claude Code도 서브에이전트를 지원한다. 구조적 차이를 보면:

방향성은 같다. 각 CLI 도구가 멀티에이전트 패턴을 점점 더 쉽게 쓸 수 있도록 추상화 레이어를 제공하고 있다.

실전 워크플로우 예시

대규모 모노레포에서 신규 API를 추가하는 시나리오를 보자.

1. @codebase_investigator "인증 관련 기존 미들웨어 구조 파악해줘"
   → 주요 파일 목록과 패턴 요약만 반환

2. @backend-specialist "새 /api/orders 엔드포인트 추가, 기존 auth 미들웨어 재사용"
   → 실제 코드 작성

3. @security-auditor와 @test-writer 병렬 실행
   → 보안 검토 + 테스트 작성 동시 진행

각 단계가 독립 컨텍스트로 실행되므로 메인 세션은 상위 계획만 유지한다. 8시간짜리 작업을 한 세션에서 끌고 가도 컨텍스트 오염이 없다.

실전 팁

도구 목록을 최소화한다. 에이전트에게 필요한 도구만 줘야 실수가 줄고 속도가 빠르다. read_file만 줄 수 있는 에이전트에게 run_shell_command까지 줄 필요 없다.

description을 구체적으로 작성한다. 오케스트레이터가 어느 에이전트에게 위임할지 description을 보고 판단한다. "프론트엔드 전문가"보다 "React 컴포넌트 및 번들 최적화 특화"가 더 정확한 라우팅을 만든다.

병렬 실행은 독립적인 작업에만. 서브에이전트 A의 결과가 B에 영향을 미친다면 순차 실행해야 한다. 병렬 실행은 완전히 독립적인 분석 작업에서 진가가 드러난다.

정리

• 서브에이전트는 컨텍스트 오염을 막고 전문성을 높이는 구조다
• .gemini/agents/*.md 파일 하나로 새로운 전문가를 추가할 수 있다
• @에이전트명으로 명시적 위임, 병렬 실행으로 속도를 높인다
• 빌트인 codebase_investigator는 새 프로젝트 탐색에 특히 유용하다

터미널 기반 AI 코딩 도구들이 멀티에이전트 패턴을 표준 기능으로 채택하는 속도가 빠르다. 에이전트 구성 패턴을 지금 익혀두면 어느 도구로 이동해도 같은 사고 체계가 통한다.

참고:

• Google Developers Blog: https://developers.googleblog.com/subagents-have-arrived-in-gemini-cli/