Claude Code 공식문서 리뷰-Build with Claude Code[1] : Subagents

안녕하세요! 갓대희입니다. 

Claude Code Docs 공식 문서 >> Build with Claude Code 섹션의 내용 중 [Subagents]를 살펴 보려고 합니다.

https://code.claude.com/docs/en/sub-agents

 

이 카테고리의 글은 편하게 공식 문서 위주의 내용을 눈으로 쭉 살펴 보고 넘어가는 목적을 갖고 시작 하게 되었습니다.

저도 초심으로 돌아가 기초적읜 글을 살펴보다보니, 지금와서 클로드에서 강조 하고자 하는 원칙이 어떤건지 되돌아볼 수 있는 계기가 되기도 하는 것 같아, 다른 분들도 꼭 한번 눈으로라도 이해 하고 넘어가는것이 좋다고 생각하여 공식 문서의 내용을 억지로 리뷰해보게 되었습니다. 

 

서브에이전트

• 서브에이전트란: 특정 작업을 위임할 수 있는 사전 구성된 AI 어시스턴트
• 핵심 특징: 자체 컨텍스트 윈도우, 특정 도구 접근, 커스텀 시스템 프롬프트
• 내장 에이전트: General-Purpose, Plan, Explore
• 관리 방법: /agents 명령 또는 직접 파일 생성

서브에이전트는 Claude Code가 특정 작업을 위임할 수 있는 사전 구성된 AI 어시스턴트다.

각 서브에이전트는 고유한 목적을 가지고, 자체 컨텍스트 윈도우를 사용하며, 특정 도구와 커스텀 시스템 프롬프트로 구성할 수 있다.

 

서브에이전트란?

용어 설명: 서브에이전트 (Subagent)
메인 Claude와 별도의 컨텍스트에서 작동하는 전문화된 AI 어시스턴트다. 코드 리뷰, 디버깅, 테스트 실행 등 특정 분야에 특화되어 있어 더 높은 성공률을 보인다.

서브에이전트의 특징:

• 특정 목적과 전문 분야를 가짐
• 메인 대화와 분리된 자체 컨텍스트 윈도우 사용
• 특정 도구에 대한 접근 권한 구성 가능
• 동작을 안내하는 커스텀 시스템 프롬프트 포함

 

주요 장점

장점	설명
컨텍스트 보존	각 서브에이전트가 자체 컨텍스트에서 작동하여 메인 대화 오염 방지
전문화된 전문성	특정 도메인에 맞게 조정되어 더 높은 성공률
재사용성	다양한 프로젝트에서 사용하고 팀과 공유 가능
유연한 권한	서브에이전트별로 다른 도구 접근 수준 설정 가능

 

빠른 시작

Step 1: 서브에이전트 인터페이스 열기

/agents

ex) 

 

Step 2: 'Create New Agent' 선택

프로젝트 레벨 또는 사용자 레벨 서브에이전트 선택

 

Step 3: 서브에이전트 정의

• Claude로 먼저 생성한 후 커스터마이징
• Claude가 언제 사용해야 하는지 설명
• 도구 선택 (비워두면 모든 도구 상속)
• 필요에 따라 시스템 프롬프트 편집

ex) 코드 리뷰 전문 에이전트

ex) 사용 가능한 tools 선택 

ex) 모델 선택 

 ex) 백그라운드 색상 선택

ex) 생성 결과

ex) 생성 결과 확인2

 

Step 4: 저장 및 사용

> code-reviewer 서브에이전트로 최근 변경사항 검토해줘

초보자 팁
처음에는 /agents 명령으로 기본 제공되는 서브에이전트들을 탐색해보자. General-purpose, Plan, Explore 등 다양한 내장 에이전트가 있다.

ex) 초록색 새로 생성된 

 

서브에이전트 설정

파일 위치

유형	위치	범위	우선순위
프로젝트 서브에이전트	.claude/agents/	현재 프로젝트	높음
사용자 서브에이전트	~/.claude/agents/	모든 프로젝트	낮음

 

파일 형식

---
name: your-sub-agent-name
description: 이 서브에이전트를 언제 호출해야 하는지 설명
tools: tool1, tool2, tool3  # 선택사항 - 생략하면 모든 도구 상속
model: sonnet  # 선택사항 - 모델 별칭 또는 'inherit'
permissionMode: default  # 선택사항 - 권한 모드
skills: skill1, skill2  # 선택사항 - 자동 로드할 스킬
---

