서브에이전트만으로 부족한 순간
서브에이전트는 메인 에이전트가 하위 작업을 위임하고 결과를 수집하는 구조다. 대부분의 작업에서는 이것으로 충분하다. 그런데 작업 규모가 커지면 한계가 보이기 시작한다.
서브에이전트끼리는 직접 대화할 수 없다. 프론트엔드를 수정하는 에이전트가 “API 응답 형식이 바뀌었는데?”라고 백엔드 담당 에이전트에게 물어볼 방법이 없다. 반드시 메인 에이전트를 거쳐야 한다. 메인 에이전트 하나가 모든 위임과 조율을 떠안으면, 그 자체가 병목이 된다. 세션 하나의 컨텍스트 윈도우 안에서 모든 것이 돌아가므로, 작업이 커질수록 메인 에이전트의 부담도 비례해서 늘어난다.
Agent Teams는 이 경계를 넘는다. 여러 Claude Code 인스턴스가 각자 독립된 세션으로 돌아가면서, 공유 태스크 리스트와 메시지 시스템으로 협업하는 구조다.
Agent Teams는 실험적 기능이다. 2026년 3월 기준 Claude Code v2.1.32 이상에서 사용할 수 있으며, 기본적으로 비활성화되어 있다. API나 동작 방식이 변경될 수 있다.
서브에이전트와 에이전트 팀은 무엇이 다른가
둘 다 “작업을 나눈다”는 점은 같지만, 구조가 근본적으로 다르다.
| 항목 | 서브에이전트 | 에이전트 팀 |
|---|---|---|
| 세션 범위 | 메인 세션 안에서 실행 | 각 팀원이 독립 세션 |
| 통신 | 메인에게만 결과 반환 | 팀원 간 직접 메시지, 브로드캐스트 |
| 태스크 관리 | 메인이 직접 위임 | 공유 태스크 리스트로 자율 할당 |
| 컨텍스트 | 메인 윈도우에 종속 | 각자 독립된 윈도우 |
| 활성화 | 기본 탑재 | 실험 기능, 별도 활성화 필요 |
서브에이전트가 “한 사람이 여러 일을 번갈아 하는” 모델이라면, 에이전트 팀은 “여러 사람이 각자 맡은 일을 하면서 필요할 때 대화하는” 모델이다.
에이전트 팀의 구조
팀 리드와 팀원
에이전트 팀은 팀 리드(Team Lead)와 팀원(Teammate)으로 구성된다.
팀 리드는 팀을 생성하고 팀원을 추가하는 세션이다. 작업을 분배하고, 팀원의 상태를 확인하고, 결과를 종합하는 조율 역할을 한다. 팀 리드가 곧 사용자가 직접 대화하는 Claude Code 세션이다.
팀원은 리드가 생성한 독립 Claude Code 인스턴스다. 인원수에 하드 리밋은 없지만, 조율 오버헤드와 토큰 비용을 고려하면 3~5명이 현실적이다. 각 팀원은 자기만의 컨텍스트 윈도우, 도구 접근 권한, 작업 영역을 갖는다. 프로젝트 맥락(CLAUDE.md, MCP 서버)은 자동으로 공유되지만, 리드의 대화 히스토리는 넘어가지 않는다. 팀원에게 전달해야 할 작업 맥락이 있다면 태스크 설명이나 메시지에 명시적으로 포함해야 한다.
팀 리드는 세션 수명 동안 고정된다. 리드를 다른 팀원으로 교체하거나, 팀원을 리드로 승격시키는 것은 지원하지 않는다.
태스크 리스트
에이전트 팀의 협업 중심에는 공유 태스크 리스트가 있다. 태스크는 세 가지 상태를 거친다.
pending → in progress → completed
리드가 태스크를 만들어 특정 팀원에게 할당하거나, 할당 없이 두면 팀원이 스스로 가져갈 수 있다. 태스크 간 의존성도 설정할 수 있어서, 선행 태스크가 완료되어야 후속 태스크가 풀리는 방식으로 순서를 강제할 수 있다. 파일 잠금을 통해 여러 팀원이 동시에 같은 태스크를 가져가는 경합도 방지한다.
태스크의 크기를 적절히 잡는 것이 중요하다. 너무 잘게 쪼개면 조율 오버헤드가 작업량을 넘어서고, 너무 크게 잡으면 팀원이 오랫동안 혼자 작업하다가 방향이 어긋날 수 있다. 함수 하나, 테스트 파일 하나, 리뷰 한 건 정도의 단위가 경험적으로 적당하다.
메시지와 브로드캐스트
에이전트 팀에서 팀원 간 통신은 두 가지 방식으로 이루어진다.
직접 메시지(message)는 특정 팀원 하나에게 보내는 1:1 메시지다.
“API 응답에 totalPrice 필드를 추가했으니 프론트 쪽에서 반영해 줘” 같은 구체적인 정보 전달에 쓴다.
브로드캐스트(broadcast)는 모든 팀원에게 동시에 보내는 메시지다. “코딩 컨벤션이 변경되었으니 모두 확인해 달라” 같은 전체 공지에 적합하다. 다만 브로드캐스트는 팀원 수만큼 토큰이 소비되므로 남발하지 않는 편이 좋다.
팀원이 할당된 태스크를 모두 마치면 idle 상태가 되고, 리드에게 자동으로 알림이 간다. 리드는 이 알림을 보고 새 태스크를 할당하거나, 팀원의 작업 결과를 확인할 수 있다.
팀 구성하기
실험 기능 활성화
Agent Teams를 사용하려면 환경 변수를 설정해야 한다.
settings.json에서 설정하는 방법이 가장 깔끔하다.
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
셸 환경 변수로 직접 설정할 수도 있다.
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
팀 생성과 역할 지정
활성화한 뒤 Claude Code 세션에서 자연어로 팀 구성을 요청하면 된다. 역할, 인원수, 작업 범위를 자유롭게 지시하면 리드가 팀원을 생성하고 역할을 할당한다.
팀원마다 모델을 지정할 수도 있다. “각 팀원은 Sonnet을 사용해”처럼 말하면 된다. 리드가 자동으로 적절한 팀 규모를 판단하기도 하고, 사용자가 직접 인원수를 지정할 수도 있다.
화면 구성
팀원 여러 명이 동시에 작업하는 모습을 어떻게 보는지에 따라 두 가지 모드가 있다.
인프로세스 모드(기본값)는 모든 팀원이 하나의 터미널 안에서 돌아간다.
Shift+Down으로 팀원을 순회하고, Enter로 특정 팀원의 세션을 열어본다.
Ctrl+T로 태스크 리스트를 토글할 수 있다. 별도 설정 없이 어떤 터미널에서든 동작한다.
분할 화면 모드는 tmux나 iTerm2를 사용해 팀원마다 별도 패널을 띄운다. 모든 팀원의 작업 상황을 동시에 볼 수 있어서 직관적이다. 패널을 클릭하면 해당 팀원과 직접 대화할 수도 있다. 다만 tmux나 iTerm2가 필요하고, VS Code 통합 터미널이나 Windows Terminal에서는 지원하지 않는다.
{
"teammateMode": "tmux"
}
매번 모드를 지정하기 번거롭다면 "auto"로 설정하면 된다. tmux 세션 안에 있을 때 자동으로 분할 화면을 사용하고, 그 외에는 인프로세스 모드로 동작한다.
비용과 한계
에이전트 팀의 가장 큰 비용은 토큰이다. 팀원 하나가 독립된 Claude Code 세션이므로, 팀원 수만큼 세션 비용이 곱해진다. 팀원 3명이면 단일 세션 대비 대략 3배 이상의 토큰을 소비한다. 브로드캐스트 메시지까지 더하면 비용은 더 올라간다.
아직 다듬어지지 않은 부분도 있다.
- 팀원이 태스크 완료 상태를 갱신하지 않아서 후속 태스크가 막히는 경우가 발생할 수 있다. 직접 확인하고 상태를 갱신해야 한다.
- 인프로세스 팀원이 있는 세션을
/resume으로 복원하면 팀원 상태가 복구되지 않는다. 리드가 존재하지 않는 팀원에게 메시지를 보내려 할 수 있으므로 주의가 필요하다. - tmux 분할 화면 모드에서 팀을 종료했을 때 세션이 남아 있을 수 있다.
tmux kill-session으로 직접 정리해야 한다. - 팀 내 중첩은 지원하지 않는다. 팀원이 자기 하위에 또 다른 팀을 구성하는 것은 불가능하다.
언제 서브에이전트로 충분하고 언제 팀이 필요한가
모든 멀티에이전트 작업에 에이전트 팀을 쓸 필요는 없다. 판단 기준은 크게 세 가지다.
- 에이전트 간 통신이 필요한가? 서브에이전트 사이에는 메시지를 주고받을 통로가 없다. 작업 중간에 에이전트끼리 정보를 교환해야 한다면 팀이 적합하다.
- 세션이 독립적으로 오래 돌아야 하는가? 서브에이전트는 메인 세션 안에서 생성되고 끝나면 결과를 반환한다. 각 에이전트가 긴 시간 동안 독립적으로 작업하면서 필요할 때만 소통해야 한다면 팀 구조가 낫다.
- 비용 대비 이득이 있는가? 토큰 비용이 팀원 수에 비례하므로, 작업의 규모와 복잡도가 그 비용을 정당화해야 한다. 파일 몇 개를 수정하는 작업이라면 서브에이전트로, 크로스 레이어 기능 개발이나 대규모 리팩터링이라면 팀으로 접근하는 것이 합리적이다.
대부분의 일상적인 작업은 서브에이전트만으로 충분하다. “여러 에이전트가 일하면 당연히 빠르지 않을까?”라는 기대만으로 도입하면 조율 오버헤드와 토큰 비용에 놀라게 된다. 단일 에이전트 워크플로우와 서브에이전트로 해결되는 범위라면 굳이 팀을 꾸릴 이유가 없다. 실험적 기능의 불안정성까지 감안하면 더 그렇다.
반대로, 여러 레이어를 동시에 수정하면서 중간중간 인터페이스를 맞춰야 하고, 각 영역의 전문성이 분리되어야 하는 작업이라면 팀 구조가 유의미한 차이를 만든다. 결국 도구의 능력보다 작업의 성격이 선택을 결정하는 게 아닐까 싶다.