2.3 협업 실전 샘플 — 기술 통합과 서브에이전트 설정
Claude Code와 Gemini CLI를 실제로 연결하는 세 가지 기술 통합 방법과, 웹리서치를 자동화하는 서브에이전트 구성 및 단계별 실행 전략을 정리한다. 업데이트: 2026-03-20
핵심 요약
| 구분 | 내용 |
|---|---|
| 📖 정의 | Claude Code와 Gemini CLI를 서브에이전트·MCP·Bash 세 가지 방식으로 연결하는 실전 구성 가이드 |
| 💡 핵심 | gemini-researcher 서브에이전트를 설정하면 Claude Code가 웹 리서치 작업을 Gemini에 자동 위임하고 결과를 검증한다 |
| 🎯 대상 | Claude Code와 Gemini를 실제 프로젝트에 함께 사용하려는 개발자 |
| ⚠️ 주의 | 서브에이전트는 현재 대화 기록에 접근할 수 없으므로 CLAUDE.md에 협업 규칙을 명문화하는 것이 필수다 |
문서 탐색
목차
1. 기술적 통합 방법
Claude Code와 Gemini를 실제로 연결하는 방법은 세 가지다. 팀 규모와 자동화 수준에 따라 선택한다.
방법 1: 서브에이전트 패턴 (가장 권장)
Claude Code는 .claude/agents/ 디렉토리에 마크다운 파일로 서브에이전트를 정의한다. Gemini CLI를 래핑한 서브에이전트를 만들면 Claude가 필요 시 자동으로 Gemini에게 작업을 위임한다.
사전 설치:
# 1. Gemini CLI 설치
npm install -g @google/gemini-cli
# 2. 인증 설정
export GEMINI_API_KEY="your-api-key" # API 키 방식 (1,000req/일 무료)
# 또는
gemini auth login # OAuth 방식 (더 관대한 한도)
# 3. 서브에이전트 디렉토리 생성
mkdir -p .claude/agents서브에이전트 파일 기본 구조 (.claude/agents/gemini-analyzer.md):
---
name: gemini-analyzer
description: >
Gemini CLI를 사용하여 대규모 코드베이스 분석, 패턴 탐지,
아키텍처 개요 파악을 수행하는 전문 분석 에이전트.
1M 토큰 컨텍스트 창을 활용한 전체 코드베이스 분석이
필요할 때 자동으로 호출됨.
tools: Bash, Read, Write
---
## 역할
- Claude로부터 분석 요청을 받아 Gemini CLI 명령을 구성하고 실행
- 결과를 정리하여 Claude에게 반환
## 실행 패턴 (Gemini CLI v0.34.0 기준)
\`\`\`bash
gemini --all-files -p "분석 요청 내용" # 전체 코드베이스 분석
gemini --yolo -p "분석 요청 내용" # 비대화형 자동화 모드
gemini --model gemini-2.5-pro -p "..." # Gemini 2.5 Pro
gemini --model gemini-3.1-pro-preview -p "..." # 최신 3.1 Pro (2026-03)
gemini --model gemini-3-flash-preview -p "..." # 빠른 응답용 Flash
\`\`\`
> v0.34.0 (2026-03-17) 변경: 에이전트 스킬 표준 정식 지원, Plan Mode 기본값 설정동작 흐름:
- Claude가 대규모 분석 요청을 받는다
- 서브에이전트 description을 확인하고 자동으로
gemini-analyzer에 위임한다 - Gemini가 1M 토큰 컨텍스트로 분석을 수행한다
- 결과를 Claude에게 반환한다
- Claude가 최종 요약 및 제안을 제공한다
방법 2: MCP 서버 통합
MCP(Model Context Protocol)는 AI 에이전트들이 서로 통신하는 표준 프로토콜이다. Gemini를 MCP 서버로 등록하면 Claude Code가 실시간으로 Gemini에게 요청을 보낼 수 있다.
# Gemini MCP 서버 등록
claude mcp add gemini-server \
--transport http \
--url http://localhost:3000 \
--header "Authorization: Bearer $GEMINI_API_KEY"또는 오픈소스 MCP 서버를 활용한다:
# gemini-cli-orchestrator (dnnyngyen/gemini-cli-orchestrator)
npm install -g gemini-cli-orchestrator
gemini-cli-orchestrator start --port 3000Claude Code UI 안에서 Gemini의 결과를 직접 확인할 수 있어 워크플로우가 매끄럽게 유지된다.
Google Workspace MCP 서버 (2026-03-04 공식 출시):
# Google Workspace MCP 서버를 통해 Claude Code에서 Google 서비스 직접 접근
claude mcp add google-workspace \
--transport http \
--url http://localhost:3001Claude Code가 Google Drive, Docs, Gmail 등에 MCP 프로토콜로 직접 접근할 수 있어, Gemini의 웹 검색과 결합하면 더 강력한 협업이 가능하다.
방법 3: Bash 서브프로세스 직접 호출
가장 단순한 방법으로, Claude Code가 Bash 도구를 통해 Gemini CLI를 직접 실행한다.
# CLAUDE.md에 지시 추가
echo "대규모 코드 분석이 필요할 때는 'gemini --all-files -p [질문]' 명령을 사용하라" >> CLAUDE.mdClaude에게 직접 지시하면 아래와 같이 터미널에서 자동 실행된다:
gemini --all-files -p "프로젝트 전체의 순환 의존성과 미사용 패키지를 분석해줘"2. 웹리서치 전용 서브에이전트 (gemini-researcher)
이것이 Claude + Gemini 협업의 핵심 패턴이다. Gemini가 웹 검색 후 md 파일로 저장 → Claude Code가 내용 검토 및 검증하는 흐름을 서브에이전트로 자동화한다.
2.1 gemini-researcher 서브에이전트 설정
.claude/agents/gemini-researcher.md 파일:
---
name: gemini-researcher
description: >
웹 검색이 필요할 때 Gemini CLI의 Google 검색을 활용해 최신 정보를 수집하고
마크다운 파일로 저장하는 리서치 전문 서브에이전트.
특정 기술 동향, 라이브러리 업데이트, 보안 취약점 CVE,
시장 동향 조사 요청 시 자동 호출됨.
tools: Bash, Write
---
## 역할
Claude Code로부터 리서치 주제를 받아:
1. Gemini CLI의 Google 검색으로 최신 정보 수집
2. 결과를 구조화된 마크다운 파일로 저장
3. 저장된 파일 경로와 핵심 요약을 Claude Code에 반환
## 실행 방법
\`\`\`bash
# research 디렉토리가 없으면 생성
mkdir -p research
# Gemini로 웹 검색 후 md 파일에 저장
gemini --yolo -p \
"다음 주제를 Google에서 검색해서 핵심 내용, 최신 동향, 실전 예시, 출처 URL을 마크다운으로 정리해줘: [주제]" \
> research/[주제-슬러그]-$(date +%Y%m%d).md
# 심층 조사가 필요한 경우 (최신 모델 사용, 2026-03 기준)
gemini --model gemini-3.1-pro-preview --yolo \
-p "[주제]에 대해 2025~2026년 최신 정보를 검색하고 아래 형식으로 정리해줘:
## 핵심 요약 (3줄 이내)
## 주요 변경사항 / 최신 동향
## 실전 활용법
## 참고 자료 (출처 URL 포함)" \
> research/[주제-슬러그]-$(date +%Y%m%d).md
\`\`\`
## 출력 파일 형식
저장되는 md 파일은 아래 형식을 따른다:
\`\`\`markdown
# [주제] 리서치 결과
검색일: [YYYY-MM-DD]
검색 키워드: [...]
## 핵심 요약
## 주요 내용
## 실전 예시 / 코드
## 참고 자료
- [제목](URL) — [날짜]
\`\`\`2.2 실행 흐름
flowchart TD O["Claude Code - 오케스트레이터"] O --> S1["1단계: 리서치 위임\ngemini-researcher 서브에이전트 호출"] S1 --> G1["Gemini CLI Google 검색 실행"] G1 --> G2["최신 정보 + 출처 수집"] G2 --> G3["research/주제-날짜.md 파일 저장"] G3 --> S2["2단계: Claude Code 검증"] S2 --> V1["Read: 저장된 md 파일 확인"] V1 --> V2["출처 URL 유효성 검토"] V2 --> V3["내용의 사실 여부 및 논리 확인"] V3 --> V4["기존 프로젝트 내용과 중복·충돌 체크"] V4 --> V5["추가 조사 요청 또는 최종 결과물에 반영"]
“수 시간이 걸리던 리서치 작업이 10~15분으로 단축된다.” — 365iwebdesign.co.uk 오케스트레이션 가이드
2.3 실전 사용 예시
Claude Code에서 아래와 같이 요청하면 자동으로 동작한다:
"Next.js 15의 Server Actions 최신 변경사항을 조사해서 정리해줘"
Claude Code가 자동으로 수행하는 단계:
gemini-researcher서브에이전트 호출 판단 (description 매칭)- Gemini가 Google 검색으로 최신 Next.js 15 정보 수집
research/nextjs15-server-actions-20260308.md저장- Claude Code가 파일을 읽어서 내용 검증
- 검증된 내용 기반으로 최종 답변 제공
2.4 여러 주제 병렬 리서치
복잡한 기술 문서 작성이나 의사결정이 필요할 때 병렬 리서치 패턴을 적용한다.
# CLAUDE.md에 병렬 리서치 규칙 추가
## 병렬 리서치 패턴
여러 주제를 동시에 조사해야 할 때는 gemini-researcher를 병렬로 호출한다.
각 주제당 별도 md 파일로 저장한 뒤, 모든 파일을 읽고 종합 분석한다.flowchart TD O["Claude Code - 오케스트레이터"] O --> R1["gemini-researcher\nReact vs Vue 2026 비교 최신 동향"] O --> R2["gemini-researcher\n번들러 선택 기준 2026 (Vite, Turbopack)"] O --> R3["gemini-researcher\nTypeScript 5.x 최신 기능"] R1 --> Z["Claude Code\n3개 md 파일 종합 검토 → 기술 스택 권고안 작성"] R2 --> Z R3 --> Z
3. 지금 당장 실행할 수 있는 단계별 전략
Step 1: 최소 설정으로 시작하기 (오늘)
# Gemini CLI 설치 (무료)
npm install -g @google/gemini-cli
# 무료 API 인증 (1,000회/일)
export GEMINI_API_KEY="AIza..."
# 서브에이전트 디렉토리 생성
mkdir -p .claude/agents
# gemini-researcher.md 서브에이전트 파일 생성
# (위의 2.1 내용 참고)이 설정만으로도 Claude Code가 웹 리서치 요청을 자동으로 Gemini에 위임하기 시작한다.
Step 2: CLAUDE.md에 협업 규칙 명문화 (이번 주)
## AI 협업 규칙
### Gemini 담당 (서브에이전트 자동 호출)
- 500개 이상 파일 분석 → gemini-analyzer 서브에이전트
- 웹 리서치 / 최신 정보 수집 → gemini-researcher 서브에이전트
- 초안 코드 생성 (비용 절감)
### Claude Code 담당
- 아키텍처 결정 및 심층 리팩토링
- 복잡한 버그 디버깅
- 보안 취약점 분석
- Gemini 결과물 검토 및 최종 품질 검증4. 2026년 이후 전망
단기 (2026년 내) — 이미 현실화되고 있는 변화
- MCP 생태계 확장: 2026-03-09 MCP 로드맵 발행 — 작업 그룹 중심 전환, 엔터프라이즈 준비(감사 추적, SSO) 추진 중
- 오케스트레이션 플랫폼 경쟁 격화: Amazon Bedrock AgentCore가 2026년 3월 한 달에 5개+ 기능 GA 출시. Google은 Agentspace를 Gemini Enterprise로 통합 (2025-10-09)
- 에이전트 스킬 표준화:
SKILL.md기반 개방형 표준으로 한 번 작성한 스킬을 Claude/Gemini 공통 사용 - 비용 거버넌스 필수화: AI FinOps가 독립 분야로 발전 — 모델 라우팅 + 시맨틱 캐싱 + 단위 경제성 측정이 3대 전략
중기 (2027~2028년)
- 자율 오케스트레이션: 개발자가 작업 목표만 제시하면 AI 시스템이 스스로 최적의 에이전트를 선택하고 조율한다
- 도메인 특화 에이전트 생태계: 보안 전문 AI, 성능 최적화 전문 AI, 법률 검토 AI 등이 Claude-Gemini 협업 파이프라인에 추가된다
- AI 팀 개념 보편화: “개발 팀”이 인간 + AI 에이전트의 혼합 조직으로 표준화된다
장기 (2029년 이후)
- Deloitte는 AI 에이전트 오케스트레이션이 기업 가치 창출의 핵심 인프라가 될 것으로 전망한다
- 단일 AI 사용은 단일 언어로만 프로그래밍하는 것처럼 비효율적인 방식으로 인식될 것이다
5. 최종 메시지
“AI를 어떻게 협업시킬 것인가”를 설계하는 사람이 다음 시대의 핵심 인재다.
Claude Code와 Gemini의 협업은 단순한 도구 조합이 아니다. 이것은 AI를 도구가 아니라 팀원으로 대하는 사고방식의 출발점이다.
gemini-researcher가 웹을 탐색해 md 파일을 만들고, Claude Code가 그 내용을 검토하고 최종 결과물을 완성하는 이 흐름은 인간이 팀원에게 조사를 맡기고 결과를 검토해 의사결정하는 방식과 다르지 않다.
두 AI의 역할 분담을 명확히 하고, 서브에이전트로 연결하고, 각자의 강점을 최대화할 때 단일 AI로는 불가능했던 수준의 생산성, 품질, 비용 효율이 동시에 실현된다.
관련 노트
| 주제 | 시작 문서 |
|---|---|
| AI 협업의 필요성 | 2.1 AI 협업의 필요성 |
| Claude + Gemini 협업 이점 | 2.2 Claude Code와 Gemini 협업 이점 |
| 전체 목차 | AI 도구 가이드 |
문서 탐색
참고 자료
- Claude Code 공식 서브에이전트 문서
- egghead.io: Create a Gemini CLI Powered Subagent in Claude Code
- vibesparking.com: Create a Gemini Subagent in Claude Code (1M Context)
- aicodingtools.blog: Using Gemini CLI as a Subagent for Claude Code
- arsturn.com: Claude Subagents & Gemini: Automate Complex AI Workflows
- 365iwebdesign.co.uk: How to Orchestrate AI CLI Agents with Claude Code
- Deloitte: AI Agent Orchestration - Unlocking Exponential Value
- GitHub: gemini-cli-orchestrator (MCP Server)
- MCP 2026 로드맵 — 2026-03-09
- Gemini CLI v0.34.0 릴리즈 — 2026-03-17
- VS Code February 2026: Google Workspace MCP — 2026-03-04
- AWS: AgentCore Runtime Stateful MCP 지원 — 2026-03
- Cloudfresh: Agentspace → Gemini Enterprise 전환 — 2025-10-09