Claude Code Agent Teams와 Subagent 차이점: 구조, 비용, 선택 기준

Claude Code에서 일을 여러 에이전트에게 나누는 방법은 하나가 아닙니다. 가장 익숙한 것은 메인 대화가 작업을 맡기고 결과만 돌려받는 **서브에이전트(Subagent)**이고, 여러 Claude 세션이 서로 메시지를 주고받으며 함께 일하는 Agent Teams라는 방법도 있습니다. 이름이 비슷하고 둘 다 “에이전트를 여러 개 띄운다”는 점이 같아서, 어느 쪽을 써야 할지 헷갈리기 쉽습니다.

두 기능의 핵심 차이는 누가 조율하고, 에이전트끼리 직접 대화하는가입니다. 서브에이전트는 메인 대화가 모든 일을 관리하고 결과 요약만 받는 위임 구조이고, Agent Teams는 팀원들이 공유 작업 목록과 메시지로 스스로 조율하는 협업 구조입니다. 이 차이가 토큰 비용과 적합한 작업 종류까지 갈라 놓습니다.

이 글에서는 두 기능이 각각 무엇인지, 공식 문서가 둘을 어떻게 비교하는지, 비용과 제한은 어떤지, 어떤 상황에 무엇을 고르면 되는지를 정리합니다. 내용은 Claude Code 공식 문서(2026-10 기준)를 확인한 것이며, 문서가 자주 바뀌므로 쓰기 전에 최신 문서를 한 번 더 확인하는 편이 좋습니다.

---

1. 서브에이전트

서브에이전트는 특정 유형의 작업을 맡는 전문 AI 어시스턴트입니다. 각자 자기 컨텍스트 창, 커스텀 시스템 프롬프트, 허용된 도구, 독립된 권한을 가지며, 하나의 세션 안에서 일합니다. 검색 결과나 로그, 파일 내용처럼 다시 볼 일 없는 출력이 메인 대화를 채울 때, 그 일을 서브에이전트에게 넘기면 요약만 돌아옵니다.

1-1. 정의 파일

서브에이전트는 YAML 프론트매터가 있는 마크다운 파일로 정의하고, 본문이 시스템 프롬프트가 됩니다. 필수 필드는 name과 description 둘뿐이고, tools, model, permissionMode, isolation 같은 나머지 필드는 선택입니다. 아래는 공식 문서의 예시입니다.

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
 
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

정의 파일은 여러 곳에서 올 수 있고, 이름이 겹치면 우선순위가 높은 쪽이 이깁니다.

순위	위치	범위
1	Managed settings	조직 전체
2	--agents CLI 플래그	현재 세션 (디스크에 저장 안 됨)
3	.claude/agents/	현재 프로젝트
4	~/.claude/agents/	내 모든 프로젝트
5	플러그인의 agents/ 디렉터리	플러그인을 켠 곳

에이전트의 정체성은 파일 경로가 아니라 name 필드에서 나옵니다. 플러그인에서 온 서브에이전트는 hooks, mcpServers, permissionMode 필드가 무시됩니다.

1-2. 호출 방식

• 자동 위임: Claude가 작업 내용과 각 서브에이전트의 description을 맞춰 보고 고릅니다. 설명에 “use proactively” 같은 문구를 넣으면 위임을 유도할 수 있습니다.
• 자연어 지정: “Use the test-runner subagent to fix failing tests”처럼 이름을 들어 요청합니다.
• @-멘션: @agent-<name> 형식으로 부릅니다. 플러그인 에이전트는 @agent-my-plugin:code-reviewer처럼 플러그인 이름이 붙습니다.
• 세션 전체를 서브에이전트로: claude --agent code-reviewer로 시작하면 세션 자체가 그 에이전트로 동작합니다.

내부적으로 서브에이전트를 부르는 도구 이름은 Agent입니다. 예전 글에서 Task 도구라고 부르던 것과 같은 도구이고, 기존 Task(...) 표기는 별칭으로 계속 동작합니다.

