Claude 에이전트 팀 템플릿 6가지 직접 써보고 정리한 현실적인 구성법

다들 에이전트 팀 좋다고 하잖아요.

“AI 여러 개 동시에 돌리면 개발 속도 3배!” “에이전트 팀으로 혼자서 10인분!”

근데 솔직히 말할게요. 저도 처음에 진짜인가 싶었어요.

Agent Teams 환경변수 켜고 “팀 짜줘”라고 했더니? 에이전트 3개가 서로 같은 파일을 고치고 있더라고요. 충돌 나고, 토큰 날리고, 결과물은 쓰레기.

왜 그랬냐면, 팀 구성을 아무렇게나 했으니까요.

그래서 Anthropic 공식 데모 6종을 전부 분석하고, 커뮤니티 템플릿 수백 개를 뒤지고, 직접 산업별 팀을 구성해봤습니다. 결론부터 말하면 템플릿이 답이에요.

이 글에서 정리한 걸 복붙하면 바로 돌아가는 팀을 만들 수 있습니다.

Claude 에이전트 팀 템플릿 6가지 직접 써보고 정리한 현실적인 구성법 - 공식 데모부터 산업별 팀까지

이 글에서 다루는 내용

Anthropic 공식 데모 6종 분석 (Research Agent, Email Agent 등)
Agent Teams vs Subagent — 언제 뭘 쓰는지
산업별 팀 템플릿 6가지 (코딩, DevOps, 데이터, 콘텐츠, 고객지원, 투자분석)
커뮤니티 오케스트레이터 9개 비교
비용 최적화 실전 팁

에이전트 팀이란?

정의: 여러 Claude 인스턴스가 각자의 컨텍스트 윈도우에서 독립 작업하면서, 공유 태스크 리스트와 직접 메시징으로 협업하는 시스템입니다.

핵심은 **”독립 작업 + 소통”**이에요.

혼자 일하는 AI(서브에이전트)와의 차이점:

항목	Subagent	Agent Teams
컨텍스트	메인과 공유	각자 독립
소통 방식	결과만 반환	직접 메시지 교환
조율	메인이 관리	자체 조율 (공유 태스크)
적합한 작업	단순 위임	복잡한 협업

서브에이전트는 “심부름꾼”이고, Agent Teams는 “팀원”입니다. 이 차이를 모르면 팀을 짜도 심부름만 시키게 돼요.

1단계: 공식 데모 6종 — Anthropic이 보여주는 정답

Anthropic이 직접 만든 claude-agent-sdk-demos에 6개의 레퍼런스 구현이 있습니다. 이게 에이전트 팀의 “정석”이에요.

1-1. Research Agent (Python) — 가장 완성도 높음

