Claude Code Agent Teams 실전 가이드 — 병렬 에이전트 설정부터 실전 시나리오까지

2026년 2월, Claude Opus 4.6과 함께 Agent Teams가 출시됐어요.

기존:
Claude Code 1개 → 순서대로 처리
API 레이어 → DB 레이어 → 테스트 → 문서화
(순차 실행)

Agent Teams:
Claude Code 여러 개 → 동시에 처리
Agent 1: API 레이어
Agent 2: DB 레이어       → 동시 실행
Agent 3: 테스트 작성
Agent 4: 코드 리뷰

단순히 여러 창을 띄우는 게 아니에요. 에이전트들이 서로 소통하고 조율해요.

---

Agent Teams vs Subagents — 뭐가 다른가

헷갈리기 쉬운 개념이에요.

Subagents:
→ 메인 세션이 작업 위임
→ 서브에이전트는 결과만 보고
→ 서브에이전트끼리 직접 소통 불가
→ 단순 병렬 처리

Agent Teams:
→ 에이전트끼리 직접 소통 가능
→ 서로 결과 공유하고 검토
→ 한 에이전트 결과가 다른 에이전트 작업에 영향
→ 진짜 협업

예시:

Subagents 방식:
리드 → "API 분석해" → Subagent 1 → 결과 보고
리드 → "DB 분석해" → Subagent 2 → 결과 보고
(독립적으로 각자 작업)

Agent Teams 방식:
Agent 1이 API 취약점 발견
→ 직접 Agent 2에게 메시지: "이 API가 DB에 어떻게 접근하는지 확인해줘"
→ Agent 2가 DB 레이어 분석 후 답변
→ 두 결과를 합쳐서 더 완전한 분석

---

활성화 방법

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

또는 환경변수로:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

주의: Opus 4.6 이상 필요. Pro 플랜($20) 가능하지만 하루 2~3회 한도. Max 플랜($100~200) 권장.

---

기본 사용법

# 에이전트 팀 생성
> 우리 인증 시스템을 리뷰하는 에이전트 팀 만들어줘.
  세 명의 팀원을 소환해:
  - 보안 리뷰어: 취약점, 토큰 처리, 세션 관리 감사
  - 성능 분석가: 응답 시간, 병목 지점 파악
  - 테스트 커버리지 체커: 엣지 케이스, 테스트 누락 확인
  서로 결과를 공유하고 검토해줘.

Claude Code가 자동으로:

1. 팀 리드 세션 (현재 세션) 설정
2. 팀원 3개 생성
3. 공유 태스크 리스트 배포
4. 에이전트 간 소통 채널 열기

---

키보드 단축키

Shift+↑/↓:  팀원 세션 선택
Ctrl+T:      공유 태스크 리스트 보기
Enter:       선택한 세션 열기
Escape:      현재 에이전트 중단

---

태스크 의존성 관리

에이전트들이 같은 파일을 건드리면 충돌이 나요. Agent Teams는 자동으로 의존성을 관리해요.

좋은 태스크 분해:
├── Agent 1: 인증 모듈 분석 (독립)
├── Agent 2: DB 레이어 분석 (독립)
├── Agent 3: API 엔드포인트 분석 (독립)
└── Agent 4: 위 결과 취합 + 보안 갭 파악 (1,2,3 완료 후)

나쁜 태스크 분해:
├── Agent 1: 버그 전부 고쳐 (너무 광범위)
└── Agent 2: Agent 1 기다리기 (불필요한 의존성)

Agent 4는 1, 2, 3이 끝날 때까지 자동으로 대기해요. 수동으로 관리할 필요 없어요.

---

Git Worktrees와 함께 쓰기

여러 에이전트가 같은 파일 수정하면 충돌이 나요. Worktrees로 각 에이전트에 독립된 작업 공간을 줘요.

