Claude Code Agent Teams 실전 - MCP 서버 + 병렬 에이전트로 PR 리뷰 파이프라인 구축하기

들어가며

지난 MCP 서버 직접 만들기에서 Spring Boot로 사내 시스템을 AI 에이전트에 연결하는 법을 봤습니다. MCP 서버가 있으면 Claude가 우리 데이터에 접근할 수 있죠. 그런데 막상 써보면 벽에 부딪힙니다. "PR이 50개 파일이면 Claude가 전부 순차로 리뷰하고 있어서 너무 오래 걸린다"는 문제입니다.

이 지점을 풀기 위해 2026년 2월 5일 Claude Code v2.1.32에 Agent Teams가 연구 프리뷰로 등장했습니다. Claude Code 2.1.x 완전 정리에서 이름만 언급됐던 기능이죠. Agent Teams는 기존 서브에이전트와 달리 동료 에이전트끼리 공유 task list를 통해 실시간 협업하는 구조입니다.

오늘은 Agent Teams와 앞에서 만든 MCP 서버를 결합해 "PR 리뷰 자동화 파이프라인"을 실전으로 구축합니다. 50개 파일 PR이 들어오면 보안·성능·스타일·테스트 관점의 전문 에이전트 4명이 동시에 달라붙어 리뷰하고, 결과를 집계해서 GitHub에 코멘트까지 남기는 워크플로우입니다.

1. Subagent vs Agent Teams - 뭐가 다른가

용어가 비슷해서 처음 보면 헷갈립니다. 핵심 차이를 먼저 정리합니다.

구분	Subagent (기존)	Agent Teams (신규)
커뮤니케이션	메인 ↔ 서브 단방향	동료 간 공유 task list
작업 분배	메인이 지시	에이전트가 직접 claim
충돌 방지	메인이 관리	task list로 자동 관리
동시성	가능하지만 독립적	조율된 병렬
적합 작업	격리된 탐색·리서치	파일 독립적 대량 작업
출시	2025년부터 지원	2026-02-05 (v2.1.32)
요구 모델	모든 Claude 모델	Opus 4.6 이상

한 문장 요약

Subagent는 "독립 연구원", Agent Teams는 "실시간 공유 화이트보드를 보며 일하는 동료들"입니다.

리서치 에이전트가 독립적으로 코드베이스를 탐색하는 건 Subagent, 50개 파일을 네 관점에서 분업해서 리뷰하는 건 Agent Teams입니다. 두 기능은 대체 관계가 아니라 다른 문제를 푸는 다른 도구입니다.

2. Agent Teams 아키텍처

Agent Teams의 핵심은 공유 task list입니다. 모든 에이전트가 읽고 쓸 수 있는 하나의 작업 보드를 보며 움직입니다.

3대 구성요소

1. Orchestrator (Lead Agent): 프로젝트를 작업 단위로 쪼개서 task list에 추가. 진행 상황 모니터링.
2. Specialist Agents: 각자 전문 도메인이 있는 하위 에이전트들. task list에서 자기 도메인에 맞는 작업을 집어 실행.
3. Shared Task List: 모든 에이전트가 접근 가능한 task 데이터. status(pending/in_progress/completed), outputs, owner 필드 포함.

라이프사이클

1. Orchestrator: 할 일 5개를 task list에 pending 상태로 추가
   ├─ task-1: controller.java 보안 리뷰
   ├─ task-2: controller.java 성능 리뷰
   ├─ task-3: controller.java 스타일 리뷰
   ├─ task-4: service.java 보안 리뷰
   └─ task-5: service.java 성능 리뷰

2. Security Agent: task-1을 claim (in_progress + owner 설정)
   Performance Agent: task-2를 claim
   Style Agent: task-3을 claim
   → 3명이 동시에 작업 시작

3. Security Agent: task-1 완료 → output 기록, completed 처리
   → 비어있는 동안 task-4를 claim하여 이어서 작업

4. 모든 task가 completed → Orchestrator가 결과 집계

왜 이 구조가 중요한가