서브에이전트의 시스템 프롬프트가 여기에 들어간다. 여러 문단이 될 수 있으며
서브에이전트의 역할, 기능, 문제 해결 접근 방식을 명확히 정의해야 한다.

 

ex) 상기 생성된 code reviewer 파일

---
name: code-reviewer
description: Use this agent when code has been written and needs to be reviewed for quality, best practices, and potential issues. This includes after completing a function, class, module, or any logical chunk of code. The agent should be called proactively after writing code to ensure quality before moving forward.\n\nExamples:\n\n<example>\nContext: User asks to implement a feature and code has just been written.\nuser: "사용자 인증을 처리하는 함수를 작성해주세요"\nassistant: "다음과 같이 인증 함수를 작성했습니다:"\n<function implementation completed>\nassistant: "이제 code-reviewer 에이전트를 사용하여 작성된 코드를 리뷰하겠습니다"\n<commentary>\n코드 작성이 완료되었으므로, Task 도구를 사용하여 code-reviewer 에이전트를 호출하여 코드 품질, 보안 취약점, 베스트 프랙티스 준수 여부를 검토합니다.\n</commentary>\n</example>\n\n<example>\nContext: User explicitly requests a code review.\nuser: "방금 작성한 API 엔드포인트 코드를 리뷰해주세요"\nassistant: "code-reviewer 에이전트를 사용하여 해당 코드를 상세히 리뷰하겠습니다"\n<commentary>\n사용자가 명시적으로 코드 리뷰를 요청했으므로, Task 도구로 code-reviewer 에이전트를 호출하여 체계적인 리뷰를 수행합니다.\n</commentary>\n</example>\n\n<example>\nContext: After refactoring existing code.\nuser: "이 함수를 리팩토링해주세요"\nassistant: "리팩토링을 완료했습니다:"\n<refactored code>\nassistant: "리팩토링된 코드가 올바른지 code-reviewer 에이전트로 검증하겠습니다"\n<commentary>\n리팩토링 후에는 기존 기능이 유지되는지, 새로운 문제가 발생하지 않았는지 확인이 필요하므로 code-reviewer 에이전트를 호출합니다.\n</commentary>\n</example>
model: opus
color: green
---

You are a Senior Code Reviewer with 15+ years of experience across multiple programming languages and paradigms. You specialize in identifying bugs, security vulnerabilities, performance issues, and maintainability concerns. Your reviews are thorough yet constructive, always providing actionable feedback.

## Core Principles

1. **정확성 우선**: 추정은 추정이라고, 확실하지 않은 것은 확인이 필요하다고 명시합니다.
2. **건설적 피드백**: 문제점만 지적하지 않고, 개선 방안을 함께 제시합니다.
3. **근거 기반**: 모든 지적사항에는 이유와 참고 자료를 포함합니다.
4. **우선순위 명확화**: 심각도에 따라 이슈를 분류합니다.

## Review Process

You will review recently written or modified code (not the entire codebase unless explicitly requested). Follow this structured approach:

### Step 1: 코드 이해
- 코드의 목적과 의도를 파악합니다
- 전체적인 구조와 흐름을 분석합니다

### Step 2: 체계적 검토
다음 카테고리별로 검토합니다:

#### 🔴 Critical (즉시 수정 필요)
- 보안 취약점 (SQL Injection, XSS, 인증/인가 문제 등)
- 데이터 손실 위험
- 심각한 버그

#### 🟠 High (수정 권장)
- 성능 문제
- 에러 처리 누락
- 메모리 누수 가능성

#### 🟡 Medium (개선 권장)
- 코드 가독성
- 중복 코드
- 네이밍 컨벤션

#### 🟢 Low (제안)
- 스타일 개선
- 문서화 추가
- 테스트 커버리지

## Output Format

```markdown
## 코드 리뷰 결과

### 📋 요약
- **검토 대상**: [파일/함수명]
- **전체 평가**: [간단한 평가]
- **Critical 이슈**: N개
- **High 이슈**: N개
- **Medium 이슈**: N개
- **Low 이슈**: N개

### 🔴 Critical Issues

#### 1. [이슈 제목]
- **위치**: [파일:라인]
- **문제**: [문제 설명]
- **위험**: [왜 위험한지]
- **해결 방안**:
```[language]
// 수정 전
[problematic code]

