Claude Code 세션 팀 조율하기

• 에이전트 팀을 사용할 때, 최적의 사용 사례 및 subagents와의 비교 포함
• 팀 시작하기
• 팀원 제어하기, 표시 모드, 작업 할당, 위임 포함
• 병렬 작업 모범 사례

​

에이전트 팀을 사용할 때

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

​

subagents와 비교

​

에이전트 팀 활성화

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

​

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

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Create an agent team to explore this from different angles: one
teammate on UX, one on technical architecture, one playing devil's advocate.

​

에이전트 팀 제어하기

​

표시 모드 선택

• In-process: 모든 팀원이 메인 터미널 내에서 실행됩니다. Shift+Down을 사용하여 팀원들을 순환하고 입력하여 직접 메시지를 보냅니다. 모든 터미널에서 작동하며 추가 설정이 필요하지 않습니다.
• 분할 창: 각 팀원이 자신의 창을 가집니다. 모든 사람의 출력을 한 번에 볼 수 있고 창을 클릭하여 직접 상호작용할 수 있습니다. tmux 또는 iTerm2가 필요합니다.

{
  "teammateMode": "in-process"
}

claude --teammate-mode in-process

• tmux: 시스템의 패키지 관리자를 통해 설치합니다. 플랫폼별 지침은 tmux wiki를 참조합니다.
• iTerm2: it2 CLI를 설치한 후, iTerm2 → Settings → General → Magic → Enable Python API에서 Python API를 활성화합니다.

​

팀원 및 모델 지정

Create a team with 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.

​

팀원을 위한 계획 승인 요구

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

​

팀원과 직접 대화하기

• In-process 모드: Shift+Down을 사용하여 팀원들을 순환한 후 입력하여 메시지를 보냅니다. Enter를 눌러 팀원의 세션을 보고, Escape를 눌러 현재 턴을 중단합니다. Ctrl+T를 눌러 작업 목록을 전환합니다.
• 분할 창 모드: 팀원의 창을 클릭하여 세션과 직접 상호작용합니다. 각 팀원은 자신의 터미널의 전체 보기를 가집니다.

​

작업 할당 및 요청

• 리더 할당: 리더에게 어느 작업을 어느 팀원에게 줄지 말합니다
• 자체 요청: 작업을 마친 후, 팀원은 다음 미할당, 미차단 작업을 자체적으로 선택합니다

​

팀원 종료하기

Ask the researcher teammate to shut down

​

팀 정리하기

Clean up the team

​

hooks로 품질 게이트 적용

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

​

에이전트 팀이 어떻게 작동하는지

​

Claude가 에이전트 팀을 시작하는 방법

• 팀 요청: 병렬 작업의 이점이 있는 작업을 제공하고 명시적으로 에이전트 팀을 요청합니다. Claude는 지시에 따라 팀을 만듭니다.
• Claude가 팀 제안: Claude가 작업이 병렬 작업의 이점이 있다고 판단하면, 팀 생성을 제안할 수 있습니다. 진행하기 전에 확인합니다.

​

아키텍처

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

​

권한

​

컨텍스트 및 통신

• 자동 메시지 전달: 팀원들이 메시지를 보낼 때, 자동으로 수신자에게 전달됩니다. 리더가 업데이트를 폴링할 필요가 없습니다.
• 유휴 알림: 팀원이 완료되고 중지되면, 자동으로 리더에게 알립니다.
• 공유 작업 목록: 모든 에이전트는 작업 상태를 보고 사용 가능한 작업을 요청할 수 있습니다.

• message: 특정 팀원 한 명에게 메시지 보내기
• broadcast: 모든 팀원에게 동시에 보내기. 팀 크기에 따라 비용이 증가하므로 드물게 사용합니다.

​

토큰 사용

​

사용 사례 예시

​

병렬 코드 검토 실행

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

​

경쟁하는 가설로 조사하기

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

​

모범 사례

​

팀원에게 충분한 컨텍스트 제공

Spawn a security reviewer teammate with the prompt: "Review the authentication module
at src/auth/ for security vulnerabilities. Focus on token handling, session
management, and input validation. The app uses JWT tokens stored in
httpOnly cookies. Report any issues with severity ratings."

​

적절한 팀 크기 선택

