목차
에이전트 팀 조정
개요
Claude Code 에이전트 팀은 파일시스템 기반 조정 프로토콜을 통해 여러 Claude CLI 프로세스가 공유 작업에서 협업할 수 있도록 합니다. 각 팀원은 독립적인 claude 프로세스로 tmux 패널에서 실행되며, fcntl 잠금으로 보호된 JSON 파일을 통해 통신합니다. 데이터베이스, 데몬, 네트워크 계층이 필요 없습니다.
이 스킬은 에이전트 팀을 효과적으로 오케스트레이션하는 패턴을 제공합니다.
사용 시기
- 여러 파일이나 모듈에 걸친 병렬 구현
- 다중 에이전트 코드 리뷰 (한 에이전트가 리뷰하고 다른 에이전트가 수정 구현)
- 하위 시스템 전반에 걸친 조정된 변경이 필요한 대규모 리팩토링
- 자연스러운 병렬성을 가져 동시 에이전트의 이점을 얻을 수 있는 작업
사용하지 말아야 할 시기
- 단일 파일 변경이나 소규모 작업 (오버헤드가 이점보다 큼)
- 긴밀한 순차적 추론이 필요한 작업 (에이전트가 느슨하게 조정됨)
claudeCLI를 사용할 수 없거나 tmux가 설치되지 않은 경우
전제 조건
# Claude Code CLI 확인
claude --version
# tmux 확인 (분할 패널 모드 필요)
tmux -V
# 실험적 기능 활성화 (스포너가 자동으로 설정)
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
프로토콜 아키텍처
~/.claude/
teams/<team-name>/
config.json # 팀 메타데이터 + 멤버 명단
inboxes/
<agent-name>.json # 에이전트별 메시지 큐
.lock # fcntl 배타적 잠금
tasks/<team-name>/
1.json ... N.json # 자동 증가 작업 파일
.lock # fcntl 배타적 잠금
설계 원칙:
- 파일시스템이 데이터베이스: JSON 파일,
tempfile+os.replace를 통한 원자적 쓰기 - fcntl 잠금: 인박스와 작업에 대한 동시 읽기/쓰기 손상 방지
- 번호가 매겨진 작업: 순차적 파일 명명을 통한 자동 증가 ID
- 느슨한 결합: 에이전트는 자신의 인박스를 폴링하며 푸시 알림 없음
빠른 시작
1. 팀 생성
# 프로그래매틱 팀 설정 (MCP 또는 직접 API를 통해)
# 팀 구성이 ~/.claude/teams/<team-name>/config.json에 기록됨
팀 구성에는 다음이 포함됩니다:
name,description,created_at(ms 타임스탬프)lead_agent_id,lead_session_idmembers[]— LeadMember 및 TeammateMember 객체 배열
2. 팀원 생성
각 팀원은 ID 플래그와 함께 별도의 claude CLI 프로세스로 실행됩니다.
claude --agent-id "backend@my-team" \
--agent-name "backend" \
--team-name "my-team" \
--agent-color "#FF6B6B" \
--parent-session-id "$SESSION_ID" \
--agent-type "general-purpose" \
--model sonnet
tmux 패널 관리 및 색상 할당은 modules/spawning-patterns.md를 참조하세요.
3. 의존성이 있는 작업 생성
{
"id": "1",
"subject": "API 엔드포인트 구현",
"description": "사용자 관리를 위한 REST 엔드포인트 생성",
"status": "pending",
"owner": null,
"blocks": ["3"],
"blocked_by": [],
"metadata": {}
}
상태 머신 및 의존성 관리는 modules/task-coordination.md를 참조하세요.
4. 메시지를 통한 조정
{
"from": "team-lead",
"text": "API 엔드포인트가 통합 테스트 준비 완료",
"timestamp": "2026-02-07T22:00:00Z",
"read": false,
"summary": "API 준비 완료"
}
메시지 유형 및 인박스 작업은 modules/messaging-protocol.md를 참조하세요.
조정 워크플로우
agent-teams:team-created— 팀 구성 및 디렉토리 초기화agent-teams:teammates-spawned— tmux 패널에서 에이전트 실행agent-teams:tasks-assigned— 의존성 있는 작업 생성, 소유자 할당agent-teams:coordination-active— 에이전트가 작업을 요청하고, 메시지를 교환하며, 완료 표시agent-teams:team-shutdown— 승인 프로토콜을 통한 정상 종료
역할 및 건강 모니터링
각 팀원은 role을 가지며, 이는 능력과 작업 호환성을 결정합니다. 다섯 가지 역할이 정의됩니다: implementer(기본값), researcher, tester, reviewer, architect. 역할은 에이전트가 처리할 수 있는 위험 계층을 제한합니다. 전체 능력 매트릭스 및 역할-위험 호환성 표는 modules/crew-roles.md를 참조하세요.
팀원의 건강은 심박 메시지와 요청 만료를 통해 모니터링할 수 있습니다. 리더는 60초마다 2단계 정지 감지 프로토콜(health_check 프로브 + 30초 대기)로 팀 건강을 폴링합니다. 정지된 에이전트의 작업은 해제되고 "대기하지 말고 교체" 원칙에 따라 다시 시작되거나 교체됩니다. 전체 프로토콜 및 상태 머신은 modules/health-monitoring.md를 참조하세요.
모듈 참조
- team-management.md: 팀 수명주기, 구성 형식, 멤버 관리
- messaging-protocol.md: 메시지 유형, 인박스 작업, 잠금 패턴
- task-coordination.md: 작업 CRUD, 상태 머신, 의존성 순환 감지
- spawning-patterns.md: tmux 생성, CLI 플래그, 패널 관리
- crew-roles.md: 역할 분류, 능력 매트릭스, 역할-위험 호환성
- health-monitoring.md: 심박 프로토콜, 정지 감지, 자동 복구
Conjure와의 통합
Agent Teams는 conjure 위임 모델을 확장합니다.
| Conjure 패턴 | Agent Teams 동등 패턴 |
|---|---|
delegation-core:task-assessed | agent-teams:team-created |
delegation-core:handoff-planned | agent-teams:tasks-assigned |
delegation-core:results-integrated | agent-teams:team-shutdown |
| 외부 LLM 실행 | 팀원 에이전트 실행 |
먼저 Skill(conjure:delegation-core)를 사용하여 작업이 단일 서비스 위임보다 다중 에이전트 조정에 더 적합한지 판단하세요.
워크트리 격리 대안 (Claude Code 2.1.49+)
파일을 수정하는 병렬 에이전트의 경우 isolation: worktree는 파일시스템 기반 조정에 비해 가벼운 대안을 제공합니다. 각 에이전트는 자체 임시 git 워크트리에서 실행되어 공유 파일에 대한 fcntl 잠금이나 인박스 기반 충돌 회피가 필요 없습니다.
- 에이전트 팀 메시징보다 워크트리를 선호할 때: 에이전트가 겹치는 파일을 작업하지만 중간 실행 통신이 필요하지 않은 경우
- 에이전트 팀 메시징을 선호할 때: 에이전트가 서로의 진행 상황에 따라 발견 사항을 조정하거나 계획을 변경해야 하는 경우
- 둘 다 결합: 조정에는 에이전트 팀을 사용하고, 파일시스템 안전을 위해 팀원별로
isolation: worktree를 사용
문제 해결
일반적인 문제
tmux를 찾을 수 없음
패키지 관리자를 통해 설치: brew install tmux / apt install tmux
오래된 잠금 파일
에이전트가 작업 중간에 충돌하면 잠금 파일이 남을 수 있습니다. ~/.claude/teams/<team>/inboxes/ 또는 ~/.claude/tasks/<team>/에서 .lock 파일을 수동으로 제거하세요.
고아 작업
충돌한 에이전트가 요청한 작업은 in_progress 상태로 무기한 남습니다. 심박 기반 정지 감지 및 자동 작업 해제를 위해 modules/health-monitoring.md를 사용하세요. 건강 모니터링 프로토콜은 60초 + 30초 프로브 창 내에서 응답하지 않는 에이전트를 감지하고 작업을 재할당합니다.
메시지 순서 파일시스템 타임스탬프 해상도는 다양합니다(HFS+ = 1초 세분성). 빠른 메시지 폭발 시 충돌을 피하기 위해 번호가 매겨진 파일 이름이나 UUID 정렬 이름을 사용하세요.
Bedrock/Vertex/Foundry에서 모델 오류 (2.1.39 이전) 팀원 에이전트가 엔터프라이즈 제공업체에서 잘못된 모델 식별자를 사용하여 400 오류를 유발할 수 있습니다. 모든 제공업체에 대해 올바른 모델 ID 자격을 얻으려면 Claude Code 2.1.39+로 업그레이드하세요.
중첩 세션 가드 (2.1.39+)
claude가 기존 세션 내에서 실행을 거부하는 경우, 서브쉘 호출이 아닌 tmux 패널 분할을 사용하고 있는지 확인하세요. 가드는 의도적입니다. 자세한 내용은 modules/spawning-patterns.md를 참조하세요.
종료 조건
- 구성 및 디렉토리와 함께 팀 생성됨
- 팀원이 생성되고 구성에 등록됨
- 의존성 그래프(순환 없음)로 작업 생성됨
- 에이전트가 인박스 메시지를 통해 조정 중
- 정상 종료 완료됨