Claude Code Subagent로 작업 위임하기

들어가며

Claude Code에서 하나의 에이전트가 모든 작업을 처리하면, 컨텍스트가 빠르게 소모되고 작업 간 간섭이 발생할 수 있습니다. Subagent는 특정 작업을 독립된 컨텍스트에서 처리하는 하위 에이전트입니다. 메인 에이전트가 작업을 위임하면, 서브에이전트가 자체 컨텍스트 윈도우(~200k 토큰)에서 독립적으로 수행하고 결과 요약만 반환합니다.

이번 포스팅에서는 서브에이전트의 동작 원리, 종류, 사용법, 그리고 실전 패턴을 정리합니다.

동작 원리

서브에이전트의 실행 흐름은 다음과 같습니다:

1. 메인 에이전트가 Task 도구를 통해 서브에이전트를 생성
2. 서브에이전트에 독립된 컨텍스트 윈도우가 할당됨
3. 서브에이전트가 허용된 도구만 사용하여 작업 수행
4. 작업 완료 후 결과 요약만 메인 에이전트에 반환

핵심은 컨텍스트 격리입니다. 서브에이전트는 메인 대화의 히스토리를 받지 않고, 메인 에이전트는 서브에이전트의 중간 과정을 보지 않습니다. 덕분에 테스트 실행 로그, 대량 검색 결과 같은 방대한 출력이 메인 컨텍스트를 오염시키지 않습니다.

내장 서브에이전트 종류

서브에이전트	모델	도구	용도
Explore	Haiku (빠름)	Glob, Grep, Read, Bash(읽기 전용)	코드베이스 탐색, 파일 검색
Plan	메인 상속	읽기 전용 도구	구현 계획 수립을 위한 리서치
general-purpose	메인 상속	모든 도구	복잡한 멀티스텝 작업
Bash	메인 상속	Bash	터미널 명령 실행

Explore 서브에이전트

가장 자주 사용되는 서브에이전트입니다. Haiku 모델을 사용해 빠르고 저렴하며, 읽기 전용이라 안전합니다. 탐색 깊이를 세 단계로 지정할 수 있습니다:

• quick: 파일명을 알고 있을 때 단일 검색 (~2-5초)
• medium: 여러 검색 전략으로 중간 수준 탐색
• very thorough: 여러 패턴을 교차하여 철저히 탐색

general-purpose 서브에이전트

모든 도구에 접근 가능한 범용 에이전트입니다. 코드 수정이 필요하거나 여러 단계를 거쳐야 하는 복잡한 작업에 적합합니다.

커스텀 서브에이전트 만들기

.claude/agents/ 디렉토리에 마크다운 파일을 생성하면 커스텀 서브에이전트를 정의할 수 있습니다.

.claude/agents/
├── code-reviewer.md
├── debugger.md
└── data-scientist.md

작성 형식

---
name: code-reviewer
description: 코드 변경사항의 보안, 성능, 가독성을 리뷰합니다
model: sonnet
tools: Read, Grep, Glob
---

## 역할
코드 리뷰어로서 변경된 코드를 분석합니다.

## 리뷰 기준
1. 보안 취약점 (OWASP Top 10)
2. 성능 병목
3. 코드 가독성과 유지보수성
4. 테스트 커버리지

## 출력 형식
- 심각도: Critical / Warning / Suggestion
- 파일:라인 형태로 위치 명시
- 구체적인 개선 방안 제시

주요 frontmatter 옵션

필드	설명
name	서브에이전트 이름
description	설명. Claude가 위임 판단 시 참고합니다
model	사용할 모델 (haiku, sonnet, opus)
tools	허용할 도구 목록
background	true면 항상 백그라운드 실행
skills	프리로딩할 스킬 목록
memory	user 또는 project (세션 간 메모리 유지)

병렬 실행

서브에이전트는 최대 10개까지 동시 실행이 가능합니다. 독립적인 작업을 병렬로 처리하면 대기 시간을 크게 줄일 수 있습니다.

"인증 모듈, 데이터베이스 모듈, API 모듈을 각각 별도 서브에이전트로 병렬 분석해줘"

각 서브에이전트가 독립적으로 탐색하고, 메인 에이전트가 결과를 종합합니다.

