Gemini CLI 서브에이전트: YAML 프론트매터 선언과 독립 컨텍스트 윈도우 설계

2026년 4월 Google이 Gemini CLI에 서브에이전트 기능을 추가하면서 CLI 기반 멀티에이전트 워크플로우의 새로운 기준이 제시됐다. 각 서브에이전트는 독립적인 컨텍스트 윈도우와 커스텀 시스템 지시사항을 보유하며, Markdown+YAML 프론트매터 파일로 선언적으로 정의할 수 있다. Gemini 2.5 Pro 기반 서브에이전트가 제공하는 100만 토큰 이상의 컨텍스트 윈도우는 Claude Code 서브에이전트 대비 약 5배에 달한다.

컨텍스트가 소진되고 오염되는 문제

단일 CLI 세션의 한계는 크게 두 가지다. 첫째, 복잡한 장기 태스크를 처리하다 보면 컨텍스트 윈도우가 소진된다. 방대한 코드베이스를 분석하거나 여러 독립적인 기능을 동시에 개발할 때 메인 에이전트의 컨텍스트가 빠르게 채워진다. 둘째, 모든 중간 단계가 메인 컨텍스트 히스토리에 쌓이면 이후 상호작용의 품질이 저하된다. 불필요한 중간 추론 과정이 다음 요청의 컨텍스트를 오염시키기 때문이다.

서브에이전트는 이 문제를 구조적으로 해결한다. 복잡하고 반복적이거나 대용량 처리가 필요한 태스크를 전문화된 서브에이전트에 위임함으로써, 메인 세션은 빠르고 간결하게 "큰 그림"에 집중할 수 있다. 서브에이전트와의 상호작용은 별도 컨텍스트 루프에서 처리되므로 메인 대화 히스토리에 영향을 주지 않는다.

코드가 아니라 마크다운으로 에이전트를 정의한다

Gemini CLI 서브에이전트의 핵심 설계 원칙 중 하나는 코드가 아닌 선언적 정의다. 서브에이전트는 .md 파일의 YAML 프론트매터로 정의한다.

⤢✕

서브에이전트 파일의 저장 위치는 두 가지다. ~/.gemini/agents/ 디렉토리는 개인 워크플로우용 전역 서브에이전트를 저장한다. .gemini/agents/ 디렉토리는 레포지토리에 커밋하여 팀 전체가 공유할 수 있는 프로젝트 레벨 서브에이전트를 저장한다. Gemini CLI 확장(Extension) 내부의 agents/ 디렉토리를 통해 확장 번들로 서브에이전트를 배포하는 것도 가능하다.

YAML 프론트매터의 주요 필드는 다음과 같다. name 필드는 서브에이전트의 고유 식별자로 @name 형식의 명시적 호출에 사용된다. description 필드는 메인 에이전트가 자동 위임 시 어떤 서브에이전트를 선택할지 판단하는 데 사용하는 텍스트다. tools 필드는 이 서브에이전트가 사용할 수 있는 도구 목록을 제한한다. model과 temperature 필드로 서브에이전트별로 다른 모델과 파라미터를 설정할 수 있다. max_turns는 서브에이전트가 수행할 최대 상호작용 횟수를 제한한다.

마크다운 본문은 그대로 서브에이전트의 시스템 프롬프트가 된다. 복잡한 지시사항, 예제, 제약 조건을 일반 마크다운 문서처럼 작성할 수 있어 프로그래머가 아닌 도메인 전문가도 서브에이전트를 정의할 수 있다.

독립 컨텍스트 윈도우가 만드는 토큰 절약

⤢✕

컨텍스트 격리의 핵심 원칙은 서브에이전트 간 컨텍스트가 완전히 격리된다는 것이다. 서브에이전트 A가 처리하는 내용은 서브에이전트 B의 컨텍스트에 영향을 주지 않는다. 이는 병렬 실행 시 에이전트 간 상호 오염을 방지하고, 각 서브에이전트가 자신의 전문 영역에만 집중할 수 있게 한다.

메인 컨텍스트 보호도 이 격리에서 나온다. 서브에이전트의 모든 중간 처리 과정은 서브에이전트 컨텍스트 내에만 존재한다. 메인 에이전트 세션에는 서브에이전트의 최종 결과 텍스트만 전달된다. 이로써 메인 컨텍스트 윈도우는 서브에이전트 활동으로 채워지지 않고 핵심 오케스트레이션 정보만을 유지한다. 여기서 토큰 절약 효과가 발생한다. 다섯 개 파일을 분석하는 태스크를 다섯 개 서브에이전트에 각각 위임하면, 메인 컨텍스트에는 다섯 개의 분석 결과 요약만 포함된다. 직접 처리 시 필요한 전체 파일 내용이 메인 컨텍스트에 들어오지 않는다.

Gemini 2.5 Pro 기반 서브에이전트는 각각 100만 토큰 이상의 독립 컨텍스트 윈도우를 갖는다. 이는 긴 코드 파일, 상세한 문서, 복잡한 데이터셋을 통째로 서브에이전트 컨텍스트에 로드하여 처리할 수 있음을 의미한다.

