Gemini CLI 서브에이전트, Claude Code를 어떻게 따라잡았나

Google이 2026년 4월 Gemini CLI v0.38.1에서 서브에이전트 기능을 공개했다. 개발자는 Markdown과 YAML로 역할·도구·행동 지침을 선언적으로 정의한 전문화 에이전트를 만들고, 복잡한 작업을 독립 컨텍스트 윈도우에서 병렬로 처리하도록 위임할 수 있다. Claude Code가 먼저 서브에이전트를 출시한 지 수 개월 만에 Google이 유사 기능을 내놓으면서 CLI 기반 에이전틱 개발 도구의 멀티에이전트 설계 경쟁이 본격화됐다.

허브-앤-스포크 구조로 컨텍스트를 나눈다

Gemini CLI 서브에이전트는 허브-앤-스포크(Hub-and-Spoke) 아키텍처를 기반으로 한다. 메인 세션이 허브(관리자)가 되고 서브에이전트들이 스포크(전문가)가 된다.

⤢✕

서브에이전트가 호출되면 완전히 깨끗한 컨텍스트 윈도우에서 시작한다. 특정 태스크와 관련 지침만 전달받고, 중간 도구 호출들은 작업 이력에서 삭제된다. 최종 결과만 간결한 요약으로 허브에 반환된다. 이 설계는 메인 세션의 컨텍스트를 깔끔하게 유지하면서 복잡한 서브태스크를 전문화된 에이전트에 위임하는 것을 가능하게 한다.

서브에이전트의 가장 차별화된 특징은 Markdown 파일과 YAML 프론트매터로 에이전트를 선언적으로 정의하는 방식이다.

---
name: code-reviewer
description: 코드 품질, 보안 취약점, 성능 개선 사항을 분석하는 전문 리뷰어
tools:
  - read_file
  - search_files
  - run_shell_command
model: gemini-2.5-pro
temperature: 0.2
---

당신은 시니어 소프트웨어 엔지니어로서 코드 리뷰를 전문으로 합니다.
리뷰 시 다음 기준을 적용합니다:
1. OWASP Top 10 보안 취약점 확인
2. 시간 복잡도와 공간 복잡도 분석
3. 코드 가독성과 유지보수성 평가
4. 테스트 커버리지 갭 식별

모든 발견 사항을 심각도(Critical/High/Medium/Low)로 분류하여 보고합니다.