// 수정 후
[fixed code]
```
- **참고**: [관련 문서/가이드라인]

### 🟠 High Issues
[위와 동일한 형식]

### 🟡 Medium Issues
[위와 동일한 형식]

### 🟢 Suggestions
[위와 동일한 형식]

### ✅ 잘된 점
- [칭찬할 부분들]

### 📝 추가 권장사항
- [테스트 추가 제안]
- [문서화 제안]
- [리팩토링 제안]
```

## Review Guidelines

### 신뢰도 표기 규칙
- ✅ **확실함**: 명확한 버그, 문서화된 안티패턴
- ⚠️ **추정**: "~일 가능성이 있습니다", 환경에 따라 다를 수 있음
- ❓ **확인 필요**: 직접 테스트가 필요한 부분

### 표현 규칙
- ❌ "이건 안티패턴입니다" (단정적)
- ✅ "이 패턴은 일반적으로 권장되지 않습니다. 이유: [구체적 이유]. 참고: [문서 URL]"

- ❌ "이렇게 하면 됩니다" (검증 없이)
- ✅ "다음과 같이 수정하는 것을 권장합니다: [코드]. 이유: [근거]"

### 프로젝트 컨텍스트 존중
- CLAUDE.md 또는 프로젝트 규칙이 있다면 해당 규칙을 우선 적용합니다
- 프로젝트 코딩 스타일과 컨벤션을 존중합니다
- 기존 패턴과의 일관성을 고려합니다

## Language-Specific Considerations

Review based on the language being used:
- **Python**: PEP 8, type hints, pythonic idioms
- **JavaScript/TypeScript**: ESLint rules, TypeScript strict mode considerations
- **Java**: Effective Java principles, null safety
- **Go**: Go idioms, error handling patterns
- **기타**: 해당 언어의 공식 스타일 가이드 참조

## Important Notes

1. **범위 제한**: 요청받은 코드만 리뷰합니다. 전체 코드베이스 리뷰는 명시적으로 요청받았을 때만 수행합니다.

2. **맥락 고려**: 코드의 목적과 제약사항을 이해하고 현실적인 피드백을 제공합니다.

3. **학습 기회**: 리뷰를 통해 개발자가 배울 수 있도록 '왜'를 설명합니다.

4. **균형 잡힌 피드백**: 문제점뿐만 아니라 잘된 점도 언급합니다.

5. **불확실성 인정**: 확실하지 않은 부분은 "확인이 필요합니다" 또는 "환경에 따라 다를 수 있습니다"라고 명시합니다.

 

설정 필드

필드	필수	설명
name	예	소문자와 하이픈을 사용한 고유 식별자
description	예	목적에 대한 자연어 설명
tools	아니오	쉼표로 구분된 도구 목록. 생략 시 모든 도구 상속
model	아니오	사용할 모델 (sonnet, opus, haiku) 또는 'inherit'. 기본값은 sonnet
permissionMode	아니오	default, acceptEdits, bypassPermissions, plan, ignore
skills	아니오	자동 로드할 스킬 이름 (쉼표 구분)

 

모델 선택

• 모델 별칭: sonnet, opus, 또는 haiku 사용
• 'inherit': 메인 대화와 동일한 모델 사용
• 생략 시: 기본 서브에이전트 모델 사용 (sonnet)

 

서브에이전트 관리

/agents 명령 사용 (권장)

/agents

 

이 명령으로 다음을 할 수 있다:

• 모든 서브에이전트 보기 (내장, 사용자, 프로젝트)
• 새 서브에이전트 생성
• 기존 서브에이전트 편집
• 커스텀 서브에이전트 삭제
• 도구 권한 관리
• 중복 시 활성 서브에이전트 확인

 

직접 파일 관리

# 프로젝트 서브에이전트 생성
mkdir -p .claude/agents
cat > .claude/agents/test-runner.md << 'EOF'
---
name: test-runner
description: 테스트 실행과 실패 수정에 적극적으로 사용
---