• 토큰 비용이 선형으로 증가: 각 팀원은 자신의 컨텍스트 윈도우를 가지며 독립적으로 토큰을 소비합니다. 자세한 내용은 에이전트 팀 토큰 비용을 참조합니다.
• 조율 오버헤드 증가: 더 많은 팀원은 더 많은 통신, 작업 조율, 충돌 가능성을 의미합니다
• 수익 감소: 특정 지점을 넘으면, 추가 팀원은 작업 속도를 비례적으로 높이지 않습니다

​

작업을 적절히 크기 조정

• 너무 작음: 조율 오버헤드가 이점을 초과합니다
• 너무 큼: 팀원들이 체크인 없이 너무 오래 작동하여 낭비된 노력의 위험이 증가합니다
• 적절함: 함수, 테스트 파일, 검토와 같은 명확한 결과물을 생성하는 자체 포함된 단위

​

팀원들이 완료될 때까지 기다리기

Wait for your teammates to complete their tasks before proceeding

​

연구 및 검토로 시작하기

​

파일 충돌 피하기

​

모니터링 및 조율

​

문제 해결

​

팀원이 나타나지 않음

• In-process 모드에서, 팀원들이 이미 실행 중이지만 보이지 않을 수 있습니다. Shift+Down을 눌러 활성 팀원들을 순환합니다.
• Claude에게 준 작업이 팀을 보증할 만큼 복잡한지 확인합니다. Claude는 작업에 따라 팀원을 생성할지 결정합니다.
• 분할 창을 명시적으로 요청했으면, tmux가 설치되어 있고 PATH에서 사용 가능한지 확인합니다:
  잘못된 코드 신고

  복사

  AI에게 묻기

  which tmux
  
• iTerm2의 경우, it2 CLI가 설치되어 있고 Python API가 iTerm2 환경 설정에서 활성화되어 있는지 확인합니다.

​

너무 많은 권한 프롬프트

​

팀원들이 오류에서 중지됨

• 직접 추가 지시를 제공합니다
• 작업을 계속하기 위해 대체 팀원을 생성합니다

​

리더가 작업 완료 전에 종료됨

​

고아 tmux 세션

tmux ls
tmux kill-session -t <session-name>

​

제한 사항

• In-process 팀원과의 세션 재개 없음: /resume과 /rewind는 in-process 팀원을 복원하지 않습니다. 세션을 재개한 후, 리더는 더 이상 존재하지 않는 팀원에게 메시지를 보내려고 시도할 수 있습니다. 이 경우 리더에게 새 팀원을 생성하도록 말합니다.
• 작업 상태가 지연될 수 있음: 팀원들이 때때로 작업을 완료로 표시하지 못하여 종속 작업을 차단합니다. 작업이 막혀 있는 것처럼 보이면, 작업이 실제로 완료되었는지 확인하고 작업 상태를 수동으로 업데이트하거나 리더에게 팀원을 밀도록 말합니다.
• 종료가 느릴 수 있음: 팀원들은 현재 요청이나 도구 호출을 마친 후 종료되어 시간이 걸릴 수 있습니다.
• 세션당 한 팀: 리더는 한 번에 한 팀만 관리할 수 있습니다. 새 팀을 시작하기 전에 현재 팀을 정리합니다.
• 중첩된 팀 없음: 팀원들은 자신의 팀이나 팀원을 생성할 수 없습니다. 리더만 팀을 관리할 수 있습니다.
• 리더가 고정됨: 팀을 만드는 세션은 수명 동안 리더입니다. 팀원을 리더로 승격하거나 리더십을 이전할 수 없습니다.
• 생성 시 권한 설정: 모든 팀원은 리더의 권한 모드로 시작합니다. 생성 후 개별 팀원 모드를 변경할 수 있지만, 생성 시 팀원별 모드를 설정할 수 없습니다.
• 분할 창은 tmux 또는 iTerm2 필요: 기본 in-process 모드는 모든 터미널에서 작동합니다. 분할 창 모드는 VS Code의 통합 터미널, Windows Terminal, Ghostty에서 지원되지 않습니다.

​

다음 단계

• 경량 위임: subagents는 세션 내에서 연구 또는 검증을 위해 도우미 에이전트를 생성하며, 에이전트 간 조율이 필요하지 않은 작업에 더 좋습니다
• 수동 병렬 세션: Git worktrees를 사용하면 자동화된 팀 조율 없이 여러 Claude Code 세션을 직접 실행할 수 있습니다
• 접근 방식 비교: subagent vs 에이전트 팀 비교를 참조하여 나란히 비교합니다