에이전트 파일은 두 위치에 저장할 수 있다. 프로젝트 수준의 .gemini/agents/*.md는 팀과 공유되고, 사용자 수준의 ~/.gemini/agents/*.md는 개인 전용이다. 버전 관리 시스템에 에이전트 정의를 포함해 팀 전체가 일관된 에이전트를 사용하도록 관리할 수 있다.

병렬 실행은 순차 처리 대비 작업 시간을 크게 단축한다. 순차 실행에서 75초가 걸리던 작업이 병렬 실행에서 30초로 단축됐다. 실제 절감 효과는 태스크 간 의존성 여부와 각 태스크의 독립성에 따라 다르지만, 상호 독립적인 분석·생성 작업에서 병렬화 효과가 극대화된다. Google이 제공하는 내장 서브에이전트에는 범용 보조자, CLI 헬퍼, 코드베이스 조사 에이전트가 포함되며, 사용자는 이를 기반으로 자신만의 전문화 에이전트를 구축할 수 있다.

안전 설계 측면에서 Gemini CLI는 서브에이전트가 다른 서브에이전트를 호출하는 것을 명시적으로 금지한다. 와일드카드로도 불가하다. 무한 루프와 토큰 낭비를 막기 위한 설계로, 서브에이전트 호출 체인의 깊이가 항상 1로 제한되므로 컨텍스트와 비용이 예측 가능해진다. 복잡한 중첩 오케스트레이션이 필요하면 메인 세션에서 여러 서브에이전트를 순서대로 또는 병렬로 호출하는 방식으로 처리해야 한다.

Claude Code와 무엇이 다른가

Claude Code는 Gemini CLI보다 수 개월 앞서 서브에이전트 기능을 출시했다. Gemini CLI v0.38.1의 서브에이전트는 2026년 3월 기준 실험적 상태로, 핵심 기능은 개발 워크플로우에서 동작하지만 권한 상속이 불완전하고 병렬 실행에 알려진 버그가 존재한다. 프로덕션 파이프라인에서의 사용은 아직 권장되지 않는다.

두 도구의 가장 큰 기술적 차이는 컨텍스트 윈도우 크기다. Gemini CLI는 1M 토큰 컨텍스트를 활용해 대규모 코드베이스 전체를 단일 서브에이전트 세션에서 분석할 수 있다. Claude Code는 더 작은 컨텍스트 윈도우로 운영되지만 최대 10개 서브에이전트를 동시에 실행하는 성숙한 병렬화 전략으로 이를 보완한다. 컨텍스트 격리 방식도 다르다. Gemini CLI는 서브에이전트 종료 시 중간 도구 호출을 메인 세션 이력에서 완전히 삭제하는 반면, Claude Code는 서브에이전트 실행 결과와 핵심 컨텍스트를 보존해 후속 에이전트나 사용자가 참조할 수 있게 한다.

항목	Gemini CLI	Claude Code
정의 형식	Markdown + YAML 프론트매터	Markdown + 커스텀 시스템 프롬프트
저장 위치	.gemini/agents/ 또는 ~/.gemini/agents/	.claude/agents/
도구 통합	YAML에서 선언적 명시	동적 도구 접근
버전 관리	파일 기반 (Git 친화적)	파일 기반 (Git 친화적)
팀 공유	프로젝트 레벨 공유 지원	프로젝트 레벨 공유 지원
재귀	금지	제한적 허용
동시 실행 한도	미공개	최대 10개

두 도구 모두 Markdown 파일 기반 에이전트 정의를 채택했다는 공통점이 있다. 에이전트 정의를 코드와 함께 버전 관리하고, 팀 전체에 일관된 에이전트를 배포하며, Pull Request 리뷰 과정에서 에이전트 변경을 검토할 수 있게 하는 접근이다.

오케스트레이션은 어떤 패턴으로 짜는가

멀티에이전트 시스템에서 자주 쓰이는 오케스트레이션 패턴을 정리하면 이렇다.

⤢✕

순차 파이프라인은 코드 분석 → 테스트 생성 → 문서 작성처럼 이전 단계 결과가 다음 단계 입력이 되는 경우에 적합하다. Google ADK의 SequentialAgent 프리미티브가 output_key를 통해 세션 상태를 공유하는 방식이 이 패턴을 구현한다. 오케스트레이터-워커 패턴은 중앙 오케스트레이터가 전체 목표를 이해하고 전문화 워커에게 세부 작업을 위임하는 것으로, Gemini CLI와 Claude Code 모두 이 패턴을 기본으로 채택한다. 병렬 분산-수집 패턴은 독립적인 여러 항목을 동시에 처리하고 결과를 집계하는 것으로, 동일한 서브에이전트 여러 인스턴스를 동시 실행하는 Gemini CLI의 병렬 실행이 이 패턴의 구현이다.

Gemini CLI의 YAML 기반 에이전트 정의에서 배울 수 있는 선언적 설계 원칙도 몇 가지 있다. 각 에이전트는 하나의 명확한 역할을 가져야 한다 — "코드 리뷰 에이전트"는 리뷰만, "테스트 생성 에이전트"는 테스트만 담당한다(단일 책임 원칙). YAML에서 에이전트가 실제로 필요한 도구만 명시적으로 선언해 오작동 범위를 제한한다(도구 최소 권한). 에이전트의 description 필드는 오케스트레이터가 올바른 에이전트를 선택하는 기준이 되므로 명확하고 구체적으로 써야 한다(설명 주도 위임). 각 워커 에이전트를 독립적으로 테스트한 후 오케스트레이터를 구성해야 한다 — 단독 테스트를 통과하지 못하는 에이전트는 통합 환경에서도 실패한다(독립 테스트 가능성). 장기 워크플로우는 단계별로 체크포인트를 설정해, 7단계에서 실패했을 때 처음부터 재시작하는 대신 6단계 결과부터 재개할 수 있도록 한다(체크포인트 설계).

실무에서는 병렬과 순차를 섞어 쓰는 경우가 많다.

⤢✕

코드 분석과 PR 리뷰는 서로 독립적이므로 병렬 실행하고, 테스트 생성은 코드 분석 결과에 의존하므로 분석 완료 후 시작한다.

1M 토큰과 컨텍스트 격리는 상충하지 않는가

Gemini CLI의 1M 토큰 컨텍스트 윈도우는 대규모 코드베이스 분석에서 강점을 발휘한다. 수십만 줄의 코드베이스 전체를 단일 컨텍스트에서 처리할 수 있어 파일 간 관계와 전역적 패턴을 놓치지 않는다. 다만 대규모 컨텍스트는 항상 비용과의 균형이 필요하다. 서브에이전트의 독립 컨텍스트 윈도우는 각 태스크에 필요한 정보만 포함해 효율적인 처리를 가능하게 한다. 중간 결과가 메인 세션 이력에서 삭제되면 메인 컨텍스트가 깔끔하게 유지되어 오케스트레이터의 전체 태스크 관리 능력이 저하되지 않는다.

Gemini CLI의 서브에이전트 기능은 Markdown+YAML 선언적 정의, 독립 컨텍스트 윈도우, 병렬 실행 위에 구축된 CLI 기반 멀티에이전트 오케스트레이션 시스템이다. Claude Code와 비교해 1M 컨텍스트라는 강점이 있으나 실험적 상태와 재귀 금지 제한은 극복해야 할 과제다.

허브-앤-스포크 구조로 컨텍스트를 나눈다

Claude Code와 무엇이 다른가

오케스트레이션은 어떤 패턴으로 짜는가

1M 토큰과 컨텍스트 격리는 상충하지 않는가

Sources

함께 읽기