Claude Code: 제대로 알고 쓰자(agent team편)

Claude Code 세션 팀 조율하기

공유 작업, 에이전트 간 메시징, 중앙 집중식 관리를 통해 여러 Claude Code 인스턴스가 팀으로 함께 작업하도록 조정할 수 있다.

에이전트 팀은 아직 실험적 기능이며 기본적으로 비활성화되어 있다. settings.json 또는 환경에 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS를 추가하여 활성화할 수 있다.

에이전트 팀을 사용하면 여러 Claude Code 인스턴스가 함께 작업하도록 조정할 수 있다. 한 세션이 팀 리드로 작동하여 작업을 조정하고, 작업을 할당하고, 결과를 종합한다. 팀원들은 각자 자신의 컨텍스트 윈도우에서 독립적으로 작업하며 서로 직접 통신한다.

단일 세션 내에서 실행되고 메인 에이전트에게만 보고할 수 있는 서브에이전트와 달리, 리드를 거치지 않고 개별 팀원과 직접 상호작용할 수도 있다.

이번 포스팅에서는 아래와 같은 내용을 알아볼 것이다.

• 에이전트 팀을 사용하는 경우, 최적 사용 사례 및 서브에이전트와의 비교 포함
• 팀 시작하기
• 팀원 제어하기, 디스플레이 모드, 작업 할당, 위임 포함
• 병렬 작업을 위한 모범 사례

에이전트 팀을 사용하는 경우

에이전트 팀은 병렬 탐색이 실질적인 가치를 더하는 작업에 가장 효과적이다. 가장 좋은 사용 사례는 아래와 같다.

• 분석 및 검토: 여러 팀원이 문제의 다양한 측면을 동시에 조사한 다음 서로의 발견 사항을 공유하고 도전할 수 있다.
• 새로운 모듈 또는 기능: 팀원들이 각자 별도의 부분을 소유하여 서로 방해하지 않는다.
• 경쟁 가설을 통한 디버깅: 팀원들이 서로 다른 이론을 병렬로 테스트하고 더 빠르게 답에 수렴한다.
• 계층 간 조정: 프론트엔드, 백엔드, 테스트에 걸친 변경 사항을 각각 다른 팀원이 소유한다.

에이전트 팀은 조정 오버헤드를 추가하고 단일 세션보다 훨씬 많은 토큰을 사용한다!!! 당연하겠지만 팀원들이 독립적으로 작업할 수 있을 때 가장 잘 작동한다. 순차적 작업, 동일한 파일 편집 또는 많은 종속성이 있는 작업의 경우 단일 세션 또는 서브에이전트가 더 효과적이다.

서브에이전트와 비교

에이전트 팀과 서브에이전트 모두 작업을 병렬화할 수 있지만 다르게 작동한다.

	서브에이전트	에이전트 팀
컨텍스트	자체 컨텍스트 윈도우; 결과가 호출자에게 반환됨	자체 컨텍스트 윈도우; 완전히 독립적
통신	메인 에이전트에게만 결과 보고	팀원들이 서로 직접 메시지 전송
조정	메인 에이전트가 모든 작업 관리	자체 조정을 통한 공유 작업 목록
최적 사용처	결과만 중요한 집중된 작업	토론과 협업이 필요한 복잡한 작업
토큰 비용	낮음: 결과가 메인 컨텍스트로 요약됨	높음: 각 팀원은 별도의 Claude 인스턴스

결과를 보고하는 빠르고 집중된 워커가 필요할 때는 서브에이전트를 사용하는 것을 권장한다. 팀원들이 발견 사항을 공유하고, 서로 도전하고, 스스로 조정해야 할 때는 에이전트 팀을 사용하는 것을 권장한다.

에이전트 팀 활성화하기

에이전트 팀은 기본적으로 비활성화되어 있다. 셸 환경 또는 settings.json을 통해 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 환경 변수를 1로 설정하여 활성화해야한다.

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

첫 번째 에이전트 팀 시작하기

에이전트 팀을 활성화한 후 Claude에게 에이전트 팀을 만들라고 말하고 작업과 원하는 팀 구조를 자연어로 설명하면 된다. Claude는 팀을 만들고, 팀원을 생성하고, 프롬프트를 기반으로 작업을 조정하게된다.

