여러 에이전트 팀을 띄웠지만 조율에 실패할 때 /agent-teams-team-communication-protocols가 메시징 규칙을 설정합니다. — Claude Skill

팀 커뮤니케이션 프로토콜

에이전트 팀원 사이의 효과적인 커뮤니케이션을 위한 프로토콜입니다. 메시지 유형 선택, 계획 승인 워크플로, 종료 절차, 피해야 할 흔한 안티패턴을 포함합니다.

사용 시점

• 새 팀의 커뮤니케이션 규범 설정
• 메시지 유형 선택(message, broadcast, shutdown_request)
• 계획 승인 워크플로 처리
• 정상적인 팀 종료 관리
• 팀원 정체성과 역량 발견

메시지 유형 선택

message(직접 메시지) — 기본 선택

특정 팀원 한 명에게 보냅니다:

{
  "type": "message",
  "recipient": "implementer-1",
  "content": "API 엔드포인트가 준비됐습니다. 이제 프런트엔드 폼을 만들 수 있습니다.",
  "summary": "프런트엔드용 API 엔드포인트 준비 완료"
}

사용 대상: 작업 업데이트, 조율, 질문, 통합 알림.

broadcast — 아껴서 사용

모든 팀원에게 동시에 보냅니다:

{
  "type": "broadcast",
  "content": "중요: 공유 types 파일이 업데이트됐습니다. 계속하기 전에 최신 변경을 가져오세요.",
  "summary": "공유 types 업데이트"
}

오직 다음에만 사용: 모두에게 영향을 주는 중요한 차단 이슈, 공유 리소스의 큰 변경.

왜 아껴야 하나요? 각 브로드캐스트는 팀원 수만큼 별도 메시지를 보내므로 팀 규모에 비례해 API 리소스를 소비합니다.

shutdown_request — 정상 종료

팀원에게 종료를 요청합니다:

{
  "type": "shutdown_request",
  "recipient": "reviewer-1",
  "content": "검토가 완료되어 팀을 종료합니다."
}

팀원은 shutdown_response로 응답합니다(승인 또는 사유가 있는 거절).

커뮤니케이션 안티패턴

계획 승인 워크플로

팀원이 plan_mode_required로 생성된 경우:

1. 팀원이 읽기 전용 탐색 도구로 계획을 만듭니다
2. 팀원이 ExitPlanMode를 호출해 리드에게 plan_approval_request를 보냅니다
3. 리드가 계획을 검토합니다
4. 리드가 plan_approval_response로 응답합니다:

승인:

{
  "type": "plan_approval_response",
  "request_id": "abc-123",
  "recipient": "implementer-1",
  "approve": true
}

피드백과 함께 거절:

{
  "type": "plan_approval_response",
  "request_id": "abc-123",
  "recipient": "implementer-1",
  "approve": false,
  "content": "API 호출에 대한 오류 처리를 추가하세요"
}

종료 프로토콜

정상 종료 순서

1. 리드가 각 팀원에게 shutdown_request 전송
2. 팀원이 요청 수신: type: "shutdown_request"가 있는 JSON 메시지로 받습니다
3. 팀원이 shutdown_response로 응답:
   • approve: true — 팀원이 상태를 저장하고 종료
   • approve: false + 사유 — 팀원이 계속 작업
4. 리드가 거절 처리 — 팀원이 끝날 때까지 기다린 뒤 다시 시도
5. 모든 팀원이 종료된 뒤 — Teammate cleanup 호출

거절 처리

팀원이 종료를 거절하면:

• 사유를 확인합니다(보통 "아직 작업 중")
• 현재 작업이 완료될 때까지 기다립니다
• 종료 요청을 다시 시도합니다
• 긴급하면 사용자가 강제 종료할 수 있습니다

팀원 발견

config 파일을 읽어 팀원을 찾습니다:

위치: ~/.claude/teams/{team-name}/config.json

구조:

{
  "members": [
    {
      "name": "security-reviewer",
      "agentId": "uuid-here",
      "agentType": "team-reviewer"
    },
    {
      "name": "perf-reviewer",
      "agentId": "uuid-here",
      "agentType": "team-reviewer"
    }
  ]
}

메시징과 작업 배정에는 항상 name을 사용합니다. agentId를 직접 사용하지 마세요.

문제 해결

팀원이 메시지에 응답하지 않습니다. 팀원의 작업 상태를 확인하세요. 유휴 상태라면 작업을 완료했고 새 작업 배정이나 종료를 기다리는 중일 수 있습니다. 아직 활성 상태라면 실행 중간일 수 있으며 현재 작업이 끝난 뒤 메시지를 처리합니다.

리드가 모든 상태 업데이트를 브로드캐스트합니다. 흔한 안티패턴입니다. 브로드캐스트는 비쌉니다. 하나당 N개의 메시지를 보냅니다. 지점 간 업데이트에는 직접 메시지(type: "message")를 사용하세요. 브로드캐스트는 업데이트된 인터페이스 계약처럼 중요한 공유 리소스 변경에 예약하세요.

팀원이 종료 요청을 예상과 다르게 거절했습니다. 팀원이 아직 작업 중입니다. shutdown_response content 필드의 거절 사유를 확인하고, 작업이 끝날 때까지 기다린 뒤 다시 시도하세요. 저장되지 않은 작업이 있는 팀원을 강제 종료하지 마세요.

plan_approval_request가 도착했지만 request_id가 없습니다. 팀원이 필요한 요청 맥락 없이 ExitPlanMode를 호출했습니다. 팀원에게 계획 모드에 다시 들어가 탐색을 완료하고 ExitPlanMode를 다시 호출하게 하세요. request_id는 계획 모드 시스템에서 자동으로 생성됩니다.

두 팀원이 서로를 기다리며 아무도 진행하지 못합니다. 교착 상태입니다. 둘 다 상대가 먼저 끝나기를 기다리며 막혀 있습니다. 리드는 한 팀원에게 직접 메시지로 스텁 또는 부분 결과를 보내 차단을 풀고 진행하게 해야 합니다.

관련 스킬

• team-composition-patterns — 커뮤니케이션 규범을 설정하기 전에 에이전트 유형과 팀 규모 선택
• parallel-feature-development — 병렬 구현 담당자 사이의 통합 인계를 조율하는 데 커뮤니케이션 프로토콜 사용