본문으로 건너뛰기

서브에이전트 패턴

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

빌트인 서브에이전트​

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

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

Claude는 작업 특성에 따라 자동으로 적절한 서브에이전트를 선택합니다. Explore는 코드베이스 탐색에, general-purpose는 수정이 필요한 복잡한 작업에 사용됩니다.

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

컨텍스트 분리​

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

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

중첩 제한​

서브에이전트는 다른 서브에이전트를 생성할 수 없습니다. 중첩 위임이 필요하면 Skills를 사용하거나 메인 대화에서 순차적으로 체이닝하세요.

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

포그라운드백그라운드
동작완료까지 메인 대화 차단동시에 작업 계속
권한대화형 권한 프롬프트사전 승인된 권한만
전환기본 동작Ctrl+B로 전환 가능
실패 시즉시 대화형 수정포그라운드로 resume 가능

Claude가 자동으로 판단하지만, "백그라운드에서 실행해줘"라고 요청할 수도 있습니다.

서브에이전트 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는 독립적으로 작동하며 공유 태스크 리스트로 조율합니다.

최종 수정: 에