1-3. 결과는 요약으로만 돌아옴

서브에이전트는 새 컨텍스트 창으로 시작합니다. 자기 시스템 프롬프트, Claude가 쓴 위임 메시지, CLAUDE.md, git status 스냅숏 같은 것을 받지만 부모의 대화 기록은 보지 못합니다. (대화 전체를 이어받는 fork는 예외입니다.)

일이 끝나면 서브에이전트의 최종 메시지만 메인 대화로 돌아옵니다. 중간에 쓴 도구 호출과 그 결과는 서브에이전트 안에 남습니다. 메인 대화의 컨텍스트가 깨끗하게 유지되는 이유가 이것입니다.

---

2. Agent Teams

Agent Teams는 여러 Claude Code 인스턴스가 하나의 팀으로 일하는 기능입니다. 리드가 팀원을 만들고 일을 나누면, 팀원들은 각자의 컨텍스트 창에서 독립적으로 일하면서 서로 직접 메시지를 주고받습니다. 사용자도 리드를 거치지 않고 아무 팀원에게나 직접 말을 걸 수 있습니다.

2-1. 구성요소

공식 문서의 Architecture 표는 팀을 네 요소로 설명합니다.

구성요소	역할
Team lead	팀원을 만들고 작업을 조율하는 메인 Claude Code 세션
Teammates	각자 맡은 작업을 하는 별도의 Claude Code 인스턴스
Task list	팀원이 가져가서 완료하는 공유 작업 목록
Mailbox	에이전트 사이의 메시지 시스템

• 작업 목록: 작업은 pending, in progress, completed 세 상태를 가지며 작업 간 의존성을 둘 수 있습니다. 미해결 의존성이 있는 작업은 가져갈 수 없고, 가져가기(claim)는 파일 잠금으로 경쟁 상태를 막습니다. 공유 작업 목록은 Task 도구(TaskCreate, TaskList 등)가 있는 에이전트에서 쓰이고, 없는 에이전트는 메시지로만 조율합니다.
• 메일박스: 리드가 모든 팀원에게 이름을 붙이고, 팀원은 그 이름으로 서로에게 메시지를 보냅니다. 전체 공지 기능은 없어서 받는 사람마다 한 번씩 보냅니다. 메시지는 자동으로 전달되므로 리드가 확인하러 다닐 필요가 없습니다.
• 컨텍스트: 팀원은 생성될 때 일반 세션처럼 프로젝트 컨텍스트(CLAUDE.md, MCP 서버, 스킬)를 로드하고 리드가 준 spawn prompt를 받습니다. 리드의 대화 기록은 넘어오지 않습니다.

다른 에이전트가 보낸 메시지는 사용자의 승인으로 취급되지 않습니다. 팀원이 권한 프롬프트를 대신 승인하거나, 거부된 동작을 다른 팀원에게 넘겨 우회할 수는 없습니다.

2-2. 켜는 방법

Agent Teams는 실험 기능이고 기본값은 꺼짐입니다. 환경 변수 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS를 1로 두면 켜집니다. 셸 환경 변수로 줘도 되고, settings.json의 env에 넣어도 됩니다.

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

끄려면 같은 값을 "0"으로 바꿉니다. 이 변수가 없으면 세션 시작 시 팀이 만들어지지 않고, Claude가 팀원을 만들거나 제안하지도 않습니다. 팀원은 대화형 세션에서만 만들어지며, -p(비대화형)와 Agent SDK 세션에서는 만들어지지 않습니다.

켜면 일반 위임의 동작도 바뀝니다

