Claude Code 서브에이전트는 한마디로, AI가 혼자 다 하는 게 아니라 다른 AI에게 일부 작업을 맡기는 구조입니다. 결론부터 말하면, 복잡한 작업을 여러 조각으로 나눠서 동시에 처리할 수 있기 때문에 작업 속도와 품질이 달라져요. 다만 모든 상황에서 좋은 건 아닙니다.
Claude Code 서브에이전트, 쉽게 이해하기
서브에이전트를 이해하려면 회사 조직을 떠올리면 됩니다.
- 메인 에이전트 = 팀장. 전체 작업을 파악하고, 누구에게 뭘 시킬지 결정합니다
- 서브에이전트 = 팀원. 팀장이 맡긴 특정 작업만 집중해서 처리해요
예를 들어 “한국 반도체 산업 보고서를 만들어줘”라고 요청하면, 메인 에이전트가 혼자 검색하고, 정리하고, HTML 파일까지 만드는 게 기본 동작이에요. 그런데 작업이 복잡하면 메인 에이전트가 스스로 판단해서 서브에이전트를 호출합니다.
- 서브에이전트 A → 시장 규모 데이터를 검색하고 정리
- 서브에이전트 B → 경쟁사 비교표를 작성
- 서브에이전트 C → 코드 분석이 필요한 부분을 처리
각 서브에이전트가 결과를 가져오면, 메인 에이전트가 이걸 합쳐서 최종 보고서를 완성합니다. 사용자 입장에서는 하나의 요청을 했을 뿐인데, 내부적으로 여러 AI가 협업한 셈이에요.
실제로 서브에이전트가 작동하는 모습
Claude Code를 터미널에서 쓰다 보면, 가끔 이런 표시가 보입니다.
⏳ Spawning subagent for research...
⏳ Spawning subagent for code analysis...이게 바로 서브에이전트가 생성되는 순간이에요. 대표적인 사례를 정리하면 이렇습니다.
1. 리서치 에이전트
보고서를 작성할 때, 웹 검색을 담당하는 서브에이전트가 따로 뜹니다. 메인 에이전트는 전체 구조를 잡고 글을 쓰는 동안, 서브에이전트가 검색 결과를 모아서 전달해요. 여러 검색을 병렬로 처리하니까 시간이 줄어듭니다.
2. 코드 분석 에이전트
큰 프로젝트의 파일 여러 개를 동시에 읽어야 할 때 서브에이전트가 유용합니다. 메인 에이전트가 파일 하나하나 읽으면 오래 걸리는데, 서브에이전트에게 “이 폴더의 파일들을 읽고 요약해줘”라고 시키면 빠르게 처리돼요.
3. 파일 수정 에이전트
여러 파일을 동시에 수정해야 하는 작업에서도 서브에이전트가 등장합니다. 예를 들어 “이 폴더에 있는 HTML 파일 10개의 헤더를 모두 바꿔줘” 같은 요청이면, 서브에이전트가 파일별로 나눠서 처리하는 방식이에요.
서브에이전트가 유용한 경우
- 작업 범위가 넓을 때 — 파일이 많거나, 검색할 내용이 여러 갈래일 때
- 병렬 처리가 가능할 때 — 서로 독립적인 작업이라 동시에 진행해도 되는 경우
- 긴 보고서를 만들 때 — 섹션별로 나눠서 작성하면 품질이 더 좋아질 수 있어요
서브에이전트가 오히려 비효율적인 경우
서브에이전트가 만능은 아닙니다. 오히려 불필요한 상황도 있어요.
- 단순한 질문 — “이 파일 읽어줘”, “오늘 날씨 알려줘” 같은 건 메인 에이전트 혼자 처리하는 게 빠릅니다
- 순차적으로 해야 하는 작업 — A 결과를 봐야 B를 할 수 있는 경우, 병렬 처리 자체가 불가능해요
- 컨텍스트가 중요한 작업 — 서브에이전트는 메인 에이전트의 전체 대화 맥락을 다 알지 못합니다. 앞뒤 흐름이 중요한 작업이면 메인 에이전트가 직접 하는 게 나아요
특히 세 번째가 중요합니다. 서브에이전트는 메인 에이전트가 전달한 지시사항만 받아서 일합니다. “아까 우리가 논의한 내용을 반영해서”라는 식의 맥락은 서브에이전트에게 전달되지 않을 수 있어요.
비개발자가 알아두면 좋은 점
서브에이전트는 사용자가 직접 호출하는 게 아닙니다. Claude Code가 작업 복잡도를 보고 알아서 판단해요. 그래서 사용자 입장에서 특별히 해야 할 건 없습니다.
다만 이런 점은 알아두면 좋습니다.
- 토큰 사용량이 늘어납니다 — 서브에이전트도 AI 모델을 사용하니까, 메인 에이전트만 쓸 때보다 토큰 소모가 많아요
- 작업 시간이 길어질 수 있습니다 — 서브에이전트를 생성하고 결과를 취합하는 과정이 추가되니까, 단순한 작업이면 오히려 느려질 수 있어요
- 결과의 일관성을 확인하세요 — 서브에이전트끼리 같은 용어를 다르게 쓰거나, 숫자가 미세하게 다를 수 있습니다. 최종 결과물을 한 번 훑어보는 게 좋아요
정리하면
서브에이전트는 “AI가 AI에게 일을 시키는 구조”입니다. 복잡한 작업을 분업으로 처리하니까 효율이 올라가지만, 단순한 작업에서는 오히려 오버헤드가 될 수 있어요. 비개발자라면 이런 구조가 있다는 걸 알아두고, 결과물의 일관성만 한 번 확인하면 충분합니다.
Claude Code를 쓰면서 “갑자기 여러 작업이 동시에 돌아가는 것 같은데?”라는 느낌을 받았다면, 그게 바로 서브에이전트가 작동하고 있는 거예요.