주의: 동일한 파일에 대한 동시 쓰기 작업은 충돌을 일으킬 수 있습니다. 병렬 실행은 읽기 위주 작업에 적합합니다.

에이전트 재개 (Resume)

서브에이전트는 고유 ID를 가지며, 이 ID를 통해 이전 작업을 이어서 진행할 수 있습니다.

사용자: "코드 리뷰 서브에이전트로 인증 모듈을 리뷰해줘"
[서브에이전트 완료, agent ID 발급]

사용자: "아까 코드 리뷰 이어서, 이번엔 권한 로직도 분석해줘"
[이전 컨텍스트를 유지한 채 서브에이전트 재개]

재개된 서브에이전트는 이전의 모든 도구 호출, 결과, 추론 내용을 그대로 유지합니다.

Skills와의 연동

Skills의 context: fork 옵션을 사용하면 스킬을 서브에이전트 컨텍스트에서 실행할 수 있습니다.

---
name: deep-research
description: 주제를 깊이 있게 조사합니다
context: fork
agent: Explore
---
$ARGUMENTS에 대해 코드베이스를 철저히 조사하고 결과를 정리해주세요.

필드	설명
context: fork	격리된 서브에이전트 컨텍스트에서 실행
agent	사용할 서브에이전트 타입 (기본값: general-purpose)

서브에이전트는 부모 대화의 스킬을 상속하지 않습니다. 필요한 스킬은 skills 필드에 명시적으로 나열해야 합니다.

언제 서브에이전트를 사용할까?

서브에이전트가 적합한 경우

• 방대한 출력이 예상될 때: 테스트 실행, 로그 분석 등
• 도구 제한이 필요할 때: 읽기 전용 리뷰, 안전한 탐색
• 독립적인 작업을 병렬 처리할 때: 여러 모듈 동시 분석
• 컨텍스트 격리가 필요할 때: 외부 코드베이스 분석

메인 에이전트가 적합한 경우

• 빈번한 대화가 필요할 때: 반복적인 수정과 피드백
• 작업이 간단할 때: 서브에이전트 오버헤드(~20k 토큰)가 비효율적
• 이전 컨텍스트를 많이 참조할 때: 계획 → 구현 → 테스트가 이어지는 경우

실전에서 사용하기

1. 테스트 실행 격리

테스트의 방대한 출력을 메인 컨텍스트에서 분리합니다.

"서브에이전트로 테스트 스위트를 실행하고, 실패한 테스트와 에러 메시지만 보고해줘"

2. 파이프라인 구성

서브에이전트를 체이닝하여 단계적 처리를 구성합니다.

1단계: code-reviewer가 문제점 발견 → 결과 반환
2단계: 메인 에이전트가 결과를 기반으로 수정 계획 수립
3단계: general-purpose 서브에이전트가 수정 구현

3. 코드베이스 전체 탐색

특정 패턴이 코드베이스 전체에서 어떻게 사용되는지 파악합니다.

"Explore 서브에이전트로 프로젝트 전체에서 에러 핸들링 패턴을 very thorough 수준으로 조사해줘"

제약 사항

• 중첩 불가: 서브에이전트는 다른 서브에이전트를 생성할 수 없습니다 (1단계만 가능)
• 토큰 오버헤드: 서브에이전트 하나당 최소 ~20k 토큰이 소모됩니다
• 백그라운드 MCP 제한: 백그라운드 실행 시 MCP 도구를 사용할 수 없습니다
• 동시 쓰기 주의: 같은 파일에 여러 서브에이전트가 동시에 쓰면 충돌이 발생할 수 있습니다

마치며

서브에이전트는 Claude Code의 작업 처리 능력을 크게 확장시켜 줍니다. 핵심은 적절한 위임입니다. 모든 작업을 서브에이전트에 맡기는 것이 아니라, 컨텍스트 격리가 필요하거나 병렬 처리가 가능한 작업을 선별하여 위임하면 효율적인 개발 워크플로우를 구성할 수 있습니다.

최근에는 서브에이전트가 메인 에이전트, 그리고 다른 서브에이전트와 협업하는 에이전트 팀이 등장했습니다. 토큰 소모량이 많아지지만 실제 하나의 조직이 운영되는 것과 같이 작동하며, 복잡한 작업시 효율이 좋습니다.