• 중복 방지: task를 claim할 때 in_progress로 즉시 락을 걸어 두 에이전트가 같은 작업 실행 X
• 동적 로드 밸런싱: 빈 에이전트가 다음 pending task를 알아서 집어감
• 실패 격리: 한 에이전트가 실패해도 task는 pending으로 되돌려 다른 에이전트가 재시도 가능
• 관찰 가능: task list 자체가 진행 상황 대시보드 역할

3. 실전 시나리오 - PR 리뷰 파이프라인

실제로 만들어볼 워크플로우입니다. 사내 백엔드 팀이 쓸 PR 리뷰 자동화라고 가정합니다.

요구사항

• GitHub PR 번호를 입력하면 변경 파일을 분석
• 4개 관점에서 병렬 리뷰: 보안·성능·컨벤션·테스트 커버리지
• 각 관점별 코멘트를 취합해 PR에 단일 리뷰 코멘트로 작성
• 사내 코딩 가이드(MCP로 노출)를 모든 에이전트가 참조
• 크리티컬한 이슈 발견 시 Slack에 알림

전체 구성도

                    [Orchestrator Agent]
                            |
                            v
                    [Shared Task List]
                    /    |    |    \
                   v     v    v     v
         [Security] [Perf] [Style] [Test Coverage]
              |       |      |        |
              +-------+------+--------+
                      |
                      v
              [사내 코딩 가이드 MCP]
              [GitHub MCP]
              [Slack MCP]

4명의 specialist agent가 3개 MCP 서버(사내 가이드, GitHub, Slack)를 공유합니다. 여기서 "사내 코딩 가이드 MCP"는 MCP 서버 직접 만들기에서 만든 방식으로 구축한 서버입니다.

4. Step 1 - Specialist Agent 정의

Claude Code에서 서브에이전트는 .claude/agents/ 폴더에 Markdown 파일로 정의합니다. Agent Teams의 specialist들도 같은 방식입니다.

보안 리뷰 에이전트

# .claude/agents/security-reviewer.md
---
name: security-reviewer
description: 보안 관점 코드 리뷰 전문. OWASP Top 10, 취약점 패턴, 
  인증/권한 누락, SQL Injection, XSS, 민감정보 노출 탐지.
tools: [Read, Grep, Glob, mcp__coding-guide__get_security_rule]
model: opus
---

# Security Reviewer Agent

너는 코드의 보안 취약점을 찾는 전문가다.

## 분석 절차
1. 대상 파일을 Read로 확인
2. mcp__coding-guide__get_security_rule 로 사내 보안 규칙 조회
3. 다음 카테고리별로 점검:
   - 입력 검증 (Validation)
   - 인증/인가 (AuthN/AuthZ)
   - SQL Injection / NoSQL Injection
   - XSS / CSRF
   - 민감정보 로깅/노출
   - 의존성 취약점 암시
4. 각 발견 사항을 다음 포맷으로 기록:
   - 파일:라인
   - 심각도: CRITICAL | HIGH | MEDIUM | LOW
   - 설명 (2~3문장)
   - 수정 예시 코드

## 출력 규칙
- CRITICAL 발견 시 반드시 task output에 "severity: CRITICAL" 플래그 포함
- 확신이 없으면 MEDIUM 이하로만 표기
- 추측성 지적 금지

성능 리뷰 에이전트

# .claude/agents/performance-reviewer.md
---
name: performance-reviewer
description: 성능 관점 코드 리뷰. N+1 쿼리, 불필요한 반복, 
  동기 블로킹, 비효율적 자료구조, 캐싱 누락 탐지.
tools: [Read, Grep, Glob, mcp__coding-guide__get_performance_pattern]
model: opus
---

# Performance Reviewer Agent

## 주요 점검 항목
- JPA N+1: @OneToMany 컬렉션 접근, Fetch Join 누락
- 반복 I/O: 루프 내 DB 호출, 루프 내 HTTP 호출
- 비동기 가능한 블로킹 작업
- 큰 객체의 불필요한 복제
- 핫 경로에서 캐싱 가능한 계산

## 측정 불가능하면 지적하지 않기
증거 없이 "느릴 것 같다"는 지적은 하지 말 것. 
예) 명확한 O(N^2) 루프 발견 → 지적 OK
예) 이론적으로 느릴 수도 있는 정규식 → 벤치마크 없이는 지적 X

