Claude Agent Team을 효과적으로 설계, 구성, 운영하기 위한 실전 가이드
이 문서는 여러 Agent가 협력하여 복잡한 작업을 수행하는 Team을 구축하는 방법을 다룹니다. 개별 Agent의 기본 개념은 Claude Agent 완전 가이드를 먼저 참조하세요.
이 가이드의 목적: Agent Team 구성 방법론, 역할 정의, 실전 시나리오, Coordination 전략을 제공합니다.
Agent Team은 공동 목표를 달성하기 위해 협력하는 여러 전문화된 Agent의 집합입니다.
| 특징 | 단일 Agent | Agent Team |
|---|---|---|
| 복잡도 | 단순~중간 작업 | 복잡한 다단계 작업 |
| 속도 | 순차 실행 | 병렬 실행 가능 (최대 5배) |
| 전문성 | 범용 | 역할별 전문화 |
| 적합 작업 | 파일 1-3개 수정 | 전체 프로젝트 개발 |
| 관리 복잡도 | 낮음 | 높음 (조율 필요) |
✅ Team 사용이 적합한 경우:
❌ 단일 Agent가 적합한 경우:
def recommend_team_size(task_complexity, file_count, estimated_hours):
"""작업에 맞는 Team 크기 추천"""
# 단순 작업
if file_count <= 3 and estimated_hours <= 2:
return 1 # 단일 Agent
# 소규모 Team (2-3명)
if file_count <= 10 or estimated_hours <= 8:
return 2 if task_complexity == "medium" else 3
# 중규모 Team (4-5명)
if file_count <= 30 or estimated_hours <= 24:
return 4 if task_complexity == "medium" else 5
# 대규모 Team (6-10명)
if file_count <= 100 or estimated_hours <= 72:
return min(6 + file_count // 20, 10)
# 매우 큰 프로젝트
return 10 # 최대 권장 크기
구성 예시:
적합 작업:
예상 완료 시간: 4-8시간
구성 예시:
적합 작업:
예상 완료 시간: 1-3일
구성 예시:
적합 작업:
예상 완료 시간: 3-7일
상세한 역할 정의는 Part 4: Multi-Agent 시스템을 참조하세요.
책임:
소유 파일:
docs/architecture/docs/ADR/ (Architecture Decision Records)책임:
소유 파일:
src/backend/**src/api/**tests/backend/**책임:
소유 파일:
src/frontend/**src/components/**tests/e2e/**책임:
소유 파일:
migrations/**schema/**database/**책임:
소유 파일:
tests/**e2e/**fixtures/**책임:
소유 파일:
src/auth/**src/security/**security-tests/**책임:
소유 파일:
.github/workflows/**infrastructure/**k8s/**개념: 기술 영역별로 팀원 배치
예시: 풀스택 웹 애플리케이션
Team = {
"frontend": Frontend Developer,
"backend": Backend Developer,
"database": Database Specialist,
"testing": Test Engineer
}
장점:
단점:
개념: 기능 단위로 팀원 배치
예시: E-commerce 플랫폼
Team = {
"auth-feature": Full-stack Developer (인증 기능 전담),
"payment-feature": Full-stack Developer (결제 기능 전담),
"product-catalog": Full-stack Developer (상품 카탈로그 전담)
}
장점:
단점:
개념: 아키텍처 계층별로 팀원 배치
예시: 3-tier 아키텍처
Team = {
"presentation-layer": Frontend Developer,
"business-layer": Backend Developer,
"data-layer": Database Specialist
}
장점:
단점:
프로젝트: E-commerce 플랫폼의 백엔드 REST API 구축
요구사항:
Team 구성 (5명):
team = {
"backend-architect": {
"role": "Backend Architect",
"responsibilities": [
"API 설계 (OpenAPI spec)",
"데이터베이스 스키마 설계",
"마이크로서비스 아키텍처 정의"
],
"owned_files": [
"docs/architecture/**",
"docs/api-spec.yaml"
]
},
"auth-api-developer": {
"role": "Backend Developer (Auth)",
"responsibilities": [
"JWT 기반 인증 구현",
"Role-based 권한 관리",
"OAuth 2.0 통합"
],
"owned_files": [
"src/auth/**",
"tests/auth/**"
],
"depends_on": ["backend-architect"]
},
# ... 나머지 팀원
}
실행 계획:
# Phase 1: Architecture (Sequential - 2시간)
await backend_architect.design_system()
# Phase 2: Core Implementation (Concurrent - 8시간)
await asyncio.gather(
auth_api_developer.implement(),
catalog_api_developer.implement(),
database_specialist.implement_schema()
)
# Phase 3: Order System (Sequential - 6시간)
await order_api_developer.implement()
# Phase 4: Testing (Concurrent - 4시간)
await asyncio.gather(
test_engineer.integration_tests(),
test_engineer.performance_tests()
)
# Total: ~20시간 (단일 Agent 대비 3-4일 절약)
프로젝트: 실시간 분석 대시보드 (Frontend + Backend)
요구사항:
Team 구성 (6명):
예상 완료 시간: ~24시간
프로젝트: Monolith → Microservices 마이그레이션
요구사항:
Team 구성 (8명):
예상 완료 시간: ~60시간 (2-3주 → 3-4일로 단축)
구조:
Coordinator
/ | | \
A B C D
특징:
적합:
구조:
A ←→ B
↕ ↕
C ←→ D
특징:
적합:
구조:
Lead
/ \
Senior Senior
/ \ / \
J1 J2 J3 J4
특징:
적합:
개념: Coordinator가 팀원에게 작업 할당
장점:
단점:
개념: 팀원이 Task Board에서 작업 선택
장점:
단점:
개념: 중요 작업은 Push, 나머지는 Pull
권장: 대부분의 경우 Hybrid 전략이 최적
사용 시점:
사용 시점:
주의: Broadcast는 비용이 높습니다. 꼭 필요한 경우에만 사용하세요.
사용 시점:
증상:
해결책: 작업 재분배 (Load Balancing)
증상:
해결책: API 스펙 먼저 완성하여 병렬 작업 가능하게 만들기
증상:
해결책: 매일 증분 통합 (Continuous Integration)
증상:
해결책: Pair Programming으로 스킬 전수
요구사항 변경 시:
프로젝트 완료 후:
- [ ] 프로젝트 복잡도 분석 완료
- [ ] 적정 팀 크기 결정
- [ ] 필요한 역할 식별
- [ ] 각 역할별 System Prompt 작성
- [ ] 파일 소유권 명확히 분배
- [ ] Coordination 패턴 선택
- [ ] Task 할당 전략 수립
- [ ] 커뮤니케이션 프로토콜 정의
- [ ] 병목 모니터링 계획
- [ ] 팀 생명주기 관리 계획
문서 버전: 1.0
최종 업데이트: 2026-02-13
기반: 실전 프로젝트 경험 및 베스트 프랙티스