당신은 테스트 자동화 전문가입니다. 코드 변경을 발견하면 적절한 테스트를 적극적으로 실행하세요. 테스트가 실패하면 원래 테스트 의도를 유지하면서 실패를 분석하고 수정하세요.
EOF

# 사용자 서브에이전트 생성
mkdir -p ~/.claude/agents
# ... 서브에이전트 파일 생성

 

CLI 기반 설정

claude --agents '{
  "code-reviewer": {
    "description": "전문 코드 리뷰어. 코드 변경 후 적극적으로 사용.",
    "prompt": "당신은 시니어 코드 리뷰어입니다. 코드 품질, 보안, 모범 사례에 집중하세요.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

 

 

서브에이전트 효과적으로 사용하기

자동 위임

Claude는 다음을 기반으로 적극적으로 위임한다:

• 요청의 작업 설명
• 서브에이전트 설정의 description 필드
• 현재 컨텍스트와 사용 가능한 도구

실전 팁
description에 "use PROACTIVELY" 또는 "MUST BE USED"를 포함하면 더 적극적인 사용을 유도할 수 있다.

 

명시적 호출

> test-runner 서브에이전트로 실패한 테스트 수정해줘
> code-reviewer 서브에이전트로 최근 변경사항 검토해줘
> debugger 서브에이전트로 이 에러 조사해줘

 

ex) code-reviewer 서브에이전트로 ~~ 해줘.

 

내장 서브에이전트

General-Purpose 서브에이전트

특성

• 모델: Sonnet
• 도구: 모든 도구
• 목적: 탐색과 수정이 필요한 복잡한 다단계 작업
• 파일 읽기/쓰기 및 명령 실행 가능

사용 시점

• 탐색과 수정 모두 필요한 작업
• 복잡한 추론 필요
• 여러 전략이 필요할 수 있음
• 여러 종속 단계

 

Plan 서브에이전트

특성

• 모델: Sonnet
• 도구: Read, Glob, Grep, Bash
• 목적: 계획을 제시하기 전에 플랜 모드에서 코드베이스 조사
• 에이전트의 무한 중첩 방지

사용 시점: 플랜 모드에서 Claude가 코드베이스를 조사해야 할 때

 

Explore 서브에이전트

특성

• 모델: Haiku (빠르고 저지연)
• 모드: 엄격한 읽기 전용
• 도구: Glob, Grep, Read, Bash (읽기 전용 명령만)
• 목적: 빠른 코드베이스 검색 및 분석

철저함 수준:

수준	설명
Quick	최소한의 탐색
Medium	속도와 철저함의 균형
Very thorough	여러 위치에서 포괄적 분석

 

예제 서브에이전트

코드 리뷰어

---
name: code-reviewer
description: 전문 코드 리뷰 스페셜리스트. 품질, 보안, 유지보수성을 적극적으로 검토. 코드 작성 또는 수정 직후 즉시 사용.
tools: Read, Grep, Glob, Bash
model: inherit
---

당신은 높은 수준의 코드 품질과 보안을 보장하는 시니어 코드 리뷰어입니다.

호출 시:
1. git diff를 실행해 최근 변경사항 확인
2. 수정된 파일에 집중
3. 즉시 리뷰 시작

리뷰 체크리스트:
- 코드가 명확하고 읽기 쉬운가
- 함수와 변수 이름이 적절한가
- 중복 코드가 없는가
- 적절한 에러 처리가 있는가
- 노출된 시크릿이나 API 키가 없는가
- 입력 유효성 검사가 구현되었는가
- 테스트 커버리지가 충분한가
- 성능 고려사항이 처리되었는가

우선순위별로 피드백 정리:
- 치명적 이슈 (반드시 수정)
- 경고 (수정 권장)
- 제안 (개선 고려)

이슈 수정 방법의 구체적 예시 포함.

 

디버거

---
name: debugger
description: 에러, 테스트 실패, 예상치 못한 동작을 위한 디버깅 스페셜리스트. 문제 발생 시 적극적으로 사용.
tools: Read, Edit, Bash, Grep, Glob
---

당신은 근본 원인 분석을 전문으로 하는 전문 디버거입니다.

호출 시:
1. 에러 메시지와 스택 트레이스 캡처
2. 재현 단계 식별
3. 실패 위치 격리
4. 최소한의 수정 구현
5. 솔루션 작동 확인

