Subagents: 병렬 작업과 컨텍스트 격리

Subagents는 Claude Code의 핵심 기능으로, 특정 작업을 병렬로 실행하거나 격리된 컨텍스트에서 처리할 수 있게 해줍니다. 메인 에이전트의 컨텍스트를 오염시키지 않고 전문화된 작업을 수행할 수 있습니다.

Subagents란?

  • 정의: 격리된 컨텍스트에서 병렬로 실행되는 전문화된 AI 에이전트
  • 목적: 컨텍스트 오염 방지, 병렬 작업, 전문 분야 위임
  • 실행 방식: Claude가 작업에 따라 자동으로 생성하거나, 사용자가 정의

Subagent 유형

1. 내장 Task 에이전트

Claude가 자동으로 생성하는 일반 에이전트 클론:

# Claude가 자동으로 Task(...) 호출
"이 코드의 보안 취약점을 분석해줘"

# 내부적으로 서브에이전트 생성하여 분석 수행
# 메인 컨텍스트는 깨끗하게 유지

2. 커스텀 서브에이전트

사용자가 정의하는 전문화된 에이전트:

# .claude/agents/security-auditor.md

---
name: security-auditor
description: 코드 보안 취약점을 분석합니다
tools:
  - Read
  - Grep
  - Bash
model: sonnet
---

# 보안 감사관

## 역할
당신은 보안 전문 코드 감사관입니다.

## 검사 항목
1. XSS 취약점
2. SQL Injection
3. CSRF
4. 인증/인가 문제
5. 하드코딩된 비밀키

## 보고 형식
- 위험도: Critical/High/Medium/Low
- 위치: file:line
- 설명: 취약점 설명
- 해결책: 권장 수정 방법

Subagent 설정 옵션

옵션설명예시
name서브에이전트 이름security-auditor
description서브에이전트 설명보안 취약점 분석
tools허용된 도구 목록Read, Grep, Bash
model사용할 모델haiku, sonnet, opus
context컨텍스트 모드fork (부모 컨텍스트 복제)

백그라운드 서브에이전트

v2.0.60부터 서브에이전트를 백그라운드에서 실행할 수 있습니다:

백그라운드 실행

# 실행 중인 작업을 백그라운드로 전환
Ctrl+B

# 백그라운드 에이전트 특성
- 부모의 권한을 상속
- 사전 승인되지 않은 권한은 자동 거부
- 권한 필요시 해당 도구 호출 실패 (에이전트는 계속 실행)
- 명확화 질문 불가

백그라운드 에이전트 재개

# 권한 문제로 실패한 백그라운드 에이전트를 포그라운드로 재개
# 인터랙티브 프롬프트로 재시도 가능

서브에이전트 vs 스킬

특성서브에이전트스킬
컨텍스트격리됨메인과 공유
실행병렬 가능순차
용도작업 위임전문 지식 제공
도구 접근제한 가능제한 가능

실용적인 서브에이전트 예시

1. 코드 리뷰어

---
name: code-reviewer
description: PR 및 코드 변경사항을 리뷰합니다
tools:
  - Read
  - Grep
model: sonnet
---

# 코드 리뷰어

## 리뷰 기준
1. **코드 품질**: 가독성, 유지보수성, 중복
2. **성능**: 불필요한 연산, N+1 쿼리
3. **보안**: OWASP Top 10
4. **테스트**: 커버리지, 엣지 케이스

## 출력
- ✅ 승인
- ⚠️ 수정 권장
- ❌ 수정 필수

2. 문서화 에이전트

---
name: doc-writer
description: API 문서와 README를 생성합니다
tools:
  - Read
  - Write
model: haiku
---

# 문서 작성자

## 문서화 규칙
- JSDoc 스타일
- 모든 public 함수에 예시 포함
- 파라미터/반환값 타입 명시

3. 테스트 작성자

---
name: test-writer
description: 단위 테스트와 통합 테스트를 작성합니다
tools:
  - Read
  - Write
  - Bash
model: sonnet
---

# 테스트 작성자

## 테스트 원칙
- AAA 패턴 (Arrange, Act, Assert)
- 의미 있는 테스트 이름
- 엣지 케이스 포함
- Mock 최소화

## 프레임워크
- Jest (JavaScript/TypeScript)
- pytest (Python)

서브에이전트 관리

# 서브에이전트 목록 확인
/agents

# @-mention으로 서브에이전트 호출
@security-auditor 이 함수의 보안 검토해줘

# 새 서브에이전트 생성
/agents 명령어에서 "Create new agent" 선택

v2.1.0 서브에이전트 업데이트

  • context: fork: 프론트매터에서 부모 컨텍스트를 복제한 서브에이전트 실행 가능
  • 통합 Ctrl+B 백그라운딩: 명령어와 에이전트 모두에 적용
  • 서브에이전트 모델 선택 수정: 대화 압축 중 발생하던 문제 해결

베스트 프랙티스

  1. 하나의 전문 분야: 서브에이전트당 하나의 역할
  2. 최소 권한: 필요한 도구만 허용
  3. 경량 모델: 간단한 작업은 haiku 사용
  4. 명확한 지침: 마크다운 본문에 구체적인 가이드라인
  5. 병렬 활용: 독립적인 작업은 동시 실행

참고 자료: