Claude Code Agent Teams: 에이전트간 실시간 협업의 시작

2026. 2. 10. 14 min read

TL;DR

Claude Code에 Agent Teams 기능이 출시됐습니다. 기존 서브에이전트가 "일 시키고 결과만 받는" 구조였다면, Agent Teams는 팀메이트끼리 서로 대화하고, 공유 태스크 리스트로 작업을 조율하며, 완료된 세션은 알아서 종료되는 구조입니다. 한마디로 진짜 팀을 꾸려서 일하는 느낌이죠.

서브에이전트, 며칠 전까지 쓰던 방식

요즘 Claude Code 쓰면서 챗 패널 하나 켜놓고 개발하는 분은 별로 없을 겁니다. 다들 서브에이전트를 활용해서 병렬로 작업을 돌리고 있죠. 저도 마찬가지였고, 그러다 보니 항상 주간 토큰 리밋에 막혀서 답답함을 느끼고 있었습니다.

서브에이전트를 간단히 정리하면, 메인 세션 안에서 돌아가는 특화된 AI 어시스턴트입니다. 빌트인으로 Explore(코드베이스 탐색), Plan(계획 수립 리서치), general-purpose(멀티스텝 작업) 3종이 있고, .claude/agents/에 커스텀 에이전트를 마크다운으로 정의할 수도 있습니다.

다만 구조적 한계가 명확합니다. 서브에이전트는 메인 ↔ 서브 간 1:1 보고 구조로만 동작합니다. 서브에이전트 A와 B가 동시에 돌아가도 서로의 존재를 모릅니다. 각자 독립된 컨텍스트에서 작업하고 결과만 메인에 보고하는 방식이죠. 작업 중간에 "야 그거 내가 이미 고쳤어" 같은 조율이 불가능했습니다.

Agent Teams는 뭐가 다른가

Agent Teams는 Opus 4.6 출시와 함께 Research Preview로 공개된 기능입니다. 핵심 차이를 정리하면 이렇습니다:

구분	서브에이전트	Agent Teams
실행 위치	메인 세션 내부	각자 독립된 Claude Code 인스턴스
통신 구조	메인 ↔ 서브 (1:1 보고)	팀메이트 ↔ 팀메이트 (P2P 메시징)
컨텍스트	메인 세션의 권한 상속, 자체 컨텍스트 윈도우	완전 독립 컨텍스트 (CLAUDE.md만 공유)
태스크 관리	메인이 직접 분배	공유 태스크 리스트 + 자동 할당
조율 방식	없음 (결과만 수집)	팀메이트 간 직접 커뮤니케이션
중첩 실행	불가 (서브에이전트가 서브에이전트 생성 불가)	불가 (팀 안의 팀 미지원)
작업 완료	메인이 결과 수신	완료 시 자동 종료 + 리드에 알림
사용자 개입	포그라운드 모드에서만 가능	각 세션에 챗 인풋으로 개입 가능
토큰 비용	상대적으로 적음	팀원 수 × 독립 컨텍스트 (5명이면 ~5배)
커스텀 설정	`.claude/agents/`에 마크다운으로 정의	자연어로 요청

가장 큰 차이는 팀메이트 간 커뮤니케이션입니다. 서브에이전트는 격리된 워커인 반면, Agent Teams의 팀메이트는 서로 발견한 내용을 공유하고, 상대 접근방식에 이의를 제기하고, 독립적으로 작업을 조율할 수 있습니다.

공식 문서의 표현을 빌리면: "서브에이전트는 빠르고 집중된 워커가 필요할 때, Agent Teams는 팀메이트가 발견한 내용을 공유하고 서로 도전하며 스스로 조율해야 할 때" 사용하는 것이 적절합니다.

설정과 사용 방법

1. 환경 변수 활성화

Agent Teams는 기본적으로 비활성화되어 있습니다. 환경 변수를 설정해야 합니다:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

셸 프로필(.bashrc, .zshrc)에 넣어두면 매번 설정하지 않아도 됩니다. 또는 settings.json에서도 설정 가능합니다.

2. 디스플레이 모드 선택

두 가지 모드가 있습니다:

In-process (기본): 모든 팀메이트가 하나의 터미널에서 실행. Shift+Up/Down으로 팀메이트 전환, Enter로 세션 확인. VS Code 터미널 포함 어디서든 동작합니다.
Split panes: 각 팀메이트가 별도 터미널 패널에 표시. tmux 또는 iTerm2 필요. VS Code 통합 터미널에서는 동작하지 않습니다.

저는 권장되는 iTerm2에서 split panes 모드로 실행했습니다:

claude --dangerously-skip-permissions --teammate-mode tmux

3. 팀 구성 요청

특별한 설정 파일이나 YAML이 필요없습니다. 자연어로 요청하면 됩니다:

지금 하는 프로젝트에 계획을 읽고 앞으로 할 작업에 대해 병렬로 작업할 수 있는 지 확인 후 teammate를 구성해줘.

Claude가 프로젝트 상태를 분석하고, 적절한 팀 구성을 제안한 뒤, 승인하면 팀메이트를 생성합니다.

