06. 팀 세션 가이드¶

Claude Code에서 에이전트 여럿을 팀으로 묶어 병렬로 돌리는 기능입니다.

팀 세션이란?¶

팀 세션은 Claude Code에서 에이전트 여럿을 한 팀으로 묶어서 동시에 돌리는 기능입니다. 아직 실험 기능이에요. 동작이나 API가 변경될 수 있습니다.

서브에이전트 vs 팀 세션¶

둘 다 "에이전트 여럿이 일한다"는 건 같은데, 방식이 완전히 다릅니다.

활성화 방법¶

~/.claude/settings.json 또는 프로젝트별 .claude/settings.json에 추가합니다.

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

언제 쓰면 좋은가¶

• 한 작업을 역할별로 병렬 분해해야 할 때
• 코드 수정 + 테스트 + 문서화처럼 결과물이 여러 종류일 때
• 경쟁 가설을 병렬로 테스트할 때 (디버깅)
• 프론트엔드/백엔드/테스트를 각 팀원이 담당할 때

실사용 예시: 결제 모듈 리팩토링¶

목표: 결제 모듈 리팩토링
팀 구성:
- 분석 담당: 현재 결제 흐름과 리스크 식별
- 구현 담당: 결제 로직 분리 및 인터페이스 정리
- 검증 담당: 회귀 테스트 케이스 추가

출력 형식:
1) 변경 요약
2) 파일별 수정 목록
3) 테스트 결과
4) 남은 위험 항목

표시 모드¶

팀 운영 팁¶

• 계획 승인 요구: 팀원이 구현 전에 리더 승인을 받도록 설정 가능
• 위임 모드: Shift+Tab으로 리더를 조율 전용으로 제한
• 작업 할당: 리더 직접 할당 또는 팀원 자체 청구 (권장: 팀원당 5~6개 작업)
• 동일 파일 주의: 여러 팀원이 같은 파일을 동시에 편집하면 충돌 발생

제한 사항¶

• 세션 재개 시 in-process 팀원 복원 불가
• 세션당 하나의 팀만 관리 가능
• 중첩 팀 불가 (팀원이 자체 팀 생성 불가)
• 리더 고정 (리더십 이전 불가)

토큰 비용: 솔직한 이야기¶

팀 세션은 좋긴 한데 토큰을 많이 먹습니다.

왜 비싼가?¶

[서브에이전트]
메인 에이전트 1개 + 서브에이전트(결과만 반환)
→ 컨텍스트 공유, 토큰 절약

[팀 세션]
리더 1개 + 팀원 3개 = 4개의 독립 인스턴스
→ 각자 별도 컨텍스트 → 토큰 4배
→ 팀원 간 메시지 교환 → 추가 토큰
→ 작업 목록 동기화 → 추가 토큰

실제 비용 감각¶

위 수치는 Opus 4.6 기준 추정치이며, 모델 업데이트에 따라 달라질 수 있습니다.

비용 최적화 전략¶

1. 연구/검토 작업부터 시작 (파일 수정 없이 분석만)
2. 작업 범위를 명확히 한정 (불필요한 탐색 방지)
3. 팀 규모를 최소로 유지 (2~3명이면 충분)
4. 간단한 작업은 서브에이전트로 (팀 세션이 항상 정답은 아님)

원칙: 작업이 정말로 독립적이고 병렬 처리가 필요한 경우에만 팀 세션을 사용하세요. 순차적 작업이라면 서브에이전트가 더 효율적입니다.

Hooks로 팀 품질 관리¶

팀 세션에 Hooks를 결합하면 품질 게이트를 자동화할 수 있어요.

TeammateIdle — 팀원 유휴 방지¶

팀원이 할 일 없이 멈추려 할 때, 추가 작업을 자동 할당해요.

{
  "hooks": {
    "TeammateIdle": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '아직 미완료 작업이 있습니다. 작업 목록을 확인하세요.'"
          }
        ]
      }
    ]
  }
}

TaskCompleted — 완료 전 품질 게이트¶

팀원이 작업 완료를 선언할 때, lint/test를 통과해야만 허용해요.

{
  "hooks": {
    "TaskCompleted": [
      {
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/quality-gate.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/quality-gate.sh
if ! pnpm lint 2>/dev/null; then
  echo '{"decision": "block", "reason": "lint 에러가 있습니다."}'
  exit 0
fi

if ! pnpm test:run 2>/dev/null; then
  echo '{"decision": "block", "reason": "테스트 실패."}'
  exit 0
fi

Hooks와 팀 세션을 함께 쓰면 "사람이 안 봐도 품질이 유지되는" 자동화된 팀 워크플로우를 만들 수 있어요. 자세한 내용은 16. Hooks 실전 가이드를 참고하세요.

팀 적용 체크리스트¶

• 팀 세션 역할(분석/구현/검증) 템플릿을 정했는가?
• 토큰 비용 예산을 팀 내 공유했는가?
• 팀 세션은 정말 필요한 경우에만 사용하기로 합의했는가?
• 월 1회 릴리스 노트 기반으로 기능 변화를 점검하는가?

다음 단계¶

07. 왜 CLI인가에서 Claude Code CLI의 장점을 알아보세요.

출처¶

• Claude Code 에이전트 팀 문서