Claude Code 서브에이전트 완전정리: AI가 AI를 부려서 일하는 법

Claude Code 서브에이전트 완전정리: AI가 AI를 부려서 일하는 법

하나의 작업을 하나의 Claude가 처리하는 건 기본입니다. 하지만 코드 탐색은 탐색 전문 에이전트에게, 테스트는 테스트 전문 에이전트에게, 보안 리뷰는 보안 전문가에게 동시에 맡길 수 있다면? Claude Code의 서브에이전트(Sub-agent) 시스템이 바로 그걸 해냅니다. 이 글에서는 서브에이전트의 개념부터 실전 활용까지 완전 정리합니다.

Claude Code 서브에이전트 완전정리

---

1. 서브에이전트란?

메인 에이전트가 소환하는 전문가

서브에이전트는 메인 대화(메인 에이전트) 안에서 독립적인 컨텍스트 윈도우를 가진 별도의 AI 에이전트를 생성하는 기능입니다. 메인 에이전트가 복잡한 작업을 만나면 전문화된 서브에이전트를 소환해서 위임하고, 결과만 돌려받습니다.

[메인 에이전트] ─── "이 코드베이스 구조 파악해줘" ───▶ [Explore 서브에이전트]
     │                                                       │
     │◀───── 요약된 결과 반환 ────────────────────────────────┘
     │
     ├─── "테스트 돌려줘" ───▶ [범용 서브에이전트]
     │                              │
     │◀───── 테스트 결과 ───────────┘

왜 서브에이전트인가?

문제	서브에이전트 해결
컨텍스트 오염	탐색/분석 결과가 메인 컨텍스트를 채우지 않음
순차 처리 느림	여러 작업을 병렬로 동시 실행
하나의 역할	각 서브에이전트가 전문 역할 수행
도구 남용 위험	서브에이전트별로 도구 접근 제한 가능
비용 통제 어려움	서브에이전트별로 모델/턴 수 제한 가능

핵심 이점: 메인 대화의 컨텍스트 윈도우를 깨끗하게 유지하면서, 복잡한 작업을 병렬로 처리할 수 있습니다.

 

서브에이전트란?

---

2. 내장 서브에이전트 유형

Claude Code가 기본 제공하는 4가지 유형

Claude Code에는 바로 사용할 수 있는 내장 서브에이전트가 있습니다.

Explore (탐색 전문가)

용도: 코드베이스 탐색, 파일 검색, 코드 분석
모델: Haiku (빠르고 저렴)
도구: 읽기 전용 (Read, Glob, Grep 등)
쓰기 불가: Write, Edit 사용 불가

Explore 에이전트는 코드를 수정하지 않고 탐색만 합니다. "이 프로젝트에서 인증 로직이 어디에 있어?"처럼 탐색 작업에 최적입니다. Haiku 모델을 사용하므로 빠르고 비용이 낮습니다.

Plan (설계 전문가)

용도: 구현 계획 수립, 아키텍처 분석
모델: 메인 대화와 동일 (상속)
도구: 읽기 전용 도구
특징: Plan 모드에서 자동 사용

Plan 에이전트는 코드를 읽고 분석해서 구현 계획을 세워주는 전문가입니다. 파일을 수정하지 않으므로 안전하게 코드 분석을 맡길 수 있습니다.

범용 (General-Purpose)

용도: 복잡한 멀티스텝 작업
모델: 메인 대화와 동일 (상속)
도구: 모든 도구 사용 가능 (Read, Write, Edit, Bash 등)
특징: 가장 강력하지만 권한 관리 필요

범용 서브에이전트는 모든 도구에 접근할 수 있어 파일 수정, 테스트 실행 등 실제 작업 수행이 가능합니다.

Claude Code Guide (가이드)

용도: Claude Code 기능/사용법 안내
모델: Haiku
도구: 읽기 전용 + 웹 검색
특징: 문서 기반 답변

유형	모델	쓰기 가능	주요 용도
Explore	Haiku	❌	코드 탐색/검색
Plan	상속	❌	구현 계획 수립
범용	상속	✅	멀티스텝 작업
Guide	Haiku	❌	사용법 안내

내장 서브에이전트 유형

---

3. 서브에이전트 호출 방법

Agent 도구로 호출하기

Claude Code는 Agent 도구를 통해 서브에이전트를 생성합니다. 사용자가 복잡한 요청을 하면 Claude가 자동으로 적절한 서브에이전트를 선택해서 위임합니다.

주요 파라미터

파라미터	필수	설명
prompt	✅	서브에이전트에 전달할 작업 내용
description	✅	3~5단어 요약
subagent_type	-	에이전트 유형 (Explore, Plan 등)
model	-	모델 오버라이드 (sonnet, opus, haiku)
isolation	-	worktree로 Git 워크트리 격리
run_in_background	-	백그라운드 실행 여부
resume	-	이전 에이전트 ID로 재개

자동 위임 예시

사용자가 이런 요청을 하면:

"이 프로젝트에서 API 엔드포인트 전부 찾아줘"

Claude가 자동으로 Explore 서브에이전트를 생성합니다:

Agent(
  subagent_type="Explore",
  description="API 엔드포인트 탐색",
  prompt="이 프로젝트에서 모든 API 엔드포인트를 찾아서
         경로, HTTP 메서드, 핸들러 함수를 정리해줘"
)

CLI에서 커스텀 서브에이전트 정의

claude --agents '{
  "code-reviewer": {
    "description": "코드 리뷰 전문가. 코드 변경 후 자동 실행.",
    "prompt": "시니어 개발자로서 코드를 리뷰하세요...",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

 

서브에이전트 호출 방법

---

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

프로젝트/사용자 레벨 정의

서브에이전트는 마크다운 파일로 정의합니다. 프론트매터(YAML)로 설정하고, 본문이 시스템 프롬프트가 됩니다.

프로젝트 레벨 (팀 공유)

.claude/agents/security-reviewer.md

---
name: security-reviewer
description: 보안 취약점을 리뷰하는 전문가
tools:
  - Read
  - Grep
  - Glob
  - Bash
model: opus
---

당신은 시니어 보안 엔지니어입니다. 코드를 검토할 때:
- 인젝션 취약점 (SQL, XSS, 커맨드 인젝션)
- 인증 및 권한 부여 결함
- 코드에 포함된 시크릿이나 자격 증명
을 찾아서 구체적인 라인 번호와 수정 방법을 제시하세요.

사용자 레벨 (개인 전용)

~/.claude/agents/my-debugger.md

프론트매터 주요 설정

필드	타입	설명
name	필수	고유 식별자 (소문자, 하이픈)
description	필수	언제 이 에이전트를 쓸지 설명
tools	선택	사용 가능한 도구 목록 (허용 목록)
disallowedTools	선택	명시적으로 차단할 도구
model	선택	sonnet, opus, haiku, inherit
permissionMode	선택	default, acceptEdits, dontAsk 등
maxTurns	선택	최대 에이전틱 턴 수
skills	선택	사전 로드할 스킬 목록
mcpServers	선택	사용 가능한 MCP 서버
hooks	선택	라이프사이클 훅
memory	선택	user, project, local (영구 메모리)
background	선택	true로 항상 백그라운드 실행
isolation	선택	worktree로 Git 워크트리 격리

적용 우선순위

CLI 플래그 (--agents) → 프로젝트 (.claude/agents/) → 사용자 (~/.claude/agents/)

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

---

5. 병렬 실행과 백그라운드

서브에이전트 병렬 실행

서브에이전트의 가장 강력한 기능은 여러 작업을 동시에 처리하는 것입니다.

"인증 모듈, 데이터베이스 레이어, API 모듈을 각각 분석해줘"

이 요청을 받으면 Claude는 3개의 Explore 서브에이전트를 동시에 실행합니다:

[메인 에이전트]
    ├── [Explore] 인증 모듈 분석 ──▶ 결과 1
    ├── [Explore] 데이터베이스 분석 ──▶ 결과 2
    └── [Explore] API 모듈 분석 ──▶ 결과 3
                                       ↓
                             [메인] 결과 종합

포그라운드 vs 백그라운드

구분	포그라운드 (기본)	백그라운드
실행	결과를 기다림	결과 없이 진행
권한	실행 중 물어봄	사전 승인 필요
용도	다음 작업에 결과 필요할 때	독립적인 작업
실패 시	즉시 대응	나중에 재개

백그라운드 실행 방법

# 1. 프론트매터에서 설정
---
background: true
---

# 2. 실행 중 Ctrl+B 누르기
# → 현재 서브에이전트를 백그라운드로 전환

# 3. 대화에서 요청
"이 작업은 백그라운드로 돌려줘"

서브에이전트 재개 (Resume)

서브에이전트는 고유 ID를 가집니다. 이전 서브에이전트의 컨텍스트를 이어서 작업할 수 있습니다.

"아까 그 코드 리뷰 서브에이전트 이어서, 이번엔 권한 로직도 분석해줘"

Claude는 이전 에이전트 ID로 resume하여 전체 대화 기록을 유지한 채 작업을 이어갑니다.

병렬 실행과 백그라운드

---

6. 워크트리 격리 모드

서브에이전트에게 독립된 저장소를

워크트리(Worktree) 격리 모드는 서브에이전트에게 Git 워크트리를 통한 별도의 저장소 사본을 제공합니다. 메인 브랜치를 건드리지 않고 안전하게 실험할 수 있습니다.

설정 방법

---
name: feature-builder
description: 기능을 격리된 환경에서 구현
isolation: worktree
---

동작 방식

[메인 브랜치: main]
    │
    ├── .claude/worktrees/feature-builder/
    │   └── (저장소 전체 사본)
    │       └── 브랜치: worktree-feature-builder
    │
    └── .claude/worktrees/security-fix/
        └── (저장소 전체 사본)
            └── 브랜치: worktree-security-fix

워크트리의 장점

장점	설명
파일 충돌 방지	여러 서브에이전트가 동시에 수정해도 충돌 없음
안전한 실험	메인 브랜치 영향 없이 자유롭게 시도
자동 정리	변경 없으면 워크트리 자동 삭제
커밋 보존	커밋이 있으면 워크트리와 브랜치 보존
병렬 작업	각 에이전트가 독립된 사본에서 동시 작업

실전 시나리오

"인증 리팩토링, DB 마이그레이션, UI 개선을
 각각 워크트리에서 동시에 진행해줘"

→ 3개의 독립된 워크트리에서 각 서브에이전트가 작업
→ 결과를 확인한 뒤 원하는 브랜치만 병합

워크트리 격리 모드

---

7. 컨텍스트 관리 전략

서브에이전트와 컨텍스트 윈도우

서브에이전트의 가장 큰 이점은 메인 컨텍스트를 보호하는 것입니다.

[메인 컨텍스트: 200K 토큰]
    │
    │  ← 깔끔하게 유지
    │
    ├── [서브에이전트 A: 200K 토큰] ← 탐색 결과 가득
    │      → 메인에는 요약만 전달
    │
    └── [서브에이전트 B: 200K 토큰] ← 테스트 로그 가득
           → 메인에는 결과만 전달

컨텍스트 관리 원칙

원칙	설명
결과만 전달	서브에이전트의 상세 탐색 결과는 요약되어 메인에 전달
독립 예산	각 서브에이전트가 독립적인 200K 토큰 예산 보유
자동 압축	서브에이전트도 ~95% 용량에서 자동 컴팩션
설정 상속	CLAUDE.md, MCP 서버, 스킬은 서브에이전트에 상속
히스토리 독립	메인 대화 기록은 서브에이전트에 전달되지 않음

서브에이전트에 스킬 로드

---
name: api-developer
description: API 엔드포인트 구현 전문가
skills:
  - api-conventions
  - error-handling-patterns
---

skills 필드로 지정한 스킬의 전체 내용이 서브에이전트 시작 시 주입됩니다. 메인 컨텍스트에는 영향을 주지 않습니다.

컨텍스트 관리 전략

---

8. 실전 활용 레시피

레시피 1: 코드 리뷰 전문가

---
name: code-reviewer
description: 코드 변경 후 자동으로 리뷰하는 전문가
tools:
  - Read
  - Grep
  - Glob
  - Bash
model: sonnet
---

시니어 개발자로서 코드를 리뷰합니다:
- 버그 가능성과 엣지 케이스
- 성능 병목 지점
- 코드 스타일과 가독성
- 테스트 커버리지 부족한 부분
구체적인 라인 번호와 개선 코드를 제시하세요.

레시피 2: 보안 감사관

---
name: security-auditor
description: 보안 취약점을 찾아내는 감사관
tools:
  - Read
  - Grep
  - Glob
model: opus
---

보안 엔지니어로서 다음을 검토합니다:
- SQL/XSS/커맨드 인젝션
- 하드코딩된 시크릿
- 인증/권한 결함
- OWASP Top 10
심각도(높음/중간/낮음)와 수정 방법을 제시하세요.

레시피 3: 테스트 러너 (백그라운드)

---
name: test-runner
description: 코드 변경 후 테스트를 실행하고 결과 보고
tools:
  - Read
  - Bash
background: true
---

변경된 코드에 대해 테스트를 실행합니다:
1. 관련 테스트 파일 찾기
2. 테스트 실행
3. 실패한 테스트만 요약 보고

레시피 4: 학습하는 리뷰어 (영구 메모리)

---
name: learning-reviewer
description: 리뷰하면서 패턴을 학습하는 리뷰어
tools:
  - Read
  - Grep
  - Glob
memory: user
---

코드를 리뷰하면서 에이전트 메모리에 기록합니다:
- 발견한 코드 패턴과 컨벤션
- 반복되는 이슈
- 아키텍처 결정 사항
이전 리뷰에서 학습한 내용을 바탕으로 일관된 리뷰를 제공합니다.

레시피 5: 훅과 결합한 DB 전용 에이전트

---
name: db-reader
description: 읽기 전용 데이터베이스 쿼리 실행
tools:
  - Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

훅을 사용해서 SELECT 쿼리만 허용하도록 강제합니다.

실전 활용 레시피

---

9. 서브에이전트 vs 에이전트 팀

같은 듯 다른 두 시스템

항목	서브에이전트	에이전트 팀
구조	하나의 세션 내 하위 에이전트	독립된 여러 세션
소통	메인 에이전트에만 보고	팀원끼리 직접 소통
토큰 비용	낮음 (요약 반환)	높음 (각자 독립 세션)
병렬성	가능하나 메인이 조율	완전한 병렬 작업
적합한 작업	분업 가능한 독립 작업	상호 협력이 필요한 작업
설정	.claude/agents/ 파일	.claude/teams/ 파일

언제 뭘 써야 할까?

서브에이전트를 쓸 때:

• 탐색/분석처럼 독립적인 작업
• 메인 컨텍스트를 보호하고 싶을 때
• 비용을 절약하고 싶을 때
• 결과 요약만 있으면 충분할 때

에이전트 팀을 쓸 때:

• 프론트/백엔드 동시 개발처럼 상호 참조가 필요할 때
• 각 에이전트가 서로의 진행 상황을 알아야 할 때
• 대규모 프로젝트에서 역할별 분담이 필요할 때

서브에이전트 vs 에이전트 팀

---

10. 자주 묻는 질문 (FAQ)

Q: 서브에이전트가 메인 대화의 내용을 알 수 있나요?
A: 아닙니다. 서브에이전트는 새로운 컨텍스트로 시작합니다. 메인 대화 기록은 전달되지 않으며, prompt 파라미터로 전달한 내용만 받습니다. 단, CLAUDE.md와 MCP 서버 설정은 상속됩니다.

Q: 서브에이전트 비용은 별도인가요?
A: 서브에이전트도 같은 API 키의 토큰을 소비합니다. 다만 Explore처럼 Haiku 모델을 쓰는 서브에이전트는 Opus보다 훨씬 저렴합니다.

Q: 서브에이전트를 무한히 만들 수 있나요?
A: 이론적으로 개수 제한은 없지만, 각 서브에이전트가 API 호출을 발생시키므로 비용과 시간을 고려해야 합니다.

Q: 서브에이전트가 또 다른 서브에이전트를 만들 수 있나요?
A: 기본적으로 서브에이전트의 도구 목록에 Agent 도구가 포함되어 있으면 가능하지만, 무한 중첩을 방지하기 위해 보통 제한합니다.

Q: 워크트리 모드 없이도 여러 서브에이전트가 동시에 파일을 수정할 수 있나요?
A: 가능하지만 파일 충돌 위험이 있습니다. 여러 에이전트가 같은 파일을 수정해야 한다면 워크트리 격리 모드를 사용하는 것이 안전합니다.

Q: 서브에이전트의 대화 기록을 볼 수 있나요?
A: 네, ~/.claude/projects/{프로젝트}/{세션ID}/subagents/agent-{에이전트ID}.jsonl 경로에 저장됩니다.

 

---

면책 조항: 이 글은 정보 제공 목적으로 작성되었습니다. Claude Code의 기능과 요금은 Anthropic의 정책에 따라 변경될 수 있으며, 최신 정보는 공식 문서를 확인해 주세요.