Agent Teams를 켠 대화형 세션의 메인 대화에서 Claude가 서브에이전트를 부르면서 name을 붙이면(Claude가 스스로 붙일 수도 있습니다) 그 서브에이전트가 팀원으로 실행됩니다. 사용자가 팀을 요청하지 않아도 팀이 만들어질 수 있고, Claude Code는 실행 전에 확인을 묻지 않습니다. fork이거나 호출에 isolation을 직접 넘긴 경우는 예외입니다. 서브에이전트 정의의 프론트매터에 isolation을 적어 둬도 이 전환을 막지 못하고, 이때 팀원은 메인 세션의 작업 디렉터리에서 실행된다고 문서가 설명합니다.

2-3. 표시 모드

팀원을 보여 주는 방식은 두 가지입니다.

• In-process: 모든 팀원이 메인 터미널 안에서 실행됩니다. 어떤 터미널에서나 동작하며 기본값입니다. 리드 터미널의 에이전트 패널에서 팀원을 골라 Enter로 대화를 열고, Ctrl+T로 작업 목록을 봅니다.
• Split panes: 팀원마다 자기 창을 가집니다. tmux 또는 iTerm2가 필요합니다.

설정 키 teammateMode로 "in-process", "auto", "tmux", "iterm2" 중 하나를 고르고, 세션 한정으로는 claude --teammate-mode auto 플래그를 씁니다.

---

3. 구조 비교

두 기능의 차이는 그림으로 보면 분명합니다. 서브에이전트는 결과를 메인 대화로 돌려보내고, Agent Teams의 팀원은 작업 목록을 공유하며 서로 직접 메시지를 주고받습니다.

공식 문서(Agent Teams 문서의 “Compare with subagents”)는 둘을 다섯 항목으로 비교합니다. 아래는 그 표를 옮긴 것입니다.

구분	서브에이전트	Agent Teams
컨텍스트	자기 컨텍스트 창, 결과는 호출자에게 돌아감	자기 컨텍스트 창, 완전히 독립
소통	호출자에게 결과를 돌려줌. Claude가 생성할 때 이름을 붙인 서브에이전트는 서로 메시지를 보낼 수도 있음	팀원끼리 직접 메시지
조율	메인 에이전트가 모든 일을 관리	메시지로 스스로 조율, Task 도구가 있는 에이전트는 공유 작업 목록도 사용
적합한 일	결과만 중요한 집중된 작업	논의와 협업이 필요한 복잡한 작업
토큰 비용	낮음: 결과가 요약되어 메인 컨텍스트로 돌아옴	높음: 팀원 하나하나가 별도 Claude 인스턴스

표 바로 아래에 붙은 권고는 다음과 같습니다.

Claude Code 공식 문서, Agent Teams

보고만 하면 되는 빠르고 집중된 작업자가 필요하면 서브에이전트를 쓰세요. 팀원들이 발견한 것을 공유하고, 서로의 주장을 따져 보고, 스스로 조율해야 한다면 Agent Teams를 쓰세요.

같은 문서는 팀을 꾸리기 전에 더 가벼운 방법으로 충분한지 먼저 확인하라고도 안내합니다. 서브에이전트는 한 세션 안에서 일하고, 세션 간 메시지(cross-session messaging)를 쓰면 사용자가 직접 띄운 세션들 사이에서도 발견한 내용을 전달할 수 있기 때문입니다.

---

4. 서브에이전트 간 메시지에 대한 문서의 두 서술

이 부분은 공식 문서에 서술이 두 곳으로 나뉘어 있어서, 두 서술을 그대로 옮기고 문서가 둘을 가르는 조건을 함께 정리합니다.

• 비교표의 서술: “Subagents that Claude named when it spawned them can also message each other.” (Claude가 생성할 때 이름을 붙인 서브에이전트는 서로 메시지를 보낼 수도 있다.) 서브에이전트 문서도 Agent Teams가 켜진 세션에서 Claude가 name으로 이름을 붙이면 메시지로 지칭하고 재개할 수 있으며, SendMessage 도구가 있고 이름 있는 다른 에이전트가 있으면 시작할 때 그 목록(sibling roster)을 받는다고 설명합니다.
• 팀원 전환의 서술: 같은 조건, 즉 Agent Teams가 켜진 대화형 세션의 메인 대화(리드 세션)에서 Claude가 이름을 붙여 서브에이전트를 부르면 그 서브에이전트는 팀원으로 실행된다고 설명합니다. (2-2의 경고)