실제 사용 경험

실제로 진행 중인 프로젝트에 적용해 봤습니다. 프로젝트 현황은 다음과 같았습니다:

진행률 ~45%, TypeScript 에러 0, 테스트 74개 통과 (커버리지 ~20%)
기술부채: any 타입 5-10개, console.log 11개, 400줄+ 파일 4개, 에러 바운더리 부족

Claude가 분석 후 4명의 팀메이트를 제안했습니다:

Teammate	역할	담당 영역
quality-lead	코드 품질	type safety + console cleanup
error-boundaries	안정성	라우트/컴포넌트 에러 바운더리 추가
refactorer	리팩토링	4개 대형 파일 분할
tester	테스트	테스트 커버리지 20% → 40%+ 확장

파일 충돌이 없도록 영역을 분리한 점이 인상적이더군요.

4명이 동시에 작업을 시작하고, 각 세션의 진행 상황을 실시간으로 볼 수 있었습니다.

특히 좋았던 점은:

중간 개입 가능: 각 팀메이트 세션에 챗 인풋이 있어서, 작업 도중에 방향을 수정하거나 추가 지시를 내릴 수 있습니다.
자동 종료: 하나의 작업이 완료되면 해당 세션이 알아서 종료됩니다. 리드 에이전트에게 완료 알림이 자동으로 갑니다.
상호 조율: 팀메이트끼리 작업 중에 커뮤니케이션하면서, 예를 들어 리팩토러가 파일 구조를 변경하면 테스터가 이를 인지하고 반영할 수 있습니다.

4개 작업이 모두 완료되면 최종 검증(typecheck + build + test)을 자동으로 실행합니다.

서브에이전트 vs Agent Teams, 언제 무엇을 쓸 것인가

무조건 Agent Teams가 좋다는 건 아닙니다. 토큰 비용이 팀원 수만큼 배로 들어가기 때문에, 상황에 맞게 선택해야 합니다.

서브에이전트가 적합한 경우:

단순하고 집중된 작업 (파일 리서치, 특정 함수 검증, 코드 리뷰)
큰 출력을 격리하고 싶을 때 (테스트 실행, 로그 파일 처리 등)
순차적으로 진행해야 하는 작업
같은 파일을 수정해야 하는 경우
토큰 비용을 아끼고 싶을 때

Agent Teams가 빛나는 경우:

멀티 관점 코드 리뷰 (보안 / 성능 / 테스트 각각 전담)
경쟁 가설 디버깅 (여러 원인을 동시에 검증)
프론트엔드 / 백엔드 / 테스트 크로스 레이어 작업
계획 수립 시 다각도 탐색 (아키텍트 / 비평가 / 리서처 역할 분리)

개인적으로 느낀 점

기존에는 계획을 미리 짜놓고 그 계획에 맞춰서 서브에이전트를 호출해 동시에 작업을 시작하는 방식이었습니다. 사람이 먼저 설계하고, AI가 실행하는 구조였죠.

Agent Teams는 여기서 한 단계 더 나아간다고 느꼈습니다. 계획부터 실행, 테스트, 최종 검증까지 한번에 팀을 꾸려서 처리할 수 있습니다.

예를 들어 이런 워크플로우가 가능합니다:

계획 단계: 플래너 / 아키텍트 / 비평가 팀을 구성해서 계획 수립
계획 리뷰: 사람이 직접 리뷰하고 수정
실행 단계: 적절한 팀메이트를 구성해서 병렬 실행
검증 단계: 자동 테스트 + 빌드 검증

팀메이트끼리 작업중에 커뮤니케이션한다는 점이 기존 방식의 상위호환이라고 느껴집니다. 서브에이전트가 각자 독립된 방에서 일하고 결과만 제출하는 구조였다면, Agent Teams는 같은 사무실에서 옆자리에 앉아 일하면서 필요할 때 바로 이야기하는 구조입니다.

물론 아직 Research Preview인 만큼 제약도 있습니다. 세션 재개가 안 되고, 중첩 팀(팀 안의 팀)도 지원하지 않습니다. 하지만 현재 상태만으로도 충분히 강력하더군요.

서브에이전트 쓰면서도 항상 주간 리밋에 시달렸는데, 이번 주는 팀즈 기능으로 더 화끈하게 녹일 예정입니다.

마치며

Agent Teams는 단순히 "서브에이전트를 여러 개 돌리는 것"이 아닙니다. 팀메이트 간 커뮤니케이션, 공유 태스크 리스트, 자동 작업 할당이라는 근본적으로 다른 아키텍처입니다.

비용은 확실히 더 들지만, 복잡한 멀티 모듈 작업이나 다각도 리뷰처럼 병렬 탐색이 진짜 가치를 더하는 경우에는 그만한 값어치를 합니다.

아직 실험적 기능이니 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 설정하고 직접 체험해보시는 걸 추천합니다. iTerm2 + tmux 조합으로 split panes 모드를 쓰면 각 팀메이트의 작업을 동시에 볼 수 있어서 꽤 인상적인 경험이 됩니다.