아래 예제는 세 가지 역할이 독립적이며 서로를 기다리지 않고 문제를 탐색할 수 있기 때문에 잘 작동할 것이다.

...
개발자가 코드베이스에서 TODO 주석을 추적하는 데 도움이 되는 CLI 도구를 설계하고 있습니다.
다양한 각도에서 이것을 탐색하기 위한 에이전트 팀을 만드세요:
한 팀원은 UX를, 한 팀원은 기술 아키텍처를, 한 팀원은 반대 의견을 제시하세요.
...

여기서부터 Claude는 공유 작업 목록이 있는 팀을 만들고, 각 관점에 대한 팀원을 생성하고, 문제를 탐색하게 하고, 발견 사항을 종합하고, 완료되면 팀을 정리하려고 시도한다.

리드의 터미널에는 모든 팀원과 그들이 작업 중인 내용이 나열된다. Shift+Up/Down을 사용하여 팀원을 선택하고 직접 메시지를 보내보자.

각 팀원을 자체 분할 창에 원하는 경우 디스플레이 모드 선택을 통해 변경할 수 있다.

에이전트 팀 제어하기

리드에게 원하는 것을 자연어로 말해보자. 리드는 지시사항을 기반으로 팀 조정, 작업 할당, 위임을 처리하게 된다.

디스플레이 모드 선택하기

에이전트 팀은 두 가지 디스플레이 모드를 지원한다.

• In-process: 모든 팀원이 메인 터미널 내에서 실행된다. Shift+Up/Down을 사용하여 팀원을 선택하고 입력하여 직접 메시지를 보낼 수 있다.
• Split panes: 각 팀원이 자체 창을 갖는다. 모든 사람의 출력을 한 번에 볼 수 있고 창을 클릭하여 직접 상호작용할 수 있다. tmux 또는 iTerm2가 필요하다.

tmux는 특정 운영 체제에서 알려진 제한 사항이 있으며 전통적으로 macOS에서 가장 잘 작동한다. iTerm2에서 tmux -CC를 사용하는 것이 tmux의 권장 진입점이다.

기본값은 "auto"이며, 이미 tmux 세션 내에서 실행 중인 경우 분할 창을 사용하고 그렇지 않으면 in-process를 사용한다. "tmux" 설정은 분할 창 모드를 활성화하고 터미널을 기반으로 tmux 또는 iTerm2를 사용할지 자동으로 감지한다. 재정의하려면 settings.json에서 teammateMode를 설정하면 된다.

{
  "teammateMode": "in-process"
}

단일 세션에 대해 in-process 모드를 강제하려면 플래그로 전달할 수 있다.

claude --teammate-mode in-process

분할 창 모드는 tmux 또는 it2 CLI가 있는 iTerm2가 필요하다.

팀원 및 모델 지정하기

Claude는 작업을 기반으로 생성할 팀원 수를 결정하거나, 원하는 것을 정확히 지정할 수 있다:

...
이 모듈들을 병렬로 리팩토링하기 위해 4명의 팀원이 있는 팀을 만드세요.
각 팀원에게 Sonnet을 사용하세요.
...

팀원에 대한 계획 승인 요구하기

복잡하거나 위험한 작업의 경우 팀원이 구현하기 전에 계획을 세우도록 요구할 수 있다. 팀원은 리드가 접근 방식을 승인할 때까지 읽기 전용 계획 모드에서 작업한다.

...
인증 모듈을 리팩토링하기 위해 아키텍트 팀원을 생성하세요.
변경하기 전에 계획 승인을 요구하세요.
...

팀원이 계획을 완료하면 리드에게 계획 승인 요청을 보낸다. 리드는 계획을 검토하고 승인하거나 피드백과 함께 거부한다. 거부되면 팀원은 계획 모드에 머물고, 피드백을 기반으로 수정하고, 다시 제출한다. 승인되면 팀원은 계획 모드를 종료하고 구현을 시작한다.

리드는 승인 결정을 자율적으로 내린다. 리드의 판단에 영향을 주려면 프롬프트에 기준을 제공하자. 예를 들어 "테스트 커버리지를 포함하는 계획만 승인" 또는 "데이터베이스 스키마를 수정하는 계획은 거부"와 같다.

위임 모드 사용하기

