이 글에는 제휴 링크가 없습니다.
Claude Code 서브에이전트 사용법 — 큰 일은 혼자 하지 말고 나눠 시키세요
Claude Code를 쓰다 보면 이런 순간이 옵니다. “코드베이스 전체에서 이거 어디서 쓰이는지 다 찾아줘” 같은 큰 조사를 시켰더니, 파일을 수십 개 읽으면서 대화창이 금세 무거워지고 정작 하려던 작업의 맥락이 흐려지는 거죠. 서브에이전트(subagent)는 이럴 때 큰 일을 별도 일꾼에게 통째로 떼어주는 기능입니다.
결론 요약
- 서브에이전트 = 메인 대화와 분리된 자기만의 컨텍스트를 가진 보조 AI 일꾼
- 쓸모 3가지: 컨텍스트 격리 · 병렬 처리 · 역할 전문화
- 큰 탐색·조사, 독립적으로 나눌 수 있는 작업, 결과 검증에 특히 유용
- 커스텀 에이전트는
/agents로 정의 — 역할·도구·모델을 지정해 재사용
🧩 1. 핵심은 “컨텍스트를 나눈다”는 것
Claude Code에서 대화가 길어질수록 요청당 소모가 커지고 초점이 흐려집니다(요금·한도 글에서 다룬 그 문제죠). 서브에이전트는 큰 작업을 자기만의 깨끗한 대화창을 가진 일꾼에게 위임합니다. 그 일꾼이 파일을 100개 읽든 뭘 하든, 메인 대화에는 최종 결론만 돌아옵니다. 중간 과정의 잡음이 내 메인 컨텍스트를 채우지 않아요.
이게 서브에이전트의 전부이자 핵심입니다 — 일을 나누는 게 아니라 맥락을 나누는 것.
📦 2. 언제 쓰면 좋은가 — 세 가지 상황
① 큰 탐색·조사 — “이 함수가 어디서 호출되는지 전부”, “이 라이브러리 쓰는 곳 다 찾아줘”처럼 파일을 많이 읽어야 답이 나오는 일. 결론만 필요하고 과정은 필요 없을 때 딱입니다.
② 병렬로 나눌 수 있는 일 — 서로 의존하지 않는 작업 여러 개를 동시에 돌릴 수 있습니다. 세 폴더를 각각 조사하는 일을 한 줄로 세우지 않고 세 일꾼에게 동시에 맡기는 식이죠. 저는 블로그 글감 조사를 여러 각도로 병렬로 돌릴 때 이렇게 씁니다.
③ 역할 전문화 — “코드 리뷰어”, “테스트 작성자”처럼 특정 역할에 맞춘 에이전트를 만들어두면, 그 관점으로만 집중해서 일합니다. 메인 에이전트는 지휘에 집중하고요.
⚙️ 3. 커스텀 서브에이전트 만들기 — /agents
가장 쉬운 시작은 그냥 자연어로 “이 조사는 서브에이전트한테 시켜줘”라고 부탁하는 겁니다. 하지만 반복해서 쓰는 역할은 커스텀으로 만들어두는 게 좋아요.
Claude Code 안에서 /agents를 치면 서브에이전트를 정의·관리하는 화면이 열립니다. 여기서 정하는 것:
- 역할(설명) — 언제 이 에이전트를 부를지. 잘 써두면 Claude가 알아서 적절한 순간에 호출합니다
- 도구 권한 — 이 에이전트가 쓸 수 있는 도구 범위 (예: 조사용은 읽기·검색만, 쓰기 금지)
- 모델 — 가벼운 일은 빠른 모델, 어려운 일은 강한 모델로
프로젝트에 저장하면 팀이 공유하고, 개인 전역으로 두면 모든 프로젝트에서 씁니다.
🔍 4. 훅과 뭐가 다른가
훅(hooks)과 헷갈리기 쉬운데, 방향이 정반대입니다.
- 훅 = 정해진 시점에 무조건 실행되는 규칙 (내가 시스템에 거는 강제)
- 서브에이전트 = 필요할 때 일을 떼어 맡기는 일꾼 (내가 판단해 위임)
강제해야 하면 훅, 나눠 맡기고 싶으면 서브에이전트 — 이렇게 기억하면 됩니다.
⚠️ 5. 주의 — 만능은 아닙니다
- 작은 일에는 오히려 손해. 서브에이전트를 부르는 것도 비용이라, 파일 한두 개 보는 일은 그냥 메인에서 하는 게 빠릅니다
- 위임한 일은 과정이 안 보입니다. 결론만 오니, 중요한 작업은 그 결론을 다시 확인하세요 — AI 산출물 검증의 원칙 그대로
- 컨텍스트가 격리된다는 건, 서브에이전트가 메인 대화의 세세한 맥락을 모른다는 뜻이기도 합니다. 위임할 때 필요한 배경을 충분히 적어주세요
🎯 시작 코스
- 다음에 “코드베이스 전체에서 ~ 찾아줘” 같은 큰 조사가 생기면, 서브에이전트로 시켜보기
- 익숙해지면
/agents로 자주 쓰는 역할(리뷰어·조사원) 하나 정의 - 서로 독립적인 작업이 여러 개일 때 병렬로 나눠 맡기기
사용법 · MCP 연결 · 훅까지 왔다면, 서브에이전트는 Claude Code를 “혼자 일하는 도구”에서 “팀을 지휘하는 자리”로 바꿔주는 마지막 조각입니다.
기준: 2026-09-07 실사용 구성. 명령·기능은 버전에 따라 달라질 수 있으니 공식 문서(code.claude.com/docs)를 함께 확인하세요. 다이어그램은 직접 제작했습니다.