Claude 팀 에이전트 완전 가이드 — 개념부터 실전 셋업까지

💡 Tip. 바쁜 분들을 위한 본문 요약

• Agent Teams = 오케스트레이터가 팀메이트를 spawn하고, SendMessage로 직접 통신하는 구조
• 수동 오케스트레이션 대비: 사람 중계 제거, 진짜 병렬, 정보 유실 방지
• team-setup 스킬로 환경 감지 → tmux 레이아웃 → 팀 spawn까지 자동화
• 실제 캡처 3장으로 셋업 과정을 보여줌

---

수동 오케스트레이션의 한계 — 왜 팀 에이전트가 필요한가

#1에서 다뤘듯, session-sync.md로 4개 세션을 수동 중계하는 구조는 분명한 한계가 있었다. 정리하면:

• 모든 통신이 사람을 경유 → 사람이 병목
• 중계 과정에서 정보 유실 (타입 증발 사건)
• 에이전트 4명이 병렬이어도 중계하는 사람은 직렬

핵심 문제는 에이전트끼리 직접 대화할 수 없다는 것이었다. Agent Teams는 이걸 시스템 레벨에서 해결한다.

---

Agent Teams 아키텍처

구조는 단순하다:

• 오케스트레이터 (Lead): 팀을 만들고, 작업을 분배하고, 결과를 종합한다. claude --resume으로 세션 복구 가능.
• 팀메이트: 오케스트레이터가 spawn한 독립 에이전트. 각자의 컨텍스트 윈도우에서 작업. 일회성 — resume 불가.
• SendMessage: 에이전트 간 직접 통신. session-sync.md를 사람이 트리거하는 대신, 시스템이 라우팅.

핵심은 오케스트레이터가 유일한 진입점이라는 것이다. 사용자는 오케스트레이터에게만 지시하고, 오케스트레이터가 팀메이트에게 작업을 위임한다. 팀메이트끼리도 SendMessage로 직접 통신할 수 있어서, “BE가 API 스펙 바꿨으니 FE에 알려줘” 같은 중계를 사람이 할 필요가 없다.

각 팀메이트는 독립된 컨텍스트 윈도우를 가진다. 이건 장점이자 제약이다. 장점은 한 팀메이트의 컨텍스트가 터져도 다른 팀메이트에 영향이 없다는 것. 제약은 팀메이트 간 공유 상태가 없어서 필요한 정보는 반드시 메시지로 전달해야 한다는 것이다.

수동 오케스트레이션과 비교하면:

핵심 도구

• TeamCreate — 팀 생성. 팀 이름을 지정하면 오케스트레이터가 리드가 된다.
• Agent — 팀메이트 spawn. 이름, 작업 디렉토리, 역할을 지정. run_in_background: true로 병렬 생성.
• SendMessage — 에이전트 간 메시지. to: "backend"로 특정 팀메이트에게, to: "*"로 전체에게.
• TaskCreate / TaskList — 작업 추적. 칸반 보드처럼 작업을 생성하고 상태를 관리.

실제 오케스트레이터의 동작을 보면 이런 흐름이다:

사용자: "유저 API에 필터 추가하고, 프론트에 검색 UI 넣어줘"

오케스트레이터:
  1. TaskCreate("BE: 유저 API 필터 파라미터 추가")
  2. TaskCreate("FE: 검색 UI 컴포넌트 구현")
  3. SendMessage(to: "backend", "유저 목록 API에 name, role 필터 추가해줘")
  4. SendMessage(to: "frontend", "유저 검색 UI 만들어줘, API 스펙은 BE 완료 후 공유할게")
  5. BE 완료 보고 수신 → SendMessage(to: "frontend", "API 스펙: GET /users?name=&role=")
  6. FE 완료 보고 수신 → 양쪽 결과 검증 → 사용자에게 종합 보고

📌 핵심: 사용자는 한 번만 지시하면 된다. 분배, 동기화, 결과 종합은 오케스트레이터가 알아서 처리한다.

환경변수 설정

Agent Teams는 실험 기능이라 환경변수로 명시적 활성화가 필요하다.

# ~/.zshrc 또는 ~/.bashrc에 추가
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

설정 후 Claude Code를 재시작하면 TeamCreate, SendMessage 등 팀 관련 도구가 활성화된다. ~/.claude/settings.json에서 권한도 확인해야 한다:

{
  "permissions": {
    "allow": [
      "TeamCreate",
      "Agent",
      "SendMessage"
    ]
  }
}

⚠️ 주의: settings.json(권한/환경변수)과 .claude.json(UI/동작 설정)은 다른 파일이다. teammateMode 같은 옵션은 .claude.json에 들어간다.

알아야 할 제약

• 실험 기능 — 위 환경변수 없이는 팀 도구 자체가 보이지 않는다.
• 팀메이트는 일회성 — resume 불가. 세션 끊기면 새로 spawn해야 한다.
• 토큰 비용 — 팀메이트마다 별도 컨텍스트 윈도우를 소비한다. 3명 팀이면 토큰 사용량도 3배. Max Plan이 아니면 금방 한도에 도달한다.
• 간헐적 idle 미응답 — 팀메이트가 작업 완료 후 응답 없이 멈추는 경우가 있다. 재지시 또는 재spawn으로 해결.
• 파일 충돌 — 두 팀메이트가 같은 파일을 동시에 수정하면 나중에 쓴 쪽이 이긴다. Git Worktree로 분리하거나, 작업 영역을 명확히 나눠야 한다.

---

내가 쓰는 셋업: team-setup 스킬

이론은 여기까지.