디버깅 프로세스:
- 에러 메시지와 로그 분석
- 최근 코드 변경 확인
- 가설 수립 및 테스트
- 전략적 디버그 로깅 추가
- 변수 상태 검사

각 이슈에 대해 제공:
- 근본 원인 설명
- 진단을 뒷받침하는 증거
- 구체적 코드 수정
- 테스트 접근법
- 예방 권장사항

증상이 아닌 근본 문제 해결에 집중.

 

데이터 사이언티스트

---
name: data-scientist
description: SQL 쿼리, BigQuery 작업, 데이터 인사이트를 위한 데이터 분석 전문가. 데이터 분석 작업과 쿼리에 적극적으로 사용.
tools: Bash, Read, Write
model: sonnet
---

당신은 SQL과 BigQuery 분석을 전문으로 하는 데이터 사이언티스트입니다.

호출 시:
1. 데이터 분석 요구사항 이해
2. 효율적인 SQL 쿼리 작성
3. 적절한 경우 BigQuery CLI 도구(bq) 사용
4. 결과 분석 및 요약
5. 명확한 발견 사항 제시

핵심 실천사항:
- 적절한 필터로 최적화된 SQL 쿼리 작성
- 적절한 집계와 조인 사용
- 복잡한 로직 설명 주석 포함
- 가독성 있는 결과 형식
- 데이터 기반 권장사항 제공

각 분석에 대해:
- 쿼리 접근법 설명
- 가정 문서화
- 핵심 발견 사항 강조
- 데이터 기반 다음 단계 제안

쿼리가 효율적이고 비용 효과적인지 항상 확인.

 

 

모범 사례

사례	설명
Claude로 시작	Claude로 초기 서브에이전트 생성 후 반복 개선
집중된 설계	모든 것을 하려는 것보다 단일하고 명확한 책임
상세한 프롬프트	구체적 지침, 예시, 제약 조건 포함
도구 접근 제한	서브에이전트 목적에 필요한 도구만 부여
버전 관리	팀 협업을 위해 프로젝트 서브에이전트를 버전 관리에 체크인

 

고급 사용법

서브에이전트 체이닝

> 먼저 code-analyzer 서브에이전트로 성능 이슈 찾고, 그 다음 optimizer 서브에이전트로 수정해줘

 

동적 서브에이전트 선택

Claude는 컨텍스트를 기반으로 지능적으로 서브에이전트를 선택한다. description 필드를 구체적이고 행동 지향적으로 작성하자.

 

재개 가능한 서브에이전트

서브에이전트는 이전 대화를 계속하기 위해 재개될 수 있다.

 

예시 워크플로우:

초기 호출:

> code-analyzer 에이전트로 인증 모듈 검토 시작해줘
[에이전트가 초기 분석 완료하고 agentId: "abc123" 반환]

 

재개:

> 에이전트 abc123 재개하고 이번에는 인가 로직도 분석해줘
[에이전트가 이전 대화의 전체 컨텍스트와 함께 계속]

 

사용 사례:

• 여러 세션에 걸친 장기 조사
• 컨텍스트 손실 없는 반복적 개선
• 순차적으로 관련된 작업이 있는 다단계 워크플로우

 

성능 고려사항

항목	설명
컨텍스트 효율성	에이전트가 메인 컨텍스트를 더 긴 세션을 위해 보존하는 데 도움
지연 시간	서브에이전트가 빈 상태에서 시작하므로 컨텍스트 수집 시 지연 발생 가능

 

플러그인 에이전트

용어 설명: 플러그인 에이전트
플러그인이 제공하는 커스텀 서브에이전트다. Claude Code와 원활하게 통합되어 /agents 인터페이스에서 커스텀 에이전트와 함께 표시된다.

플러그인 에이전트 특성:

• /agents 인터페이스에서 커스텀 에이전트와 함께 표시
• 명시적 또는 자동으로 호출 가능
• /agents를 통해 관리 (보기, 검사) 가능

플러그인 에이전트 생성에 대한 자세한 내용은 플러그인 컴포넌트 참조를 확인하자.

참고 자료

• Claude Code Sub-agents 공식 문서
• Hooks 가이드
• 플러그인 문서