위임 모드 없이 리드는 때때로 팀원을 기다리는 대신 작업을 직접 구현하기 시작한다. 위임 모드는 리드를 조정 전용 도구로 제한하여 이를 방지한다: 생성, 메시징, 팀원 종료, 작업 관리.

이것은 리드가 코드를 직접 건드리지 않고 작업 분해, 작업 할당, 결과 종합과 같은 오케스트레이션에 완전히 집중하기를 원할 때 유용하다.

활성화하려면 먼저 팀을 시작한 다음 Shift+Tab을 눌러 위임 모드로 전환할 수 있다.

팀원과 직접 대화하기

각 팀원은 완전하고 독립적인 Claude Code 세션이다. 추가 지침을 제공하거나, 후속 질문을 하거나, 접근 방식을 재지정하기 위해 팀원에게 직접 메시지를 보낼 수 있다.

작업 할당하기

공유 작업 목록은 팀 전체에서 작업을 조정한다. 리드는 작업을 만들고 팀원은 작업을 처리한다. 작업에는 세 가지 상태가 있다.

1. 대기 중
2. 진행 중
3. 완료됨

작업은 다른 작업에 종속될 수도 있다. 해결되지 않은 종속성이 있는 대기 중 작업은 해당 종속성이 완료될 때까지 진행할 수 없다.

리드는 작업을 명시적으로 할당하거나 팀원이 스스로 진행할 수 있다.

• 리드 할당: 리드에게 어떤 작업을 어떤 팀원에게 줄지 이야기하면 된다.
• 자체 진행: 작업을 완료한 후 팀원은 다음 할당되지 않고 차단되지 않은 작업을 스스로 선택한다.

작업 청구는 파일 잠금을 사용하여 여러 팀원이 동시에 동일한 작업을 청구하려고 할 때 경쟁 조건을 방지한다.

팀원 종료하기

팀원의 세션을 우아하게 종료하면 아래와 같이 하면 된다.

연구 팀원에게 종료하라고 요청하세요.

그러면 리드는 종료 요청을 보낸다. 팀원은 우아하게 종료하면서 승인하거나 설명과 함께 거부할 수 있다.

팀 정리하기

완료되면 리드에게 정리를 요청할 수 있다.

팀을 정리하세요

이렇게 하면 공유 팀 리소스가 제거된다. 리드가 정리를 실행하면 활성 팀원을 확인하고 아직 실행 중인 팀원이 있으면 실패하므로 먼저 종료하자.

항상 리드를 사용하여 정리하는 것을 권장한다. 팀원은 팀 컨텍스트가 올바르게 해결되지 않아 리소스가 일관성 없는 상태로 남을 수 있으므로 정리를 실행해서는 안 된다. (Memory leak!!!)

훅으로 품질 게이트 시행하기

팀원이 작업을 완료하거나 작업이 완료될 때 규칙을 시행하기 위해 훅을 사용할 수 있다!

• TeammateIdle: 팀원이 유휴 상태가 되려고 할 때 실행된다. 코드 2로 종료하여 피드백을 보내고 팀원이 계속 작업하도록 한다.
• TaskCompleted: 작업이 완료로 표시될 때 실행된다. 코드 2로 종료하여 완료를 방지하고 피드백을 보낸다.

에이전트 팀 작동 방식

아키텍처

에이전트 팀은 아래와 같이 구성된다.

구성 요소	역할
Team lead	팀을 만들고 팀원을 생성하고 작업을 조정하는 메인 Claude Code 세션
Teammates	각각 할당된 작업을 수행하는 별도의 Claude Code 인스턴스
Task list	팀원이 청구하고 완료하는 공유 작업 항목 목록
Mailbox	에이전트 간 통신을 위한 메시징 시스템

시스템은 작업 종속성을 자동으로 관리한다. 팀원이 다른 작업이 종속된 작업을 완료하면 수동 개입 없이 차단된 작업이 차단 해제된다.

팀과 작업은 로컬에 저장된다.

• 팀 구성: ~/.claude/teams/{team-name}/config.json
• 작업 목록: ~/.claude/tasks/{team-name}/

팀 구성에는 각 팀원의 이름, 에이전트 ID, 에이전트 유형이 포함된 members 배열이 있다. 팀원은 이 파일을 읽어 다른 팀 멤버를 발견할 수 있다.

