Claude Code Agent Teams 제한 사항 총정리

아직 experimental 딱지가 붙어 있는 기능답게, 알아두셔야 할 제약이 꽤 있다. 공식 문서에 나와 있는 것보다 더 제한적이다.

1. 구조적 제한

리더 고정 — 팀을 만든 세션이 끝까지 리더다. 중간에 리더를 교체하거나 팀원을 리더로 승격시키는 건 불가능하다.

세션당 1팀 — 하나의 리더 세션에서 동시에 여러 팀을 운영할 수 없다. 새 팀을 만들려면 기존 팀을 먼저 정리해야 한다.

중첩 팀 불가 — 팀원이 자기 밑에 또 팀을 만들거나 팀원을 스폰하는 계층 구조는 안 된다. 무한 재귀, 토큰 폭주, 통제력 상실을 막기 위한 의도적 설계다. 참고로 하네스 스킬의 팀 아키텍처에는 정의되어 있지만 사용되지는 않는다.

팀원은 서브에이전트도 못 만든다 — 문서에는 “팀이나 팀원을 못 만든다”고만 써 있지만, 실제로는 Agent 도구 자체가 제거된다. 서브에이전트 스폰, 팀 생성·삭제, 크론 작업까지 전부 막혀 있다. 팀원은 사실상 가장 제한된 실행 컨텍스트다.

컨텍스트 격리 — 팀원끼리 컨텍스트 윈도우를 공유하지 않는다. 소통은 메일박스 메시지와 공유 태스크 리스트를 통해서만 이루어진다.

리더 히스토리 미전달 — 리더와 나눈 대화 내용이 팀원에게 자동으로 넘어가지 않는다. 팀원에게 필요한 맥락은 스폰 시 명시적으로 넣어줘야 한다.

도구 비대칭 — 독립 서브에이전트는 약 25개 도구를 쓸 수 있는데, 팀원은 약 20개만 쓸 수 있다. 오케스트레이션 관련 도구(Agent, TeamCreate, TeamDelete, Cron 등)가 전부 빠져 있다.

스폰 시 일괄 권한 — 모든 팀원이 리더의 권한 모드를 그대로 물려받는다. 스폰 시점에 팀원별로 다른 권한을 줄 수 없다. 스폰 후 개별 변경은 가능하지만 번거롭다.

dangerously-skip-permissions 전파 — 리더가 이 옵션으로 실행 중이면 모든 팀원도 동일하게 적용된다. 특정 팀원만 제한하는 건 안 된다.

세션 재개 불가 — /resume 이나 /rewind 로 진행 중이던 팀원을 복원할 수 없다. 재개하면 리더가 이미 사라진 팀원에게 메시지를 보내려고 시도해서 꼬이게 된다. 새 팀원을 다시 스폰해야 한다.

태스크 상태 지연 — 팀원이 작업을 끝내놓고 완료 표시를 안 하는 경우가 있다. 이러면 종속된 다음 태스크가 블록된다. 수동으로 확인하고 상태를 갱신해줘야 할 때가 있다. 시간이 오래 지나도 팀원이 반응이 없다면 진행 상태 확인해 달라고 하면 된다.

종료가 느리다 — 팀원은 현재 실행 중인 요청이나 도구 호출이 끝나야 종료된다. 복잡한 작업 중이면 꽤 기다려야 한다.

파일 충돌 — 두 팀원이 같은 파일을 동시에 수정하면 한쪽 변경이 덮어씌워지거나 git merge conflict가 발생한다.

Opus 4.6+ 필수 — Agent Teams는 Opus 4.6 이상에서만 동작한다. Sonnet으로 팀원을 스폰할 수는 있지만 리더는 Opus여야 한다.

v2.1.32 이상 필수 — 이전 버전에서는 기능 자체가 없다.

Split pane은 tmux/iTerm2만 — VS Code 통합 터미널, Windows Terminal, Ghostty에서는 split-pane 모드가 지원되지 않는다. in-process 모드로 폴백되는데, 이 경우 팀원 출력이 한 스레드에 섞이게 된다.

환경변수 스코프 주의 — 셸에서 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 을 설정하면 그 터미널에서만 유효하다. settings.json 에 넣어야 영구 적용된다.

토큰 선형 증가 — 팀원 수만큼 컨텍스트 윈도우가 별도로 생기므로 토큰 비용이 선형으로 늘어난다. 하네스를 적용하면 기존 대비 비용이 증가하는데, 이는 비효율이 발생하는 것이 아니라 에이전트 팀을 구성하여 병렬로 동작하기 때문이다.

수확 체감 — 팀원이 많아질수록 조율 오버헤드가 커지고, 일정 수를 넘으면 추가 팀원이 속도 향상에 기여하지 못한다. 실전에서는 3~5명이 적정선이다.

브로드캐스팅 — 모든 팀원을 대상으로 하는 메시지 전달은 비용이 크다.

Agent Teams는 병렬 작업에 강력하지만, 계층 구조 불가 + 리더 고정 + 컨텍스트 격리 + 토큰 비용이라는 네 가지 벽이 명확하다. “AI가 AI를 관리하는” 깊은 계층은 아직 지원하지 않는다.