스타일/테스트 에이전트도 같은 패턴

style-reviewer와 test-coverage-reviewer도 동일한 구조로 작성합니다. 각 에이전트는 자기 전문 영역만 보고, 판단 기준은 프롬프트에 명시합니다.

5. Step 2 - Orchestrator 프롬프트

실제 사용은 사용자가 한 명령으로 트리거합니다. Slash Command로 래핑하는 게 표준입니다.

/review-pr 커맨드

# .claude/commands/review-pr.md
---
name: review-pr
description: GitHub PR 번호를 받아 4개 관점 병렬 리뷰 수행
---

# PR 리뷰 오케스트레이션

대상: PR #$1

## 실행 절차

### Phase 1 - 컨텍스트 수집
1. mcp__github__get_pull_request 로 PR 메타 조회
2. mcp__github__get_pr_files 로 변경 파일 목록 획득
3. 각 파일을 Read로 확인

### Phase 2 - Task 분배
변경 파일 N개 × 리뷰 관점 4개 = 총 (N*4)개 task 생성

TaskCreate로 다음과 같이 등록:
- 각 task의 subject: "{파일경로} - {관점}"
- description: 파일 경로, 대상 에이전트 명시

### Phase 3 - 병렬 실행
다음 4개 specialist agent를 병렬로 기동:
- security-reviewer
- performance-reviewer
- style-reviewer
- test-coverage-reviewer

각 에이전트는 자기 도메인 task를 TaskList로 조회해 claim 후 실행.

### Phase 4 - 결과 집계
모든 task가 completed 되면:
1. 파일별, 심각도별로 발견 사항을 그룹핑
2. 마크다운 리뷰 코멘트 작성
3. mcp__github__post_pr_comment 로 PR에 업로드
4. CRITICAL 발견이 있다면 mcp__slack__post_message 로 #backend-alert 알림

Claude Code 2.1.x의 Agent Teams는 TaskCreate/TaskList API를 내장 제공합니다. 별도 인프라 없이 메모리 기반 task list로 조율됩니다.

6. Step 3 - 사내 코딩 가이드 MCP 연결

모든 에이전트가 참조하는 사내 가이드는 앞서 만든 MCP 서버에서 제공합니다. Resource와 Tool로 각각 노출.

@McpTool(
    name = "get_security_rule",
    description = "사내 보안 규칙 조회. category는 auth | validation | crypto | logging 중 하나."
)
public SecurityRule getSecurityRule(
        @McpToolParam(description = "규칙 카테고리") String category) {
    return securityRuleRepository.findByCategory(category)
            .orElseThrow(() -> new IllegalArgumentException(
                "Unknown category: " + category));
}

@McpResource(
    uri = "guide://conventions/java",
    name = "java_conventions",
    description = "사내 Java 코딩 컨벤션 전체"
)
public String javaConventions() {
    return resourceLoader.loadMarkdown("java-conventions.md");
}

specialist 에이전트들은 자기 도메인에 맞는 MCP 도구만 허용됩니다. tools: [..., mcp__coding-guide__get_security_rule] 라인이 그 역할이죠. 최소 권한 원칙이 여기에도 적용됩니다.

7. Step 4 - 동시성과 레이트 리밋

4개 에이전트가 동시에 MCP 서버를 호출하면 부하가 4배로 튑니다. 여기서 주의할 포인트들.

MCP 서버 쪽 대비

@RestController
@RequestMapping("/mcp")
@RateLimiter(name = "mcp-default", fallbackMethod = "rateLimitFallback")
public class McpGatewayController {
    // ...
}

# application.yml
resilience4j:
  ratelimiter:
    instances:
      mcp-default:
        limit-for-period: 30      # 초당 30회
        limit-refresh-period: 1s
        timeout-duration: 500ms

Claude Code 쪽 조율

• 동시 에이전트 수: 2~5명이 스위트 스팟. 그 이상은 조율 비용이 병렬 이득을 잠식
• task 크기: 너무 잘게 쪼개면 overhead 증가. 파일 1개를 관점 1개로 보는 정도가 적당
• MCP 호출 최소화: 같은 규칙을 반복 조회하지 말고, Phase 1에서 한 번 로드하여 에이전트에 전달