문서는 두 서술을 조건으로 구분합니다. 서브에이전트에 이름을 붙이는 기능 자체가 Agent Teams를 켠 상태로 시작한 세션에서만 동작하고, 그중 팀원으로 바뀌는 것은 메인 대화에서 name을 붙여 부른 서브에이전트입니다. 이름이 붙어도 서브에이전트로 남는 경우는 다음과 같습니다.

• -p(비대화형) 세션이나 Agent SDK 세션에서 부른 경우
• fork이거나 호출에 isolation을 넘긴 경우

문서의 팀원 전환 규칙은 메인 대화에서 부른 경우로 한정되어 있습니다. 서브에이전트가 이름을 붙여 만든 중첩 서브에이전트가 어떻게 동작하는지는 문서에 나와 있지 않습니다.

확실히 말할 수 있는 것은 기본 설명에서 서브에이전트는 호출자에게 결과를 돌려주는 구조이고, 에이전트끼리 직접 대화하는 것이 설계의 중심인 쪽은 Agent Teams라는 점입니다.

참고로 SendMessage 도구 자체는 Agent Teams를 켜지 않아도 쓰입니다. 끝난 서브에이전트를 이어서 일하게 할 때도 이 도구로 에이전트 ID나 이름을 지정해 재개합니다. 팀이 꼭 필요한 것은 종료 요청이나 계획 승인 같은 팀 프로토콜 메시지입니다.

---

5. 토큰 비용

Agent Teams 문서는 팀이 조율 오버헤드를 더하고, 단일 세션보다 토큰을 훨씬 많이 쓴다고 경고합니다. 팀원마다 독립된 컨텍스트 창을 가지므로 비용은 팀원 수에 따라 늘어납니다. 비용 문서(costs)도 토큰 사용량이 활성 팀원 수와 각 팀원이 실행되는 시간에 따라 커진다고 설명합니다.

"약 7배" 수치의 조건

비용 문서에는 Agent Teams가 표준 세션보다 약 7배 많은 토큰을 쓴다는 문장이 있는데, 이 수치는 팀원이 plan mode로 실행될 때라는 조건이 붙어 있습니다. 측정 방법이나 작업 종류는 문서에 나오지 않으므로 일반적인 배수로 읽으면 안 됩니다. 서브에이전트와 Agent Teams를 직접 비교한 배수는 문서에 없습니다.

비용 문서가 권하는 관리 방법은 다음과 같습니다.

• 팀원에 Sonnet 사용: 팀원 모델을 가볍게 둡니다.
• 팀을 작게: 활성 팀원 수가 곧 비용입니다.
• spawn prompt를 집중해서: 팀원은 CLAUDE.md, MCP 서버, 스킬을 자동으로 로드하고 spawn prompt 내용도 처음부터 컨텍스트에 더해집니다.
• 끝난 팀원은 종료: 활성 팀원은 종료되거나 세션이 끝날 때까지 토큰을 계속 씁니다. “Ask the researcher teammate to shut down”처럼 이름으로 종료를 요청합니다.

서브에이전트는 장황한 출력을 자기 컨텍스트에 남기고 요약만 돌려주므로 메인 컨텍스트 소비를 줄여 줍니다. 다만 비용 문서는 서브에이전트 자신의 요청도 사용량에 포함된다고 밝힙니다. 서브에이전트가 공짜는 아니고, 단순한 작업이면 model: haiku처럼 작은 모델을 지정해 비용을 낮춥니다. 병렬 작업 문서도 “여러 세션이나 서브에이전트를 동시에 돌리면 토큰 사용량이 배로 늘어난다”고 주의를 줍니다.

