Agent Teams - Claude Code 세션 팀 오케스트레이션

3 days ago 4

여러 Claude Code 인스턴스를 하나의 팀으로 구성해 병렬 작업, 메시징, 중앙 관리 기능을 수행하는 실험적 기능
각 세션은 팀 리드와 팀원으로 구성되며, 리드는 작업을 분배하고 결과를 통합, 팀원은 독립된 컨텍스트에서 협업
Subagent와 달리 팀원 간 직접 통신이 가능하며, 병렬 연구·리뷰·디버깅 등에서 효율적
환경 변수 설정으로 기능을 활성화할 수 있으며, tmux 또는 iTerm2를 통한 분할 화면 모드 지원
병렬 탐색과 협업 자동화를 통해 복잡한 개발 작업의 생산성과 품질 향상을 지원

Agent Teams 개요

여러 Claude Code 세션을 하나의 팀 단위로 조정해 병렬로 작업 수행
- 팀 리드가 작업을 분배하고 결과를 종합
- 각 팀원은 독립된 컨텍스트 창에서 개별적으로 실행
Subagent와 달리 팀원 간 직접 메시징 가능
실험적 기능으로 기본 비활성화 상태이며, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 환경 변수 설정으로 활성화

사용 시점

병렬 탐색이 가치 있는 작업에 적합
- 연구 및 리뷰: 여러 팀원이 문제의 다양한 측면을 동시에 조사
- 새 모듈 개발: 각 팀원이 별도 구성 요소 담당
- 경쟁적 가설 검증: 병렬로 다른 이론을 테스트
- 계층 간 조정: 프론트엔드·백엔드·테스트 등 분리된 영역 협업
순차적 작업이나 동일 파일 편집에는 단일 세션 또는 Subagent가 더 효율적

Subagent와의 비교

Subagent는 단일 세션 내에서 실행되어 결과만 리드에게 보고
Agent Team은 각 인스턴스가 완전히 독립되어 상호 통신 가능
조정 방식: Subagent는 리드가 전담, Agent Team은 공유 작업 목록 기반 자율 조정
토큰 비용: 팀 구성원 수에 따라 증가

활성화 및 첫 팀 생성

settings.json 또는 환경 변수에 "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" 추가
활성화 후 자연어로 팀 구성과 역할을 지정 가능
- 예: “UX, 기술 아키텍처, 비판적 검토 역할의 팀 생성”
Claude가 팀을 생성하고 작업 목록을 공유하며, 각 팀원은 독립적으로 문제 탐색

팀 제어 및 표시 모드

리드에게 자연어로 명령해 작업 분배·위임·조정 수행
표시 모드:
- In-process: 모든 팀원이 한 터미널 내에서 실행, Shift+Up/Down으로 전환
- Split panes: 각 팀원이 별도 창에서 실행, tmux 또는 iTerm2 필요
settings.json의 teammateMode로 모드 지정 가능

팀원 및 모델 지정

Claude가 자동으로 팀원 수를 결정하거나 명시적으로 지정 가능
- 예: “4명의 팀원으로 병렬 리팩터링 수행, 각 팀원 Sonnet 모델 사용”

계획 승인 및 Delegate 모드

위험하거나 복잡한 작업은 계획 승인 모드로 설정 가능
- 팀원이 계획을 제출하면 리드가 승인 또는 피드백 후 재검토
Delegate 모드는 리드가 직접 구현하지 않고 조정만 수행하도록 제한

직접 대화 및 작업 관리

각 팀원은 독립된 세션으로, 직접 메시지 전송 가능
- In-process: Shift+Up/Down으로 선택 후 입력
- Split-pane: 해당 창 클릭 후 상호작용
공유 작업 목록으로 진행 상태 관리
- 작업 상태: 대기, 진행 중, 완료
- 리드가 할당하거나 팀원이 자율적으로 Self-claim 가능
- 파일 잠금으로 동시 작업 충돌 방지

종료 및 정리

특정 팀원 종료: “연구자 팀원 종료 요청” 명령
전체 팀 종료: “Clean up the team” 명령으로 리드가 정리 수행
- 리드만 정리 가능, 팀원이 직접 실행 시 불완전한 상태 발생 가능

내부 구조 및 작동 방식

구성 요소
- Team lead: 팀 생성 및 조정 담당
- Teammates: 개별 Claude Code 인스턴스
- Task list: 공유 작업 항목
- Mailbox: 메시징 시스템
팀 구성 정보와 작업 목록은 로컬 저장
- ~/.claude/teams/{team-name}/config.json
- ~/.claude/tasks/{team-name}/

권한 및 통신

팀원은 리드의 권한 설정을 상속
각 팀원은 독립된 컨텍스트 창을 갖고, 자동 메시지 전달 및 작업 상태 공유
메시징 방식:
- message: 특정 팀원에게 전송
- broadcast: 전체 팀원에게 전송 (비용 증가 주의)

토큰 사용량

팀원 수에 비례해 토큰 사용량 증가
연구·리뷰·신규 기능 개발에는 유용하지만, 단순 작업에는 단일 세션이 효율적

활용 예시

병렬 코드 리뷰: 보안·성능·테스트 커버리지별로 팀원 분리
경쟁적 가설 검증: 여러 팀원이 서로의 이론을 반박하며 원인 규명

모범 사례

팀원에게 충분한 맥락 정보 제공
작업 크기를 적절히 조정 (5~6개 작업 단위 유지)
리드가 직접 작업하지 않도록 “Wait for teammates” 명령 사용
초기에는 코드 작성보다 리뷰·조사형 작업으로 시작
파일 충돌 방지 위해 파일 단위로 작업 분리
진행 상황을 주기적으로 점검하고 방향 조정

문제 해결

팀원이 표시되지 않을 경우 Shift+Down으로 순환 확인
권한 요청 과다 시 사전 승인 설정
오류로 중단된 팀원은 직접 지시하거나 새 팀원 생성
리드가 조기 종료 시 “계속 진행” 명령으로 재개
잔여 tmux 세션은 tmux ls 및 tmux kill-session으로 종료

제한 사항

세션 복원 불가, 작업 상태 지연, 종료 지연 등 제약 존재
한 세션당 한 팀만 관리 가능, 중첩 팀 생성 불가
리드 교체 불가, 권한은 생성 시 일괄 적용
Split-pane 모드는 tmux 또는 iTerm2 필요, VS Code 등에서는 미지원

다음 단계

병렬 작업을 위한 대안:
- Subagent: 단일 세션 내 보조 에이전트
- 수동 병렬 세션: Git worktree 기반 다중 세션 실행
- 기능 비교표를 통해 Subagent와 Agent Team의 차이 검토

Read Entire Article