병렬로 위임하되, 쓰기 충돌은 조심해야 한다

Gemini CLI는 단일 서브에이전트뿐 아니라 여러 서브에이전트를 동시에 병렬로 실행하는 기능을 지원한다. 다섯 가지 다른 주제를 동시에 조사하거나, 서로 독립적인 코드 컴포넌트를 병렬로 리팩터링하는 작업이 가능하다.

병렬 실행의 주의사항도 명확히 정의되어 있다. 코드 편집이 필요한 태스크에서는 여러 서브에이전트가 동시에 같은 파일을 수정할 때 충돌이 발생할 수 있다. 읽기 전용 태스크는 병렬 실행이 안전하지만, 쓰기 작업이 포함된 태스크는 주의가 필요하다. 병렬 서브에이전트 기능은 2026년 4월 기준 실험적 상태로, 구현에 알려진 버그가 있다.

서브에이전트 호출 방식은 두 가지다. 자동 위임은 메인 에이전트가 태스크를 분석해 적합한 서브에이전트를 자동으로 선택한다. description 필드의 내용이 선택 판단의 기준이 된다. 명시적 호출은 @서브에이전트이름 문법을 프롬프트 맨 앞에 사용하여 특정 서브에이전트를 직접 지정한다.

Claude Code와 다른 지점: 설정 방식과 컨텍스트 크기

두 시스템은 공통 목표(컨텍스트 효율성 및 병렬 실행)를 서로 다른 철학으로 구현한다.

정의 방식에서 갈린다. Claude Code 서브에이전트는 Task 도구를 통해 코드 내에서 동적으로 생성한다. 에이전트의 역할과 지시사항을 코드로 정의하는 프로그래밍 중심 접근이다. Gemini CLI 서브에이전트는 Markdown+YAML 파일로 선언적으로 정의한다. 코드 없이 텍스트 파일만으로 에이전트를 정의하는 설정 중심 접근이다. 컨텍스트 윈도우 크기도 다르다. Claude Code 서브에이전트는 Claude 모델의 기본 컨텍스트 윈도우를 사용한다. Gemini CLI 서브에이전트는 Gemini 2.5 Pro의 100만 토큰 이상 컨텍스트를 활용한다. 대용량 컨텍스트가 필요한 작업에서 Gemini CLI 서브에이전트가 유리하다.

공유 메커니즘은 유사하다. Claude Code는 서브에이전트 결과를 텍스트로만 메인 에이전트에 전달한다. Gemini CLI도 동일하게 결과 텍스트만 메인 컨텍스트에 전달한다. 두 시스템 모두 서브에이전트 내부 상태가 메인 컨텍스트를 오염시키지 않는다는 핵심 원칙을 공유한다. 도구 격리 방식도 다르다. Gemini CLI는 YAML tools 필드로 서브에이전트별 도구 사용을 명시적으로 제한한다. Claude Code는 Task 도구 호출 시 서브에이전트에게 허용할 도구를 파라미터로 전달한다. 팀 공유 측면에서는 Gemini CLI의 .gemini/agents/ 디렉토리를 레포지토리에 커밋하면 팀 전체가 동일한 서브에이전트 정의를 공유한다. Claude Code의 서브에이전트는 CLAUDE.md나 스크립트 파일로 팀에 공유 가능하지만, 표준화된 디렉토리 구조는 없다.

실제로 어떻게 쓰이나

코드 리뷰 병렬화는 @security-reviewer, @performance-reviewer, @style-checker 등 전문화된 서브에이전트를 정의하고, PR 리뷰 시 세 에이전트를 병렬로 실행해 각각 보안·성능·스타일 관점에서 동시에 검토하는 방식이다. 멀티언어 문서 번역은 대용량 문서를 @korean-translator, @japanese-translator, @spanish-translator 서브에이전트에 병렬 위임한다. 각 에이전트는 100만 토큰 컨텍스트 덕분에 매우 긴 문서도 한 번에 처리한다. 레거시 코드 분석은 레거시 코드베이스의 각 모듈을 전담 서브에이전트에 위임해 의존성 분석, 리스크 평가, 리팩터링 제안을 병렬로 수행하는 방식이다. 메인 에이전트는 각 서브에이전트의 결과를 집계해 전체 마이그레이션 전략을 수립한다.

Gemini CLI 서브에이전트는 CLI 기반 AI 에이전트 워크플로우에 구조적 멀티에이전트 아키텍처를 도입한 중요한 이정표다. Markdown+YAML 선언적 정의, 독립 컨텍스트 윈도우, 병렬 실행 지원의 조합은 기술 팀이 재사용 가능하고 버전 관리 가능한 에이전트 라이브러리를 구축하는 기반이 된다. Claude Code 서브에이전트와 비교할 때 프로그래밍 중심 vs 설정 중심, 그리고 컨텍스트 윈도우 크기의 차이가 핵심이다. 병렬 실행의 안정성 문제는 아직 해결 과제로 남아있지만, 읽기 전용 리서치 및 분석 워크플로우에서는 이미 실용적인 생산성 향상을 제공한다.