Lead Agent (haiku)
├── Researcher x4 (병렬)
│   ├── tools: WebSearch, Write
│   ├── 웹 검색 5-13회씩
│   └── files/research_notes/*.md 저장
│
├── Data Analyst x1
│   ├── tools: Glob, Read, Bash, Write
│   ├── matplotlib으로 차트 생성
│   └── files/charts/*.png 저장
│
└── Report Writer x1
    ├── tools: Skill, Write, Glob, Read, Bash
    ├── reportlab으로 PDF 생성
    └── files/reports/*.pdf 저장

이 구조가 왜 좋냐면요.

역할이 명확하게 분리돼 있어요. Researcher는 검색만, Analyst는 분석만, Writer는 작성만. 서로의 영역을 침범하지 않으니까 충돌이 없습니다.

실행 결과: 7분 54초, 82회 도구 호출, 비용 약 $0.05-0.10 (haiku 기준)

이걸 코드로 보면:

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, AgentDefinition

agents = {
    "researcher": AgentDefinition(
        description="웹 검색으로 리서치 수행",
        tools=["WebSearch", "Write"],
        prompt=researcher_prompt,
        model="haiku"
    ),
    "data-analyst": AgentDefinition(
        description="리서치 노트에서 데이터 추출, 차트 생성",
        tools=["Glob", "Read", "Bash", "Write"],
        prompt=data_analyst_prompt,
        model="haiku"
    ),
    "report-writer": AgentDefinition(
        description="PDF 리포트 생성",
        tools=["Skill", "Write", "Glob", "Read", "Bash"],
        prompt=report_writer_prompt,
        model="haiku"
    )
}

options = ClaudeAgentOptions(
    permission_mode="bypassPermissions",
    system_prompt=lead_agent_prompt,
    allowed_tools=["Task"],
    agents=agents,
    model="haiku"
)

핵심 패턴을 뽑으면:

Lead는 Task 도구만 가지고 있음 (직접 일하지 않고 지시만)
각 에이전트는 필요한 도구만 부여 (Researcher에게 Bash 안 줌)
전원 haiku (비용 최적화)
파일 기반 소통 (files/ 폴더에 결과 저장 → 다음 단계가 읽음)

1-2. Email Agent (TypeScript) — MCP 연동의 정석

Main Agent
├── React + Express 웹앱 (localhost:3000)
├── WebSocket 실시간 통신
│
└── inbox-searcher (서브에이전트)
    ├── tools: Read, Bash, Glob, Grep,
    │         mcp__email__search_inbox,
    │         mcp__email__read_emails
    └── Gmail 쿼리 문법 지원

여기서 배울 점: MCP 서버 도구를 에이전트에 직접 연결할 수 있다는 거예요.

mcp__email__search_inbox처럼 MCP 도구명을 그대로 tools 배열에 넣으면 됩니다. 이걸 응용하면 Slack, GitHub, DB 등 어떤 MCP 서버든 에이전트에 연결할 수 있어요.

1-3. 나머지 4개 데모 요약

데모	언어	핵심
Resume Generator	TypeScript	WebSearch → DOCX 자동 생성
Excel Demo	Electron + Python	AI 기반 스프레드시트 (openpyxl)
Chat App	React + Express	SDK 웹앱 통합 레퍼런스
Hello World V2	TypeScript	Session API (멀티턴, 세션 재개)

Resume Generator는 단일 에이전트지만 “검색 → 생성” 파이프라인의 좋은 예시이고, Hello World V2는 세션 관리(재개, 원샷)의 레퍼런스입니다.

2단계: Agent Teams 활성화 — 3가지 방법

에이전트를 “팀”으로 만들려면 Agent Teams를 켜야 합니다. 2026년 2월 기준 아직 실험 기능이에요.

방법 1: settings.json (권장)

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

방법 2: 마크다운 에이전트 파일

mkdir -p .claude/agents

# .claude/agents/reviewer.md
---
name: reviewer
description: "코드 리뷰 전문가"
tools: Read, Grep, Glob
model: haiku
---
# 리뷰어 지침
코드를 분석하고 개선 사항을 제안합니다.
- 보안 취약점 체크
- 성능 이슈 식별
- 코딩 컨벤션 검증

방법 3: SDK AgentDefinition (코드)

AgentDefinition(
    description="코드 리뷰 전문가",
    tools=["Read", "Grep"],
    prompt="코드를 분석하고 개선 사항을 제안합니다.",
    model="haiku"
)

어떤 방법을 쓸까?

빠르게 시작: 방법 1 (환경변수만)
팀원 역할 정의: 방법 2 (마크다운 파일)
프로덕션 앱: 방법 3 (SDK 코드)

저는 방법 2를 가장 많이 써요. 마크다운 파일이 가장 관리하기 편하거든요.

3단계: 산업별 팀 템플릿 6가지 — 복붙해서 바로 쓰세요

직접 구성하고 테스트해본 팀 구성입니다. 각 팀의 핵심은 **”역할 분리 + 최소 도구”**예요.

템플릿 1: 코딩 팀 (풀스택 개발)

Lead Architect (sonnet)
├── frontend-dev (haiku)
│   ├── tools: Read, Write, Edit, Bash
│   └── React/Vue UI 구현
│
├── backend-dev (haiku)
│   ├── tools: Read, Write, Edit, Bash, Grep
│   └── API/서버 구현
│
├── test-engineer (haiku)
│   ├── tools: Read, Write, Bash, Grep
│   └── 테스트 작성/실행
│
└── code-reviewer (haiku)
    ├── tools: Read, Grep, Glob
    └── 코드 리뷰/품질 검증

왜 이렇게 짰냐면요. frontend와 backend가 서로 다른 폴더에서 작업하니까 충돌이 거의 없어요. test-engineer는 둘 다 끝난 후에 돌리고, reviewer는 읽기 전용이라 어느 시점에서든 돌릴 수 있습니다.

실전 팁: reviewer한테는 Write 도구를 안 줘요. 코드를 직접 고치게 하면 오히려 꼬이거든요. 리뷰 결과만 뱉게 하고, 수정은 해당 개발자가 합니다.

템플릿 2: DevOps 팀

DevOps Lead (sonnet)
├── infra-engineer (haiku)
│   ├── tools: Read, Write, Bash
│   └── Terraform/K8s 인프라
│
├── ci-cd-specialist (haiku)
│   ├── tools: Read, Write, Bash
│   └── 파이프라인 구성
│
├── monitoring-agent (haiku)
│   ├── tools: Read, Bash, Grep
│   └── 로그/메트릭 분석
│
└── security-scanner (haiku)
    ├── tools: Read, Grep, Bash
    └── 취약점 검사

참고: cc-devops-skills에 DevOps 전용 스킬이 잘 정리돼 있습니다.

템플릿 3: 데이터 분석 팀

Data Lead (sonnet)
├── data-collector (haiku)
│   ├── tools: WebSearch, Read, Write, Bash
│   └── 수집/정제
│
├── analyst (haiku)
│   ├── tools: Read, Bash, Write
│   └── 통계/시각화
│
├── ml-engineer (haiku)
│   ├── tools: Read, Bash, Write
│   └── 모델 학습/평가
│
└── report-writer (haiku)
    ├── tools: Read, Write, Glob, Bash
    └── 리포트 생성

Anthropic 공식 Research Agent와 거의 같은 구조예요. collector가 먼저 돌고 → analyst와 ml-engineer가 병렬로 → report-writer가 마무리. 이 순서가 파이프라인의 핵심입니다.

템플릿 4: 콘텐츠 팀 (블로그/마케팅)

Content Lead (sonnet)
├── researcher (haiku)
│   ├── tools: WebSearch, Write
│   └── 트렌드/소스 수집
│
├── writer (sonnet)
│   ├── tools: Read, Write
│   └── 글 작성 (sonnet 권장!)
│
├── editor (haiku)
│   ├── tools: Read, Edit
│   └── 교정/편집
│
├── seo-optimizer (haiku)
│   ├── tools: WebSearch, Read, Edit
│   └── SEO/GEO 최적화
│
└── sns-publisher (haiku)
    ├── tools: Read, Write
    └── SNS 포스트 변환

주의: writer는 sonnet을 쓰세요. haiku로 글을 쓰면 품질이 확 떨어져요. 나머지는 haiku로 충분합니다.

이 구조가 제가 실제로 쓰는 블로그 파이프라인(@blog-pipeline)과 거의 같아요. researcher → writer → editor → seo → sns 순서로 흘러갑니다.

템플릿 5: 고객 지원 팀

Support Lead (sonnet)
├── ticket-classifier (haiku)
│   ├── tools: Read, Write
│   └── 티켓 분류/우선순위
│
├── knowledge-searcher (haiku)
│   ├── tools: Grep, Glob, Read
│   └── FAQ/문서 검색
│
├── response-drafter (haiku)
│   ├── tools: Read, Write
│   └── 답변 초안 작성
│
└── escalation-handler (haiku)
    ├── tools: Read, Write
    └── 에스컬레이션 처리

템플릿 6: 투자 분석 팀

Investment Lead (sonnet)
├── market-scanner (haiku)
│   ├── tools: WebSearch, Write
│   └── 시장 스캔
│
├── fundamental-analyst (haiku)
│   ├── tools: Read, Bash, Write
│   └── 재무 분석 (PER, ROE 등)
│
├── technical-analyst (haiku)
│   ├── tools: Bash, Read, Write
│   └── 기술적 분석 (RSI, MACD)
│
├── news-analyst (haiku)
│   ├── tools: WebSearch, Read, Write
│   └── 뉴스/감성 분석
│
├── risk-manager (haiku)
│   ├── tools: Read, Write
│   └── 리스크 관리/포지션 사이징
│
└── report-generator (haiku)
    ├── tools: Read, Write
    └── 종합 리포트 생성

이게 제가 쓰는 @forge 에이전트의 아키텍처예요. 6명이 각자 분석하고, Investment Lead가 종합 판단을 내립니다. 실제로 AAPL 분석을 이 구조로 돌려보면 기술적 분석(RSI 74.2 과매수)과 펀더멘탈 분석(ROE 152%)이 동시에 나와서 균형 잡힌 판단이 가능합니다.

4단계: 커뮤니티 오케스트레이터 — 안 만들어도 됩니다

직접 팀을 코딩하기 싫으면 이미 만들어진 도구를 쓰면 됩니다.

이름	GitHub Stars	특징
Claude Squad	–	tmux 기반 터미널 관리
Claude Swarm	–	에이전트 스웜 세션
Claude Flow	–	엔터프라이즈급 오케스트레이션
Happy Coder	–	폰/데스크탑에서 에이전트 제어
TSK	–	Rust CLI + Docker 격리
claude-code-by-agents	–	@mentions로 에이전트 조정

그리고 대규모 템플릿 컬렉션:

컬렉션	규모
wshobson/agents	에이전트 112개, 오케스트레이터 16개, 스킬 146개
claude-code-templates	100+ 템플릿, 19.6K 스타
awesome-claude-code	에이전트 13+, 워크플로우 25+, 도구 23+
claude-skills (jeffallan)	풀스택 스킬 65개
Trail of Bits Security	보안 감사 스킬 12+

솔직한 추천: 처음이면 claude-code-templates부터 보세요. npx claude-code-templates로 바로 설치 가능하고, 웹사이트(aitmpl.com)에서 미리보기도 됩니다.

5단계: 비용 최적화 — 이걸 모르면 토큰 폭탄 맞습니다

전략	설명	절약 효과
모델 선택	서브에이전트 haiku, 리드만 sonnet	80-90%
도구 제한	각 에이전트에 필요한 도구만	불필요한 호출 방지
프롬프트 최적화	간결하고 구체적 지시	20-30%
병렬 실행	독립 작업 동시 실행	시간 50% 단축
파일 기반 캐싱	중간 결과 파일 저장 후 재사용	반복 작업 제거

같은 작업을 돌렸을 때 비용 차이:

모델 구성	비용	소요 시간
전원 haiku	$0.05-0.10	~8분
리드 sonnet + 팀원 haiku	$0.20-0.50	~7분
전원 sonnet	$0.50-1.00	~6분
전원 opus	$5-10	~5분

현실적인 추천: 리드만 sonnet, 나머지 haiku. 이게 가성비 최고예요.

실전 경험: Agent Teams를 Pro 플랜에서 전원 Opus로 돌렸더니 5분 만에 토큰이 바닥났습니다. Haiku로 바꾸니까 20-30분은 거뜬했어요.

빠르게 시작하기 — 3가지 방법

방법 A: 공식 데모 클론

git clone https://github.com/anthropics/claude-agent-sdk-demos.git
cd claude-agent-sdk-demos/research-agent
uv sync
ANTHROPIC_API_KEY=your_key uv run python research_agent/agent.py

가장 확실합니다. Anthropic이 만든 거니까 구조가 검증돼 있어요.

방법 B: 마크다운 파일 직접 생성

mkdir -p .claude/agents

cat > .claude/agents/my-researcher.md << 'EOF'
---
name: my-researcher
description: "웹 검색으로 정보를 수집하는 리서처"
tools: WebSearch, Write
model: haiku
---
# 리서처 역할
주어진 주제에 대해 웹 검색으로 정보를 수집합니다.
- 최소 5회 이상 검색
- 결과를 마크다운으로 정리
- files/research/ 폴더에 저장
EOF

5분이면 됩니다. 필요한 역할만 만들어서 바로 테스트.

방법 C: 커뮤니티 템플릿 설치

# 100+ 템플릿 한 번에
npx claude-code-templates

# 112개 에이전트 컬렉션
git clone https://github.com/wshobson/agents.git
cp -r agents/.claude/* .claude/

남이 만든 거 갖다 쓰는 게 제일 빠릅니다.

에이전트 팀 구성할 때 실수하는 3가지

실수 1: 에이전트한테 도구를 너무 많이 줌

# 나쁜 예
researcher:
  tools: WebSearch, Write, Read, Edit, Bash, Grep, Glob

# 좋은 예
researcher:
  tools: WebSearch, Write

도구가 많으면 에이전트가 헤맵니다. 검색 에이전트한테 Bash를 줘봤자 쓸 일이 없어요. 필요한 도구만 최소한으로.

실수 2: 모든 에이전트를 같은 모델로

리드는 판단력이 필요하니까 sonnet, 단순 작업자는 haiku. 전원 opus는 돈 낭비예요.

Addy Osmani의 가이드에서도 “3-4명이 최적”이라고 말합니다. 에이전트가 많아지면 조율 비용이 생산성을 잡아먹거든요.

실수 3: 역할 경계가 불명확

# 나쁜 예: 누가 뭘 하는지 모름
agent-1: "코드 작업합니다"
agent-2: "코드 리뷰합니다"

# 좋은 예: 역할과 영역이 명확
frontend-dev: "src/components/ 폴더의 React 컴포넌트만 담당"
backend-dev: "src/api/ 폴더의 Express 라우트만 담당"

폴더 단위로 영역을 나누면 충돌이 거의 사라집니다.

제가 실제로 쓰는 구성

솔직히 말하면 저는 아직 Agent Teams보다 Task Subagent 방식을 더 많이 씁니다.

Claude Code (메인, opus) → Task subagent (haiku/sonnet 워커)

이유:

스킬/에이전트 개발이 50-100줄 단위라 팀까지 필요 없음
Task Subagent가 가장 안정적이고 비용 효율적
Agent Teams는 대형 프로젝트에서만 진가를 발휘

하지만 블로그 파이프라인(@blog-pipeline)은 사실상 팀 구조예요:

blog-pipeline (리드)
├── WebSearch (리서처 역할)
├── unified-blog-writer (작가 역할)
├── sns-writer (SNS 퍼블리셔 역할)
└── telegram-sender (알림 역할)

스킬을 에이전트처럼 조합하면 형식적인 “팀”은 아니지만 실효성은 같습니다.

FAQ

Q: Agent Teams와 Subagent 중 뭘 먼저 배워야 하나요?

Subagent부터요. Agent Teams는 Subagent의 확장이에요. Task 도구로 워커를 스폰하는 패턴을 먼저 익히고, 그다음에 Teams로 넘어가는 게 학습 곡선이 완만합니다.

Q: 에이전트 팀 몇 명이 적당한가요?

3-4명이 최적입니다. 실전 가이드에서도 “에이전트가 많으면 조율에 시간을 더 쓴다”고 경고해요. 리드 1명 + 워커 2-3명이 가성비 최고.

Q: haiku로 코드 작성해도 괜찮나요?

단순한 코드는 괜찮아요. 하지만 복잡한 로직이나 아키텍처 판단이 필요하면 sonnet을 쓰세요. 리뷰어(읽기 전용)는 haiku로 충분합니다.

Q: 커뮤니티 템플릿 중 어디서 시작하면 좋나요?

claude-code-templates (19.6K 스타)가 가장 접근성이 좋아요. npx claude-code-templates로 바로 설치됩니다.

Q: Agent Teams가 아직 실험 기능인데 프로덕션에 써도 되나요?

2026년 2월 기준 아직 experimental입니다. 개인 프로젝트나 개발 환경에서는 적극 활용하되, 프로덕션 파이프라인에는 안정적인 SDK 방식(AgentDefinition)을 쓰는 게 안전해요.

정리

상황	추천	이유
처음 시작	공식 데모 클론	검증된 구조
소규모 작업	Task Subagent	비용 효율, 안정성
중규모 프로젝트	산업별 템플릿 복붙	역할 분리 검증됨
대규모 프로젝트	Agent Teams + 커뮤니티 도구	자율 조율 필요
빠르게 다양한 팀	npx claude-code-templates	100+ 템플릿 즉시 사용

에이전트 팀은 결국 **”누가 뭘 하고, 뭘 안 하는지”**를 명확히 정의하는 게 전부예요.

템플릿 가져다 쓰세요. 처음부터 만들 필요 없습니다.

참고 자료:

이 글은 직접 에이전트 팀을 구성하고 테스트한 경험을 바탕으로 작성했습니다. 사용 환경에 따라 결과가 다를 수 있습니다.