# 각 에이전트가 별도 브랜치에서 작업
> 세 개의 독립된 기능을 병렬로 개발하는 팀 만들어줘.
  각 에이전트는 별도 worktree를 사용해:
  - Agent 1: feature/payment-refactor 브랜치
  - Agent 2: feature/auth-update 브랜치
  - Agent 3: feature/api-v2 브랜치

각 에이전트가 완전히 독립된 환경에서 작업해요. 충돌 없이 병렬 개발 가능해요.

주의: .env 파일은 기본으로 worktree에 복사 안 돼요.

# .worktreeinclude 파일 만들기
echo ".env" >> .worktreeinclude
echo ".env.local" >> .worktreeinclude
echo "config/local.json" >> .worktreeinclude

---

실전 시나리오 3가지

시나리오 1 — 코드베이스 보안 감사

> 코드베이스 보안 취약점 감사 팀 만들어줘.
  에이전트 4명:
  1. 인증 리뷰어: 인증 플로우, 세션 처리 감사
  2. 인풋 검증 리뷰어: 모든 사용자 입력 체크
  3. DB 보안 리뷰어: 쿼리, 데이터 접근 패턴 분석
  4. 통합 리뷰어: API 경계, 외부 연동 확인
  서로 발견한 내용 공유하고 결론 검토해줘.

순차 실행 대비 시간: 4배 감소

시나리오 2 — 대규모 리팩토링

> API, DB, 프론트엔드를 동시에 리팩토링하는 팀 만들어줘.
  - Agent 1 (feat/api-refactor): REST API를 OpenAPI 스펙으로 정리
  - Agent 2 (feat/db-optimize): 쿼리 최적화, 인덱스 추가
  - Agent 3 (feat/ui-update): API 변경에 맞춰 프론트 업데이트
  각자 별도 브랜치에서 작업해줘.

시나리오 3 — 기능 개발 + 리뷰 동시

> 결제 기능 개발 팀 만들어줘.
  - Agent 1: 결제 API 구현
  - Agent 2: Agent 1 코드 실시간 리뷰하고 피드백
  - Agent 3: 테스트 코드 작성 (Agent 1 진행과 병렬로)

코드 작성하면서 동시에 리뷰와 테스트가 진행돼요.

---

토큰 비용 현실

단일 세션 대비 Agent Teams:
팀원 3명 = 3~4배 토큰 소모

시간은 3배 빠른데 비용도 3~4배
→ 시간 가치 > 비용이면 의미 있음
→ 단순 작업엔 낭비

Agent Teams가 가성비 좋은 경우:

✅ 여러 레이어에 걸친 대규모 리팩토링
✅ 보안/성능/품질 다각도 동시 감사
✅ 독립적인 기능 여러 개 병렬 개발
✅ 코드 작성 + 리뷰 + 테스트 동시 진행

Agent Teams 쓰지 말아야 하는 경우:

❌ 순서가 있는 작업 (A 끝나야 B 시작)
❌ 같은 파일 수정이 많은 작업
❌ 간단한 버그 수정
❌ 작은 기능 추가

---

Subagents vs Agent Teams vs 단일 세션 선택 기준

단일 세션:
→ 일반 개발, 소규모 수정
→ 순서가 있는 작업
→ 빠른 처리 필요

Subagents:
→ 독립적인 리서치 위임
→ 결과 취합해서 하나의 결론
→ 중간 소통 불필요

Agent Teams:
→ 에이전트끼리 결과 공유 필요
→ 서로 검토하고 개선
→ 여러 레이어 동시 작업
→ 복잡한 협업 시나리오

---

팀 종료

# 작업 완료 후
> 모든 팀원에게 작업 완료 확인하고 종료해줘.
  결과를 REPORT.md로 취합해줘.

# 또는 직접
/team shutdown

 

📌 관련 글

Claude Advisor Strategy

Claude Advisor Strategy 실전 가이드 — Opus 성능을 Sonnet 비용으로

Claude Code로 레거시 코드 리팩토링

Claude Code로 레거시 코드 리팩토링하기 — 실전 워크플로우