Claude Code Agent Teams - 세팅부터 단축키까지 실전 가이드

Opus 4.6 출시와 함께 공개된 Claude Code Agent Teams입니다. 솔직히 현 단계에서는 비효율적이라고 봅니다. 토큰 소모가 크고 조율 비용도 만만치 않습니다.

그런데 Tom(@tomcrawshaw01)이 쓴 가이드를 읽다 보니 구조 자체는 알아둘 가치가 있었습니다. 프리뷰 단계에서 미리 손에 익혀두면 정식 출시 때 차이가 날 거라는 판단에 정리해봤습니다.

혼자 일하던 에이전트가 팀을 꾸린다

리드 에이전트가 작업을 쪼개서 여러 팀원에게 분배하고 병렬로 동시에 실행하는 구조입니다.

서브 에이전트와 가장 다른 점은 팀원끼리 직접 메시지를 주고받는다는 것입니다. 결과만 보고하는 게 아니라 서로 발견한 내용을 공유하고, 상대 작업에 이의를 제기하기도 합니다.

세팅은 30초면 끝난다

실험 기능이라 기본값이 꺼져 있습니다. 딱 한 줄이면 됩니다.

settings.json의 env 블록에 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 값을 "1"로 추가하면 됩니다. 환경변수로 직접 잡아도 되지만 settings.json이 세션 간 유지되니 더 편합니다.

이 단축키만 외우면 된다

팀이 돌아가기 시작하면 리드와 팀원 사이를 오가면서 작업을 확인해야 합니다. 외울 건 많지 않습니다.

• Shift+Up / Shift+Down - 팀원 간 전환 (in-process 모드, 대부분의 경우 이 단축키를 쓰게 됩니다)
• Enter - 선택한 팀원 세션 상세 보기
• Escape - 팀원의 현재 턴 중단
• Ctrl+T - 공유 태스크 리스트 토글
• Shift+Tab - Delegate 모드 토글. 리드가 코딩하지 않고 조율만 하도록 잠금
• split-pane 모드 - 팀원 패널을 클릭해서 직접 상호작용

Delegate 모드는 꼭 알아둬야 합니다. 켜지 않으면 리드가 위임 대신 직접 코딩을 시작하는 경우가 생깁니다.

터미널마다 되는 게 다르다

split-pane 모드는 tmux와 iTerm2에서만 동작합니다. VS Code 통합 터미널, Windows Terminal, Ghostty는 공식 미지원입니다.

Ghostty에서 작업한다면 기본 in-process 모드에서 Shift+Up/Down으로 팀원을 전환하게 됩니다.

팀원 출력을 동시에 보고 싶으면 tmux 세션 안에서 Claude Code를 실행하면 됩니다. teammateMode 기본값이 “auto”라서 tmux 세션 안이면 자동으로 split-pane으로 전환됩니다.

저는 iTerm에서 tmux new -s {my-project}로 세션을 만든 후 claude --teammate-mode tmux로 실행하고 있습니다. 전체 화면에서 팀의 활동을 한눈에 볼 수 있습니다.

태스크는 이렇게 흘러간다

태스크 리스트 기반으로 작업이 흘러갑니다. 리드가 목록을 만들면 팀원이 알아서 가져가는 구조입니다.

• 리드가 태스크 리스트를 만들면 팀원이 자동으로 다음 미할당 작업을 가져갑니다
• 태스크 간 의존 관계 설정이 가능합니다. 선행 태스크가 끝나야 후속이 풀립니다
• 특정 팀원에게 지정 배분도 됩니다. 리드에게 “이 작업은 팀원 2번에게”라고 말하면 됩니다
• 팀원 종료 프로토콜: 리드가 shutdown 요청을 보내고, 팀원이 확인 후 종료합니다
• 전체 정리: 모든 팀원 종료 확인 후 리드에게 cleanup 지시

간단하게 “팀”을 언급하면 해당 기능이 자동으로 작동합니다. 하지만 좀 더 정교한 팀을 구성하려면 총 팀원의 수와 각 팀원의 이름과 역할, 위임 범위를 정하고, 외부 파일로 정리한 태스크 간 Dependency 규칙을 이식하면 됩니다.

토큰은 생각보다 빠르게 빠진다

팀원 하나가 독립된 Claude Code 세션이라 병렬로 돌리면 비용이 급격히 올라갑니다. 몇 가지만 지키면 낭비를 줄일 수 있습니다.

• 팀원 spawn 프롬프트를 구체적으로 작성하세요. 리드 대화 이력은 팀원에게 넘어가지 않습니다. CLAUDE.md와 MCP 서버 컨텍스트만 자동 로드됩니다
• 한 파일에 팀원 두 명이 손대면 덮어쓰기가 발생합니다. 파일 단위로 확실히 나눠야 합니다
• 처음 쓴다면 코드 작성보다 리서치나 코드 리뷰부터 시작하는 게 좋습니다. 조율 복잡도가 낮습니다
• 작업 단위는 함수 하나나 테스트 파일 하나처럼 명확한 결과물이 나오는 크기가 적당합니다

부딪히기 전에 알아두면 좋은 한계

프리뷰 단계라 거친 부분이 꽤 있습니다. 미리 알아두면 도구 탓을 안 하게 됩니다.

• /resume이나 /rewind를 쓰면 in-process 팀원이 사라집니다. 리드에게 새로 spawn하라고 지시해야 합니다
• 태스크 상태가 지연될 수 있습니다. 팀원이 작업을 끝냈는데 완료 표시를 안 하면 후속 태스크가 막힙니다. 직접 확인하고 리드에게 업데이트를 요청하세요
• 세션당 팀은 1개만 가능합니다. 팀원이 자체적으로 하위 팀을 만들 수도 없습니다
• 팀을 만든 세션이 끝까지 리드입니다. 중간에 리더를 바꾸거나 팀원을 승격시킬 수 없습니다

프리뷰 단계이고 비용 대비 효율에도 의문이 남습니다. 그래도 멀티 에이전트가 가는 방향을 이해하려면 한번 직접 켜보는 게 가장 빠릅니다. 도구는 써봐야 판단할 수 있으니까요.