실패 처리

specialist 하나가 timeout/오류로 실패하면 task는 자동으로 pending으로 돌아가지 않습니다. Orchestrator가 이를 감지해 재할당해야 합니다.

### Phase 3.5 - 실패 task 복구 (Orchestrator)
TaskList로 실패(status=failed or stuck) task 탐색:
- stuck 기준: in_progress 상태로 5분 이상 update 없음
- 실패 task의 owner 해제 후 pending으로 복귀
- 최대 2회까지만 재시도, 3회째 실패는 수동 리뷰 필요로 마킹

8. Step 5 - 결과 집계와 리포팅

4명이 각자 리뷰한 결과를 하나의 PR 코멘트로 합칩니다.

집계 규칙

• 심각도 내림차순으로 정렬 (CRITICAL → LOW)
• 같은 파일의 같은 라인에 중복 지적이 있으면 통합 (여러 관점에서 겹쳐 보일 때)
• 각 지적에 "어느 리뷰어가 올렸는지" 표기 (security / perf / style / test)
• 요약 섹션 맨 위에: 총 지적 수, 심각도별 집계, 결정 제안 (APPROVE / REQUEST_CHANGES / COMMENT)

코멘트 샘플

## 🤖 자동 리뷰 결과

**4개 관점 병렬 리뷰 완료 (총 리뷰 시간: 47초)**

| 심각도 | 건수 |
|-------|------|
| CRITICAL | 1 |
| HIGH | 3 |
| MEDIUM | 7 |
| LOW | 12 |

**제안: REQUEST_CHANGES** (CRITICAL 1건 이상 존재)

---

### 🔴 CRITICAL

**OrderController.java:45** [security]
- SQL Injection 가능성: `@Query(value = "SELECT * FROM orders WHERE id = " + id)` 
  concatenation 대신 named parameter 사용 필요
- 수정 예시:
  ```java
  @Query("SELECT o FROM Order o WHERE o.id = :id")
  Order findById(@Param("id") Long id);
  ```

### 🟠 HIGH
...

리뷰 품질은 결국 specialist 에이전트의 프롬프트에 달려있습니다. "추측성 지적 금지", "확신 없으면 낮은 심각도로" 같은 규칙을 반복 명시해야 리뷰어 피로도가 덜합니다.

9. 비용 - 이득이 손실을 넘기는 지점 찾기

병렬 에이전트는 비용도 병렬로 증가합니다. 냉정하게 계산해야 합니다.

비용 구조

항목	단일 에이전트	Agent Teams (4명)
컨텍스트 로드	1회	4회 (각자 파일 읽음)
LLM 토큰	기준	약 3~4배
MCP 호출	N회	N×4회 (최악)
총 비용	기준	약 3.5~5배
소요 시간	기준	약 1/3~1/4

경제성 판단 기준

• 시간 민감도 > 비용 민감도: 팀 전체가 리뷰 대기하는 시간 > 토큰 비용일 때만 병렬 정당화
• 파일 독립성: 파일 간 의존성이 높으면 오히려 순차 리뷰가 낫다
• 크리티컬리티: 프로덕션 긴급 배포 PR은 병렬, 일반 문서 PR은 순차

Opus 4.7 task_budget 활용

Opus 4.7에 도입된 task_budget 파라미터가 Agent Teams 비용 관리에 특히 유용합니다. 각 specialist마다 토큰 한도를 걸어 "에이전트가 루프 빠져 폭주"하는 사고를 방지할 수 있습니다.

// orchestrator가 subagent 실행 시
Agent({
  subagent_type: "security-reviewer",
  task_budget: {
    max_tokens: 80000,
    on_exceed: "return_partial"
  },
  ...
})

10. 관측 가능성 - 4개 에이전트의 움직임 추적

단일 에이전트 워크플로우와 달리, Agent Teams는 "누가 뭘 하고 있는지"를 실시간으로 파악하기 어렵습니다. OpenTelemetry 기반 관측이 필수.

핵심 지표

지표	의미
agent.active.count	활성 specialist 수 - 병렬도 관찰
task.pending.duration	task가 claim되기까지 걸린 시간
task.execution.duration	task 실행 시간 - 에이전트 성능 비교
agent.failure.rate	에이전트별 실패율 - 프롬프트 품질 지표
critical.findings.count	CRITICAL 발견 건수 - 시스템 헬스 관측

