topic★★★★★난이도 · 약 12분
서브에이전트 — 작업을 나눠서 병렬 처리
복잡한 작업을 여러 하위 에이전트에게 분배하여 동시에 처리하는 구조.
#서브에이전트#병렬#Agent 도구
왜 배우는가
하나의 에이전트가 모든 걸 순차적으로 하면 느리다. 서브에이전트를 활용하면 여러 파일을 동시에 분석하거나, 조사와 구현을 병렬로 진행할 수 있다.
Claude Code에는 Agent 도구가 있다. 메인 에이전트가 복잡한 작업을 만나면, 서브에이전트를 생성하여 일부 작업을 위임할 수 있다. 각 서브에이전트는 독립된 컨텍스트에서 작업한 뒤 결과를 메인에게 돌려준다.
| 구분 | 메인 에이전트 | 서브에이전트 |
|---|---|---|
| 역할 | 전체 작업 계획 · 결과 조합 | 개별 작업 실행 · 결과 반환 |
| 컨텍스트 | 전체 대화 맥락 보유 | 위임받은 작업 범위만 보유 |
| 도구 접근 | 모든 도구 사용 가능 | Read, Grep, Glob 등 조회 도구 위주 |
| 실행 방식 | 순차 또는 병렬 위임 | 독립 실행 후 결과 반환 |
병렬 실행의 장점 — 예를 들어 "프로젝트에서 사용하지 않는 import를 모두 찾아줘"라고 하면, 메인 에이전트가 폴더별로 서브에이전트를 나눠 보내서 동시에 검색한다. 순차 실행 대비 시간이 크게 단축된다.
언제 쓰면 좋은가? — (1) 여러 파일을 동시에 분석할 때, (2) 코드 리뷰처럼 여러 관점을 동시에 검토할 때, (3) 리서치와 구현을 나눠서 진행할 때. 단순한 한 파일 수정에는 서브에이전트가 불필요하다.
bash
# 사용자가 이런 지시를 하면 서브에이전트가 활성화될 수 있다:
# 예시 1: 광범위한 검색
"src 폴더의 모든 컴포넌트에서 접근성(a11y) 문제를 찾아줘"
# → 메인이 폴더별로 서브에이전트 분배
# 예시 2: 멀티 파일 리팩토링
"모든 API 호출을 새 클라이언트 래퍼로 마이그레이션해줘"
# → 파일 그룹별로 서브에이전트가 병렬 처리
# 예시 3: 비교 분석
"우리 프로젝트의 에러 처리 패턴을 분석하고 개선안을 제시해줘"
# → 조사 에이전트 + 분석 에이전트 병렬 실행서브에이전트는 사용자가 명시적으로 호출하는 것이 아니라, AI가 작업 규모를 판단하여 자동으로 활용한다.