8장: 서브에이전트와 에이전트 팀 활용하기

왜 멀티 에이전트가 필요한가

단일 Claude Code 세션은 강력하지만, 복잡한 프로젝트에서는 한계에 부딪힐 수 있습니다. 프론트엔드와 백엔드를 동시에 수정하거나, 여러 마이크로서비스에 걸친 변경을 처리하거나, 리팩터링과 테스트 작성을 병행하는 경우가 그렇습니다.

Claude Code는 이러한 상황을 위해 두 가지 멀티 에이전트 패턴을 제공합니다: 서브에이전트(Subagent)와 에이전트 팀(Agent Teams)입니다. 각각의 구조와 적합한 사용 사례가 다르므로 목적에 맞게 선택해야 합니다.

서브에이전트

개념

서브에이전트는 메인 에이전트가 특정 작업을 위임하기 위해 생성하는 자식 에이전트입니다. 메인 에이전트의 세션 내에서 실행되며, 작업이 완료되면 결과를 메인 에이전트에 보고합니다.

핵심 특징은 다음과 같습니다.

• 메인 에이전트가 작업을 분배하고 결과를 취합합니다
• 서브에이전트 간에는 직접 통신이 불가능합니다
• 각 서브에이전트는 독립적인 컨텍스트를 가집니다
• 메인 에이전트의 컨텍스트를 오염시키지 않습니다

서브에이전트가 적합한 경우

• 독립적인 하위 작업을 병렬로 처리할 때
• 큰 작업을 작은 단위로 분할하여 컨텍스트 효율을 높일 때
• 탐색적 분석(코드베이스 조사, 패턴 검색 등)을 위임할 때

서브에이전트 활용 예시

Claude Code에서 직접 서브에이전트 사용을 요청할 수 있습니다.

다음 작업을 서브에이전트로 병렬 처리해 줘:

1. components/ 디렉토리의 모든 컴포넌트에서 
   deprecated API 사용을 찾아서 목록을 만들어 줘

2. lib/utils/에 있는 유틸리티 함수 중 
   테스트가 없는 것을 찾아서 목록을 만들어 줘

3. app/api/ 라우트 중 에러 처리가 
   누락된 것을 찾아서 목록을 만들어 줘

스킬에서 서브에이전트를 활용하는 것도 가능합니다. 6장에서 다룬 것처럼 SKILL.md의 프론트매터에 agent: true를 설정하면 해당 스킬이 서브에이전트로 실행됩니다.

---
name: audit
description: "코드베이스를 여러 관점에서 감사합니다"
agent: true
---
 
# 코드 감사 스킬
 
서브에이전트로 실행되어 메인 세션의 컨텍스트에 영향을 주지 않습니다.
 
## 검사 항목
1. TypeScript any 타입 사용 현황
2. console.log 잔존 여부
3. 하드코딩된 환경 값
4. 미사용 import
5. 비동기 에러 처리 누락
 
각 항목별 파일 목록과 라인 번호를 보고합니다.

에이전트 팀

개념

에이전트 팀(Agent Teams)은 여러 Claude Code 세션이 독립적으로 동작하면서 서로 소통하는 협업 시스템입니다. 서브에이전트와의 가장 큰 차이는 팀원 간 직접 통신이 가능하다는 점입니다.

서브에이전트에서는 팀원 A의 발견을 팀원 B에게 전달하려면 메인 에이전트를 거쳐야 합니다. 에이전트 팀에서는 팀원끼리 직접 메시지를 주고받고, 공유 작업 목록에서 할 일을 가져가며, 서로의 작업 결과를 참조할 수 있습니다.

에이전트 팀 활성화

에이전트 팀은 실험적 기능으로, 명시적으로 활성화해야 합니다.

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

또는 환경 변수로 설정합니다.

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

에이전트 팀 사용 예시

에이전트 팀으로 다음 작업을 수행해 줘:

팀원 1 (프론트엔드):
- app/dashboard/ 페이지를 리디자인해 줘
- 새 컴포넌트가 필요하면 직접 만들어 줘

팀원 2 (백엔드):
- dashboard에 필요한 API 엔드포인트를 구현해 줘
- 팀원 1이 만드는 UI에 맞는 응답 형식을 제공해 줘

팀원 3 (테스트):
- 팀원 1, 2의 작업이 진행되면 각각에 대한 테스트를 작성해 줘

에이전트 팀이 적합한 경우

