본문으로 건너뛰기

서브에이전트 패턴

서브에이전트는 메인 대화에서 분리된 독립 에이전트에게 작업을 위임하는 시스템입니다. 각 서브에이전트는 자체 컨텍스트에서 실행되어 메인 대화의 컨텍스트를 보호하면서 복잡한 작업을 병렬로 처리할 수 있습니다.

빌트인 서브에이전트​

Claude Code에는 상황에 맞게 자동으로 사용되는 서브에이전트가 내장되어 있습니다:

서브에이전트모델도구용도
Explore상속 (Opus 상한)읽기 전용파일 탐색, 코드 검색, 코드베이스 이해
Plan상속읽기 전용플랜 모드에서 코드베이스 조사
general-purpose상속전체복잡한 리서치, 멀티스텝 작업, 코드 수정
Bash상속-별도 컨텍스트에서 터미널 명령 실행
statusline-setupSonnet-/statusline 설정 시 사용
Claude Code GuideHaiku-Claude Code 기능 질문 답변

Claude는 작업 특성에 따라 자동으로 적절한 서브에이전트를 선택합니다. Explore는 코드베이스 탐색에, general-purpose는 수정이 필요한 복잡한 작업에 사용됩니다. Explore는 v2.1.198부터 Haiku 대신 메인 세션의 모델을 상속합니다(Opus 상한).

서브에이전트의 핵심 특성​

컨텍스트 분리​

서브에이전트는 메인 대화와 독립된 컨텍스트에서 실행됩니다. 결과만 요약되어 메인 대화에 반환됩니다. 이를 통해:

  • 컨텍스트 보호: 탐색 결과가 메인 컨텍스트를 차지하지 않음
  • 병렬 처리: 여러 서브에이전트를 동시에 실행 가능
  • 격리된 실험: 실패해도 메인 대화에 영향 없음

중첩 (최대 5단계)​

v2.1.172부터 서브에이전트는 자신의 서브에이전트를 생성할 수 있습니다 — 최대 5단계 깊이까지. 이전에는 서브에이전트가 다른 서브에이전트를 만들 수 없어 중첩 위임에 Skills나 순차 체이닝이 필요했지만, 이제 서브에이전트가 직접 하위 작업을 다시 위임할 수 있습니다.

깊이는 포그라운드·백그라운드 모두 동일하게 5단계로 제한됩니다(무한 중첩 방지, v2.1.181에서 포그라운드도 동일 제한 적용).

포그라운드 vs 백그라운드​

v2.1.198부터 서브에이전트는 기본적으로 백그라운드에서 실행됩니다. 서브에이전트가 작업하는 동안 Claude는 메인 대화에서 계속 작업하고, 완료되면 알림을 받습니다.

백그라운드 (기본)포그라운드
동작메인 대화와 동시에 작업 진행완료까지 메인 대화 차단
권한권한 프롬프트가 메인 세션에 표시대화형 권한 프롬프트
실패 시포그라운드로 resume 가능즉시 대화형 수정

백그라운드 서브에이전트의 권한 요청은 자동 거부되지 않고 메인 세션에 대화상자로 표시됩니다(v2.1.186) — 어떤 에이전트가 요청했는지 함께 보여주며, Esc를 누르면 해당 요청만 거부됩니다.

서브에이전트 Resume​

서브에이전트가 완료된 후 이어서 작업시킬 수 있습니다:

> code-reviewer 서브에이전트로 인증 모듈 리뷰해줘
[에이전트 완료]

> 그 코드 리뷰를 이어서 인가 로직도 분석해줘
[이전 컨텍스트를 유지한 채 서브에이전트 재개]

Resume된 서브에이전트는 이전 도구 호출, 결과, 추론을 모두 유지합니다.

서브에이전트 비활성화​

특정 서브에이전트를 차단할 수 있습니다:

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}
# CLI 플래그로
claude --disallowedTools "Agent(Explore)"
Task → Agent 이름 변경

버전 2.1.63에서 Task 도구가 Agent로 이름이 변경되었습니다. 기존 Task(...) 참조는 호환성을 위해 별칭으로 계속 동작합니다.

실전 활용 패턴​

병렬 코드 분석​

> 프론트엔드 성능 문제와 백엔드 API 응답 시간을 동시에 분석해줘

Claude가 자동으로 여러 서브에이전트를 생성하여 병렬로 분석하고 결과를 종합합니다.

대규모 리팩토링​

> 모든 API 엔드포인트에 에러 핸들링을 추가해줘

각 엔드포인트를 별도 서브에이전트에서 처리하여 컨텍스트를 효율적으로 관리합니다.

멀티스텝 워크플로우​

> 1. DB 스키마 분석하고
  2. 마이그레이션 작성하고
  3. 테스트 작성해줘

각 단계를 서브에이전트에게 위임하고 결과를 순차적으로 조율합니다.

Agent Teams

지속적인 병렬 작업이 필요하면 서브에이전트 대신 Agent Teams를 고려하세요. 서브에이전트는 각각 결과를 메인 컨텍스트에 반환하지만, Agent Teams는 독립적으로 작동하며 공유 태스크 리스트로 조율합니다.

최종 수정: 에