실제로 매번 TeamCreate → Agent spawn → tmux 레이아웃을 수동으로 치는 건 번거롭다. 더 큰 문제는 팀 에이전트 생성과 서브에이전트 spawn을 혼동하는 경우가 자주 발생한다는 것이다. 매 세션마다 “팀 만들어줘”라고 하면 TeamCreate 대신 일반 서브에이전트를 spawn하거나, 팀 소속 없이 독립 에이전트를 띄우는 실수가 반복됐다.

그래서 이 과정을 자동화하는 스킬을 만들었다.

claude-code-bootstrap/skills/team-setup

Claude Code에서 PM(Lead) + 팀메이트(BE/FE/QA) 구조를 한 번에 셋업하는 스킬

github.com

/team-setup 슬래시 커맨드 하나로 환경 감지부터 팀 spawn까지 전부 자동화된다. 실제 사용 흐름을 캡처와 함께 보여주겠다.

1단계: /team-setup 진입

Claude Code에서 /team을 입력하면 스킬이 자동완성으로 뜬다. 선택하면 환경 감지가 시작된다.

2단계: 환경 감지 + 팀 구성

스킬이 자동으로 감지하는 것들:

• OS (WSL / macOS / Windows)
• tmux 설치 여부 + 현재 tmux 세션 안인지
• Agent Teams 환경변수 활성화 여부
• .claude/agents/에 커스텀 에이전트 정의가 있는지

환경에 따라 자동으로 모드를 선택한다:

3단계: 팀 spawn 완료

be+fe를 선택하면 스킬이 자동으로:

• Git Worktree 생성 (모노레포인 경우)
• tmux pane 분할 (main-vertical 레이아웃)
• TeamCreate + Agent spawn 실행
• 각 팀메이트가 CLAUDE.md를 읽고 코드베이스 파악 후 상태 보고

이후 오케스트레이터에서 자연어로 지시하면 된다. “backend에게 유저 조회 API에 필터 추가해달라고 해” — 이런 식이다.

💡 설정 파일 주의: ~/.claude/settings.json은 환경변수/권한 설정, ~/.claude.json은 UI/동작 설정(teammateMode 등). 이름이 비슷해서 헷갈리기 쉽다.

---

실전 운영 팁

에이전트 정의 파일을 만들어라

spawn할 때마다 역할과 규칙을 구두로 전달하는 건 비효율적이다. .claude/agents/ 디렉토리에 에이전트 정의 파일을 만들어두면 된다.

<!-- .claude/agents/team-backend.md -->
---
name: backend
description: NestJS 백엔드 담당
---

## 역할
- API 엔드포인트 구현, Prisma 스키마 관리
- 커밋 메시지: `feat(api):` 프리픽스 필수
- DB 마이그레이션 시 반드시 롤백 스크립트 포함

이렇게 정의해두면 /team-setup이나 Agent spawn 시 자동으로 로드된다. 매 세션마다 같은 규칙을 반복할 필요가 없고, 팀메이트의 행동이 일관된다.

작업 분리 전략: Worktree vs 디렉토리

팀메이트가 같은 파일을 건드리면 충돌이 난다. 두 가지 분리 전략이 있다:

• Git Worktree — 모노레포에서 팀메이트별 브랜치를 분리. isolation: "worktree" 옵션으로 Agent spawn 시 자동 생성된다. 작업 완료 후 오케스트레이터가 merge.
• 디렉토리 기반 — 프론트/백엔드가 물리적으로 분리된 경우 (apps/web, apps/api), 각 팀메이트의 작업 디렉토리를 다르게 지정하면 충돌 없이 병렬 작업이 가능하다.

📌 핵심: 어떤 전략이든, 작업 영역이 겹치지 않도록 오케스트레이터가 명확히 분배하는 게 핵심이다.

결과를 반드시 검증하라

“완료했습니다”가 실제로 맞는지는 별개다. 실제로 겪은 사례:

• cherry-pick 과정에서 코드 유실 — 파일이 존재하지만 변경 내용이 빠짐
• 엔티티를 모듈에 등록 안 함 — 빌드 통과, 런타임 500
• 프론트/백엔드 API 파라미터명 불일치 — 양쪽 빌드 통과, 연동 시 404

팀메이트가 “완료”라고 보고하면 오케스트레이터가 git diff로 변경 내용을 확인하고, 빌드/테스트를 돌려보는 게 좋다. 로컬에서 실제로 띄워보고 확인하는 게 최선이다.

세션 재시작 절차

팀메이트는 resume이 안 되므로, 세션이 끊기면:

1. claude --resume — 오케스트레이터 복구 (대화 이력 + 메모리 유지)
2. /team-setup 다시 실행 — 팀메이트 재생성
3. 각 레포에 CLAUDE.md가 있으므로 팀메이트도 프로젝트 컨텍스트를 자동 복구

오케스트레이터의 메모리 시스템이 프로젝트 컨텍스트를 보존한다. 덕분에 복구가 빠르다.

⚠️ 주의: 복구 후 이전 팀메이트의 미완료 작업이 있다면, 오케스트레이터에게 “이전 세션에서 BE가 하던 작업 이어줘”라고 지시하면 된다. 오케스트레이터가 대화 이력에서 맥락을 파악하고 새 팀메이트에게 위임한다.

---

📋 정리 — 언제 쓸까

아직 실험 기능이라 안정성은 부족하다. 간헐적으로 팀메이트가 멈추거나, spawn 자체가 실패하는 경우도 있다. 그래도 수동 오케스트레이션 대비 확실한 개선이다. session-sync.md에서 사람이 트리거하던 시절로는 안 돌아갈 것 같다.

---