---

6. 제한과 주의

6-1. Agent Teams

공식 문서의 Limitations에 나온 항목 중 실제로 부딪히기 쉬운 것들입니다.

• 세션당 팀 하나: 한 세션에는 팀이 정확히 하나이고, 팀을 더 만들거나 세션 간에 공유할 수 없습니다.
• 중첩 팀 불가: 팀원은 자기 팀원을 만들 수 없습니다. 팀 관리는 리드만 합니다. 리드를 바꾸거나 다른 팀원을 리드로 올릴 수도 없습니다.
• 같은 파일 동시 편집은 덮어쓰기: 팀원을 worktree로 격리하지 않으므로, 두 팀원이 같은 파일을 고치면 덮어써집니다. 팀원마다 맡을 파일을 나눠야 합니다.
• 세션 재개 불가: /resume, /rewind는 in-process 팀원을 복원하지 않습니다. 재개한 뒤 리드가 이미 없는 팀원에게 메시지를 보내려 할 수 있습니다.
• 작업 상태 지연: 팀원이 완료 표시를 하지 못해 의존 작업이 막히는 경우가 있습니다. 종료도 느릴 수 있습니다.
• 분할 창 미지원 터미널: Split panes는 VS Code 통합 터미널, Windows Terminal, Ghostty에서 지원되지 않습니다. 이 터미널에서는 in-process 모드로 씁니다.
• in-process 팀원의 서브에이전트: 팀원이 서브에이전트를 쓸 수는 있지만 포그라운드로만 실행됩니다. background: true인 정의를 쓰면 오류가 납니다.

6-2. 서브에이전트

• 중첩은 기본 3층: 서브에이전트도 자기 서브에이전트를 만들 수 있고, 메인 대화 아래 최대 3층까지입니다. 환경 변수 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH로 바꾸며, 1이면 중첩을 끕니다. “서브에이전트는 서브에이전트를 만들 수 없다”는 설명은 예전 동작이므로 옛 자료를 볼 때 주의합니다.
• 동시 실행은 기본 20개: CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS로 바꾸고, 넘으면 Concurrent subagent limit reached가 납니다. 세션 전체의 서브에이전트 수에는 한도가 없고, Agent Teams 팀원은 이 한도에 포함되지 않습니다.
• 도구 제한: tools(허용 목록)와 disallowedTools(거부 목록)로 서브에이전트가 쓸 도구를 좁힙니다. disallowedTools가 먼저 적용됩니다.
• 권한 모드 상속: 메인 대화가 bypassPermissions, acceptEdits, auto 모드면 서브에이전트도 그 모드로 실행되어 자기 permissionMode가 무시됩니다.

---

7. 상황별 선택 기준

공식 문서의 비교표, 병렬 작업 문서(Run agents in parallel)의 선택 기준, 서브에이전트 문서의 “Choose between subagents and main conversation”을 상황별로 정리하면 다음과 같습니다.

상황	고를 것	이유
검색, 로그 분석처럼 출력이 장황한 부수 작업	서브에이전트	다시 볼 일 없는 출력이 메인 대화를 채우지 않고 요약만 돌아옴
도구나 권한을 좁혀서 맡기고 싶을 때	서브에이전트	tools, disallowedTools, permissionMode로 제한
조사 → 작성 → 검수처럼 순서가 정해진 작업	서브에이전트	Agent Teams 문서가 순차 작업, 같은 파일 편집, 의존성이 많은 작업에는 단일 세션이나 서브에이전트가 낫다고 안내
여러 관점이 서로의 주장을 따져야 할 때	Agent Teams	리서치·리뷰, 경쟁 가설 디버깅처럼 팀원끼리 발견을 공유하고 반박하는 작업
프런트엔드, 백엔드, 테스트를 나눠 맡을 때	Agent Teams	팀원이 각자 한 조각을 소유하고 공유 작업 목록으로 진행을 맞춤
잦은 왕복과 반복 수정, 작은 수정	둘 다 아님 (메인 대화)	컨텍스트를 많이 공유하고 지연이 중요한 일은 메인 대화가 빠름
여러 작업자가 같은 파일을 고쳐야 할 때	서브에이전트 (또는 메인 대화)	Agent Teams 문서가 같은 파일 편집에는 단일 세션이나 서브에이전트를 권함. 서브에이전트는 isolation: worktree로 각자 사본에서 작업 가능
재사용할 프롬프트를 메인 컨텍스트에서 돌리고 싶을 때	둘 다 아님 (Skills)	별도 에이전트 없이 메인 대화에서 지침을 불러옴