권한

팀원은 리드의 권한 설정으로 시작한다. 리드가 --dangerously-skip-permissions로 실행되면 모든 팀원도 그렇게 한다. 생성 후 개별 팀원 모드를 변경할 수 있지만 생성 시 팀원별 모드를 설정할 수는 없다.

컨텍스트 및 통신

각 팀원은 자체 컨텍스트 윈도우를 가진다. 생성될 때 팀원은 일반 세션과 동일한 프로젝트 컨텍스트를 로드한다. CLAUDE.md, MCP 서버, 스킬. 또한 리드로부터 생성 프롬프트를 받는다. 리드의 대화 기록은 이월되지 않는다. 에이전트 팀을 꾸리면 토큰이 상당히 많이 쓰이는 이유가 바로 이것이다!!!

팀원이 정보를 공유하는 방법:

• 자동 메시지 전달: 팀원이 메시지를 보내면 수신자에게 자동으로 전달된다. 리드는 업데이트를 폴링할 필요가 없다.
• 유휴 알림: 팀원이 완료하고 중지하면 자동으로 리드에게 알린다.
• 공유 작업 목록: 모든 에이전트가 작업 상태를 볼 수 있고 사용 가능한 작업을 청구할 수 있다.

팀원 메시징:

• message: 특정 팀원 한 명에게 메시지를 보낸다
• broadcast: 모든 팀원에게 동시에 보낸다. 리소스가 팀 크기에 따라 증가하므로 신중하게 사용해야한다.

토큰 사용량

에이전트 팀은 단일 세션보다 훨씬 많은 토큰을 사용한다. 각 팀원은 자체 컨텍스트 윈도우를 가지며 토큰 사용량은 활성 팀원 수에 따라 증가한다. 연구, 검토, 새로운 기능 작업의 경우 추가 토큰은 일반적으로 가치가 있다. 일상적인 작업의 경우 단일 세션이 더 비용 효율적이다. 사용 지침은 에이전트 팀 토큰 비용을 참조하면된다.

사용 사례 예제

아래 예제는 병렬 탐색이 가치를 더하는 작업을 에이전트 팀이 처리하는 방법이다.

병렬 코드 검토 실행하기

단일 검토자는 한 번에 한 유형의 문제에 끌리는 경향이 있다. 검토 기준을 독립적인 도메인으로 분할하면 보안, 성능, 테스트 커버리지가 모두 동시에 철저한 주의를 받는다. 프롬프트는 각 팀원에게 고유한 렌즈를 할당하여 겹치지 않도록 한다.

...
PR #142를 검토하기 위한 에이전트 팀을 만드세요. 세 명의 검토자를 생성하세요:
- 보안 영향에 중점을 둔 한 명
- 성능 영향을 확인하는 한 명
- 테스트 커버리지를 검증하는 한 명
각자 검토하고 발견 사항을 보고하도록 하세요.
...

각 검토자는 동일한 PR에서 작업하지만 다른 필터를 적용한다. 리드는 완료 후 세 가지 모두에서 발견 사항을 종합한다.

경쟁 가설로 조사하기

근본 원인이 불분명할 때 단일 에이전트는 하나의 그럴듯한 설명을 찾고 찾기를 멈추는 경향이 있다. 프롬프트는 팀원을 명시적으로 적대적으로 만들어 이에 반론을 제시하게 한다: 각자의 일은 자신의 이론을 조사하는 것뿐만 아니라 다른 사람들에게 도전(?)하는 것이다.

...
사용자들이 앱이 연결 상태를 유지하는 대신 한 메시지 후 종료된다고 보고합니다.
다양한 가설을 조사하기 위해 5명의 에이전트 팀원을 생성하세요.
과학적 토론처럼 서로의 이론을 반증하기 위해 서로 대화하도록 하세요.
어떤 합의가 나오든 발견 사항 문서를 업데이트하세요.
...

토론 구조가 여기서 핵심 메커니즘이다: 한 이론이 탐색되면 후속 조사는 그것에 편향된다.

서로를 적극적으로 반증하려는 여러 독립적인 조사자들과 함께 살아남은 이론은 실제 근본 원인일 가능성이 훨씬 더 높다.

참고

에이전트-팀즈