Gemini CLI Subagents

Gemini CLI subagents란 무엇인가요?

Subagents는 주요 Gemini CLI 세션과 함께 작동하는 전문 전문 에이전트입니다. Gemini CLI에 광범위하거나 복잡한 작업을 부여하면, 메인 에이전트가 가장 적합한 subagent에 특정 하위 작업을 위임하며 오케스트레이터 역할을 합니다.

각 subagent는 고유한 별도의 컨텍스트 윈도우, 맞춤 시스템 지침, 그리고 선별된 도구 세트로 격리된 상태에서 실행됩니다. 여러 도구 호출, 검색, 또는 테스트 실행을 포함할 수 있는 작업이 메인 세션으로 단일 응답으로 통합되어 반환됩니다.

주요 기능

전문 전문가로 위임: Gemini CLI가 대규모 작업을 하위 작업으로 분해하고 대상 subagent로 라우팅합니다.
격리된 실행 환경: 각 subagent가 자체 컨텍스트 윈도우, 시스템 지침, 선별된 도구로 실행되어 메인 세션이 과부하되지 않도록 합니다.
도구 및 컨텍스트 통합: subagent가 수행한 중간 단계가 주 에이전트용 단일 응답으로 통합됩니다.
병렬 subagent 실행: Gemini CLI가 여러 subagent(서로 다른 subagent 또는 동일 subagent의 여러 인스턴스)를 동시에 실행하는 것을 지원합니다.
맞춤 subagent 정의: YAML frontmatter가 포함된 간단한 Markdown 파일로 자신만의 subagent를 만들 수 있습니다.

Gemini CLI subagents 사용 방법

subagent 정의 생성: “frontend-specialist” 예시처럼 name, description, tools, model 등의 필드를 지정하는 YAML frontmatter가 포함된 Markdown 파일(.md)을 사용합니다.
지원 위치에 정의 추가:
- 개인 워크플로우용: ~/.gemini/agents
- 팀/프로젝트 공유용: .gemini/agents
- 확장용: 확장의 agents/ 디렉터리에 에이전트 정의 Markdown 파일 포함.
평소처럼 Gemini CLI 사용: 메인 Gemini CLI 세션에 전체 작업을 제공하면, Gemini CLI가 관련 하위 작업을 처리하기 위해 subagent를 디스패치합니다.
(필요 시) 병렬 작업 실행: 작업이 여러 독립적인 연구/리팩토링/테스트 트랙으로 자연스럽게 분할될 때, Gemini CLI가 여러 subagent를 동시에 디스패치할 수 있습니다.

사용 사례

여러 주제에 걸친 연구: 서로 다른 subagent에 별도의 연구 스레드를 위임하고 병렬로 실행한 후, 메인 세션으로 통합된 출력을 받습니다.
여러 컴포넌트 리팩토링: 리팩토링을 개별 컴포넌트 수준 작업으로 분할하고, 전문 subagent가 각 영역을 처리하도록 하여 주 컨텍스트 윈도우를 채우지 않습니다.
코드 탐색 및 분석: 전문 subagent를 사용해 코드 섹션을 조사하고 요약이나 형식화된 결과를 반환하며, 주 에이전트가 의사결정과 최종 합성을 유지합니다.
테스트 및 검증: 많은 도구 호출을 포함할 수 있는 테스트 관련 단계 시퀀스를 subagent로 오프로드하여 메인 세션이 반응성을 유지합니다.
맞춤 페르소나를 사용한 워크플로우 전용 자동화: 반복 프로젝트 워크플로우에 일관된 접근과 도구 사용을 강제하는 재사용 가능한 전문 에이전트(예: frontend/UI-UX 페르소나)를 만듭니다.

자주 묻는 질문

Subagents는 메인 Gemini CLI 세션과 어떻게 다른가요?
Subagents는 주요 세션과 함께 실행되는 전문 전문 에이전트입니다. 자체 컨텍스트 윈도우, 시스템 지침, 도구로 격리되어 실행된 후 통합된 결과를 반환합니다.

Gemini CLI가 한 번에 여러 subagent를 실행할 수 있나요?
네. Gemini CLI는 병렬 실행을 지원하며, 여러 subagent 또는 동일 subagent의 여러 인스턴스를 동시에 생성할 수 있습니다.

맞춤 subagent는 어떻게 구성하나요?
맞춤 subagent는 YAML frontmatter가 포함된 Markdown 파일(.md)로 정의됩니다. 개인 용도로 ~/.gemini/agents, 프로젝트 수준 공유를 위해 .gemini/agents, 또는 확장의 agents/ 디렉터리에 배치할 수 있습니다.

Subagents가 수행한 중간 작업은 어떻게 되나요?
Subagents는 많은 도구 호출, 파일 검색, 테스트 실행을 수행할 수 있지만, 실행 결과는 주 에이전트로 단일 응답으로 통합됩니다.

Subagents는 자체 도구와 시스템 지침을 가지나요?
네. 각 subagent는 주 세션과 구별되는 선별된 도구 세트와 맞춤 시스템 지침으로 실행됩니다.

대안

위임 없는 단일 에이전트 프롬프팅: Gemini CLI에 모든 작업을 하나의 컨텍스트에서 처리하도록 요청할 수 있습니다. 맞춤 에이전트 설정을 피할 수 있지만, 긴 프롬프트가 필요하거나 컨텍스트 팽창이 발생할 가능성이 높습니다.
수동 워크플로 분할: 각 하위 작업에 대해 별도의 독립 프롬프트를 실행한 후 결과를 직접 병합할 수 있습니다. 위임을 모방할 수 있지만, 오케스트레이션과 통합을 직접 처리해야 합니다.
범용 멀티 에이전트 프레임워크: 도구 또는 프레임워크 기반 멀티 에이전트 접근법도 작업을 전문 역할로 라우팅할 수 있지만, 워크플로와 설정이 Gemini CLI의 서브에이전트 정의 및 격리 모델과 다릅니다.
채팅 기반 에이전트 역할 (비 서브에이전트): 사용 사례가 격리된 병렬 도구 실행보다는 주로 역할 기반 지원이라면, 더 간단한 역할 프롬프팅으로 충분할 수 있으며, 격리와 통합된 하위 작업 출력에 대한 제어가 적습니다.