타임라인 시각화

4명의 에이전트가 어느 시점에 어떤 task를 claim/complete했는지 간트 차트로 보면 병목이 금방 드러납니다. task가 계속 pending에 쌓이면 specialist 수를 늘릴 타이밍이고, 반대로 한 명이 쉬는 시간이 길면 병렬도가 과도한 상태입니다.

11. 언제 Agent Teams를 쓰지 말아야 하는가

모든 걸 Agent Teams로 풀 필요는 없습니다. 오히려 독이 되는 상황들.

상황	왜 부적합	대안
순차 의존이 강한 작업	병렬화 불가능, 조율 비용만	단일 에이전트 + TaskList
작업 단위가 너무 작음	overhead > 이득	단일 에이전트 루프
프롬프트 튜닝 전 단계	4배 비용으로 빠른 피드백 불가	먼저 단일로 완성 후 병렬화
외부 API 레이트 리밋 타이트	MCP 호출 폭증으로 429	백엔드 확장 후 도입
간단한 질의응답	과잉 설계	Slash Command + Skill

도입 결정 체크리스트

1. 독립적으로 처리 가능한 sub-task가 5개 이상 있는가?
2. 전체 실행 시간이 2분 이상인가?
3. 3~4배 비용 증가를 감수할 만한 시간 절감이 있는가?
4. 각 sub-task가 파일/자원 충돌 없이 수행 가능한가?
5. Opus 4.6 이상 사용이 가능한가? (요구 사양)

5개 중 4개 이상 YES라면 Agent Teams 도입이 정당화됩니다. 2개 이하면 단일 에이전트 + Skill 조합이 더 경제적입니다.

마치며

Claude Code Agent Teams의 핵심 포인트를 정리합니다.

• Subagent와 Agent Teams는 다른 도구. Subagent는 격리된 독립 탐색, Agent Teams는 공유 task list 기반 실시간 협업. 용어 비슷해도 역할은 완전히 다릅니다. 잘못 고르면 과잉 설계 또는 병렬화 실패로 이어집니다.
• 공유 task list가 조율의 전부. 별도 메시지 큐나 워크플로우 엔진 없이 TaskCreate/claim/complete 사이클이 에이전트 협업의 토대입니다. 이 구조 덕에 실패 복구, 동적 로드 밸런싱, 관찰 가능성이 한 번에 해결됩니다.
• MCP 서버와의 조합이 진짜 가치. Agent Teams 자체만으로는 그냥 병렬 실행입니다. 사내 MCP 서버를 통해 도메인 지식과 실제 시스템에 연결돼야 "우리 회사 PR 리뷰"가 됩니다. 두 기술의 조합이 1+1=3의 핵심.
• 비용 증가 3.5~5배, 시간 감소 3~4배. 시간이 돈보다 비싼 상황(긴급 배포, 팀 전체 대기)에만 경제적. 일반 PR은 단일 에이전트가 더 싸고, 문제가 터질 때의 반응 속도가 중요하면 Agent Teams. 선택 기준을 명확히 해두면 비용 폭주 없이 쓸 수 있습니다.
• 2~5명이 스위트 스팟. 그 이상은 조율 비용이 이득을 먹습니다. 대부분의 실무 시나리오는 3~4명으로 충분하고, 더 많은 에이전트가 필요하다면 task를 더 크게 묶어 담당 범위를 키우는 게 낫습니다.

Skills로 팀의 지식을 코드화하고, MCP로 시스템을 연결하고, Agent Teams로 병렬 실행 — 이 세 축이 모이면 "AI가 동료처럼 일하는 팀"의 실체에 가까워집니다. Skills 가이드에서 말한 "프롬프트 엔지니어링 쳇바퀴에서 탈출"이 이 조합으로 비로소 실현됩니다. 다음 포스트에서는 이렇게 구축한 자동화 파이프라인을 실제 프로덕션에 올릴 때 마주치는 운영 이슈 — 로그 분석, 비용 이상 탐지, 품질 드리프트 모니터링 — 를 다뤄 볼 예정입니다.