• 프론트엔드/백엔드 동시 개발처럼 상호 의존적인 작업
• 한 팀원의 결과가 다른 팀원의 작업에 영향을 미치는 경우
• 대규모 마이그레이션이나 리팩터링에서 여러 모듈을 동시에 수정할 때

서브에이전트 vs 에이전트 팀

두 패턴의 선택 기준을 정리합니다.

실전 활용 패턴

패턴 1: 코드베이스 탐색 분할

대규모 코드베이스에서 정보를 수집할 때 서브에이전트로 병렬 탐색합니다.

이 프로젝트의 기술 부채를 분석해 줘.
서브에이전트를 사용해서 다음을 병렬로 조사해 줘:

1. 타입 안전성: any 사용, 타입 단언(as), 타입 가드 누락
2. 의존성: 오래된 패키지, 미사용 패키지, 보안 취약점
3. 코드 품질: 중복 코드, 과도한 복잡도, 매직 넘버
4. 테스트: 커버리지 공백, 불안정한 테스트

결과를 취합해서 우선순위별 개선 계획을 제안해 줘.

패턴 2: 풀스택 기능 개발

프론트엔드와 백엔드를 동시에 개발할 때 에이전트 팀을 활용합니다.

사용자 알림 기능을 에이전트 팀으로 개발해 줘.

팀원 구성:
- API 담당: app/api/notifications/ 라우트 구현
  - GET: 알림 목록 조회 (페이지네이션)
  - PATCH: 읽음 처리
  - DELETE: 삭제
  
- UI 담당: 알림 드롭다운 컴포넌트 구현
  - Header에 알림 아이콘과 뱃지
  - 드롭다운으로 알림 목록 표시
  - 읽음/삭제 액션

- 테스트 담당: 두 팀원의 코드에 대한 테스트 작성

패턴 3: 대규모 마이그레이션

라이브러리 업그레이드 등 여러 파일을 동시에 수정해야 할 때 서브에이전트를 사용합니다.

React Query v4에서 v5로 마이그레이션해 줘.
서브에이전트로 디렉토리별 병렬 처리해 줘:

1. app/ 디렉토리의 페이지 컴포넌트
2. components/ 디렉토리의 공유 컴포넌트
3. hooks/ 디렉토리의 커스텀 훅
4. lib/api/ 디렉토리의 API 래퍼

각 서브에이전트는:
- import 경로 변경
- useQuery/useMutation API 변경사항 적용
- deprecated 옵션 교체
- 변경 파일 목록과 수정 내용 요약 보고

비용과 성능 고려사항

토큰 사용량

멀티 에이전트를 사용하면 토큰 사용량이 비례하여 증가합니다.

• 서브에이전트 3개: 단일 세션 대비 약 3-4배
• 에이전트 팀 3명: 단일 세션 대비 약 3-4배 + 통신 오버헤드

비용이 중요한 환경에서는 작업의 복잡도와 시간 절약 효과를 고려하여 멀티 에이전트 사용 여부를 결정합니다.

실행 시간

서브에이전트는 생성 후 20-30초 내에 작업을 시작합니다. 단순 작업이라면 직접 처리하는 것이 더 빠를 수 있습니다. 병렬 처리의 이점은 각 작업이 최소 수 분 이상 소요될 때 두드러집니다.

충돌 관리

여러 에이전트가 같은 파일을 동시에 수정하면 충돌이 발생할 수 있습니다. 이를 방지하는 전략은 다음과 같습니다.

• 작업 범위를 디렉토리 단위로 명확히 분리합니다
• 공유 파일(설정, 타입 정의 등)의 수정은 한 에이전트에게만 맡깁니다
• 에이전트 팀에서는 팀 리더가 충돌을 감지하고 조율합니다

정리

서브에이전트와 에이전트 팀은 Claude Code의 병렬 처리 능력입니다.

• 서브에이전트: 독립적인 작업을 병렬 처리하며, 메인 에이전트가 중앙에서 조율합니다
• 에이전트 팀: 상호 의존적인 작업을 팀원 간 직접 소통하며 협업 처리합니다
• 작업의 독립성과 상호 의존성에 따라 적절한 패턴을 선택합니다
• 토큰 비용이 비례 증가하므로 복잡도와 시간 절약을 고려하여 판단합니다

다음 장에서는 Claude Code를 Git 워크플로우와 CI/CD 파이프라인에 통합하는 방법을 다룹니다.