병렬 작업 문서는 이 밖에도 agent view, dynamic workflows, projects를 함께 소개합니다. 선택 질문은 세 가지로 요약됩니다. 누가 조율하는가(한 대화 안에서 Claude가 위임하고 모으면 서브에이전트, Claude가 작업자 그룹을 계획·할당·감독하면 Agent Teams), 작업자끼리 대화해야 하는가, 같은 파일을 건드리는가입니다.

Agent Teams를 쓰기로 했다면 문서는 대부분의 경우 팀원 3~5명으로 시작하고, 팀원당 작업 5~6개 정도가 적당하다고 안내합니다. 처음이라면 코드를 쓰지 않는 리서치나 리뷰부터 해 보라고 권합니다. 서브에이전트 정의는 팀원 타입으로도 재사용할 수 있어서, .claude/agents/에 만들어 둔 정의를 “Spawn a teammate using the security-reviewer agent type”처럼 불러 팀원으로 쓸 수 있습니다. 이때 정의의 skills 필드는 팀원에 적용되지 않습니다.

---

8. 이 블로그의 하네스는 서브에이전트 방식

이 블로그의 글은 조사, 집필, 검수를 나눈 에이전트 구성으로 만듭니다. 저장소의 .claude/agents/에 세 정의가 있습니다.

• blog-researcher: 공식 문서·저장소 README·논문에서 사실을 찾아 출처와 함께 정리하고, 글은 쓰지 않음 (model: sonnet)
• blog-writer: 조사 결과와 필자의 재료로 초안을 쓰고 검수 의견을 반영해 고침 (model: opus)
• blog-reviewer: 사실, 문체 규칙, 비공개 정보, 렌더링을 검수해 문제 목록을 돌려주고, 글을 직접 고치지 않음 (model: opus)

세 파일 모두 name, description, tools, model 프론트매터를 가진 일반적인 서브에이전트 정의입니다. 오케스트레이터 스킬(blog-post-pipeline)이 Agent(subagent_type: "blog-researcher")처럼 하나씩 차례로 호출하고, 앞 단계의 결과 파일을 다음 단계에 넘깁니다.

에이전트끼리 메시지를 주고받지 않고, 메인 대화가 순서대로 결과만 받아 다음 단계로 넘기는 구조이므로 Agent Teams가 아니라 서브에이전트 위임 방식입니다. 3장의 비교표로 보면 “메인 에이전트가 모든 일을 관리”하고 “결과만 중요한” 쪽에 해당하고, 7장의 순차 작업 기준과도 맞습니다. 다만 이 구성으로 쓰는 세션에서 Agent Teams를 켜면, 2-2의 경고처럼 Claude가 이름을 붙여 호출한 서브에이전트가 팀원으로 실행될 수 있다는 점은 알아 둘 필요가 있습니다.

---

함께 읽으면 좋은 글

• Claude Code 플러그인 정리: 플러그인은 서브에이전트 정의를 agents/ 디렉터리에 담아 배포할 수 있습니다. 1장의 정의 파일 우선순위에서 가장 아래에 있는 그 경로입니다.