Main Agent(메인 세션), Subagent(독립 작업자), Agent Team(팀 협업) — 세 가지가 무엇이 다르고, 언제·어떤 비용으로 쓰는지 정리했습니다.
사용자와 직접 대화하는 주 세션. Claude Code를 실행(claude)하는 순간 자동으로 시작되며, 별도 설정이나 정의 파일 없이 생성됩니다. 즉, 사용자가 Claude Code와 대화하고 있는 그 세션 자체가 Main Agent입니다.
.claude/agents/에 정의하는 것은 subagent이며, Main Agent의 정의 파일은 없음PM (사용자) ↔ 지금 이 대화 (Main Agent)
│
├→ doc-manager (subagent) spawn 가능
├→ researcher (subagent) spawn 가능
├→ community (subagent) spawn 가능
└→ ...메인 Agent가 Agent tool로 spawn하는 독립 작업자.
| 남는다 | 사라진다 | |
|---|---|---|
| 요약 결과 | Main 컨텍스트에 반환 | - |
| 생성/수정 파일 | 디스크에 유지 | - |
| 작업 과정 | - | 검색·파일 읽기·시행착오 전부 |
| 대화 이력 | - | 전부 폐기 |
.claude/agents/{name}.md---
name: "Research Agent"
description: "Researches topics and finds external resources"
model: "haiku"
tools:
allow: [WebFetch, WebSearch, Glob, Grep]
deny: [Bash, Write]
disabled: false
scope: project
---| 옵션 | 용도 |
|---|---|
model | subagent 모델 override (sonnet, haiku 등) |
tools.allow / deny | 도구 허용/차단 |
mcpServers | MCP 서버 범위 지정 |
run_in_background | true = 비동기, false = 완료 대기 |
disabled | 삭제 없이 비활성화 |
scope | project / user / plugin |
isolation: "worktree" | 독립 git worktree에서 실행 (파일 충돌 방지) |
| Main Agent | Subagent | |
|---|---|---|
| 컨텍스트 | 대화 전체 누적 | 매번 새로 시작 (spawn prompt만) |
| 가시성 | 사용자가 실시간 확인 | 최종 요약만 반환 |
| 도구 | 전체 접근 | 정의 파일에서 제한 가능 |
| 모델 | 세션 설정 따름 | 개별 override 가능 |
| 수명 | 세션 종료까지 | 작업 완료 시 폐기 |
| spawn 능력 | subagent 생성 가능 | 불가 |
Claude Code의 실험적 기능(기본 비활성)으로, 여러 독립적인 Claude Code 세션이 팀으로 협업하는 구조입니다.
// .claude/settings.json
{
"env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }
}또는 CLI: claude --env CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
| 제약 | 대응 |
|---|---|
| 세션 resume 시 teammate 복원 안 됨 | 새로 spawn |
| 태스크 상태 지연 가능 | 수동 확인 |
| 세션당 1팀, 중첩 불가 | 기존 팀 정리 후 새 팀 |
| Split pane은 tmux/iTerm2 필요 | Windows는 in-process 모드 |
| 토큰 비용 N배 (teammate 수) | 3명 시작 권장 |
| Subagent | Agent Team Teammate | |
|---|---|---|
| 통신 | 메인에게만 반환 | 팀원 간 직접 메시징 |
| 컨텍스트 | 완료 시 폐기 | 독립 세션으로 유지 |
| 조율 | 메인이 순차 관리 | 공유 태스크 + 자율 claim |
| 비용 | 낮음 (요약만 반환) | 높음 (독립 세션) |
| 상호 통신 | 불가 (메인 중개) | 직접 가능 |
Subagent = 직원 1명을 불러서 일 시키고 보고서 받기
Agent Team = 사무실 하나를 새로 차려서 팀 운영하기| 리서치 1건 | 토큰 | 비유 |
|---|---|---|
| Main이 직접 | ~11,500 | 사장님이 직접 조사 |
| Subagent 위임 | ~13,300 (+15%) | 직원 한 명 시켜 보고서 |
| Agent Team | ~15,100 (+31%) | 팀 세팅 + 팀원이 조사 |
Main Agent (Lead) → Opus (판단·조율 품질 중요)
Subagent 일반 → Sonnet (균형)
단순 작업 → Haiku (저렴)| Subagent | Agent Team | |
|---|---|---|
| 비용 | +15~30% | +30~700% |
| 장점 | 메인 컨텍스트 보호, 저렴 | 팀원 간 소통, 병렬 속도 |
| 쓸 때 | 독립 작업 위임 | 협업·토론이 필요할 때 |
6개 Agent(community·researcher·doc-manager·simulator·reviewer·orchestrator)로 같은 일을 두 방식으로 처리한 비교.
PM → Main: "카톡 파일 분석해줘"
Main → community → 요약 반환 → Main
Main → researcher → 요약 반환 → Main
Main → doc-manager → 요약 반환 → Main
Main → reviewer → 요약 반환 → Main
Main → PM 최종 보고
문제: 모든 단계가 Main을 거쳐 순차. community가 끝나야 researcher 시작.community → doc-manager: "필수서류 5종, 마감 2026-04-25"
community → researcher: "주관기관 KEIT, 예산 확인 필요"
researcher → doc-manager: "유사과제 3건, 차별화 전략 반영 권고"
doc-manager → simulator: "기술개발계획서에 시뮬레이션 스펙 필요"
simulator → doc-manager: "ROS2 Humble + Gazebo 스펙 정리 완료"
Subagent였다면 위 5건 모두 Main을 거쳐 5번의 spawn-반환 사이클.| Subagent (현재) | Agent Team | |
|---|---|---|
| 소요 시간 | 순차 5단계 | 병렬 → 빠름 |
| Main 컨텍스트 | 5개 요약 누적 | Lead는 최종 보고만 |
| 중간 소통 | Main 거쳐 5회 중개 | teammate 간 직접 5회 |
| 비용 | 기본 | ~3-4배 |
| PM 개입 | 매 단계 확인 가능 | [확인 필요]만 보고 |