TL;DR
- 서브에이전트는 Claude Code가 특정 작업에 위임하는 전문화된 AI 어시스턴트
- subagent-wizard는 5단계 대화형 워크플로우로 서브에이전트 생성을 안내
- Description 작성, 도구 선택, 시스템 프롬프트 설계까지 단계별 가이드 제공
- 8가지 서브에이전트 유형 템플릿으로 즉시 시작 가능
- 자동 위임(proactive delegation)으로 반복 작업 자동화 가능
왜 서브에이전트가 필요한가?
Claude Code를 사용하다 보면 반복되는 패턴이 있습니다.
- 코드 작성 후 매번 “리뷰해줘”라고 요청
- 테스트 실패 시 “디버깅해줘”라고 말하기
- PR 올리기 전 “보안 검토해줘”라고 부탁
이런 반복 요청을 자동화할 수 있다면? 그것이 바로 서브에이전트입니다.
서브에이전트란?
서브에이전트는 Claude Code가 특정 작업을 처리하기 위해 생성하는 전문화된 AI 어시스턴트입니다.
| 특징 | 설명 |
|---|---|
| 커스텀 시스템 프롬프트 | 도메인별 맞춤 지침 |
| 도구 제한 | 필요한 도구만 접근 허용 |
| 모델 선택 | 작업 복잡도에 따라 haiku/sonnet/opus |
| 자동 위임 | 매칭되는 작업을 사전에 위임 |
예시: 코드 리뷰어 서브에이전트
---
name: code-reviewer
description: Expert code reviewer. Use PROACTIVELY after code modifications.
tools: Read, Grep, Glob, Bash
---
You are a senior code reviewer.
When invoked:
1. Run git diff to see changes
2. Review modified files
3. Report issues by priority이렇게 설정하면 코드 수정 후 Claude가 자동으로 코드 리뷰를 시작합니다.
문제: 서브에이전트 만들기가 어렵다
서브에이전트의 개념은 간단하지만, 실제로 만들려면 여러 결정이 필요합니다.
- Description 작성: 자동 위임의 핵심인데, 어떻게 써야 트리거될까?
- 도구 선택: Read, Write, Edit, Bash… 뭘 줘야 하지?
- 시스템 프롬프트: 어떤 구조로 작성해야 효과적일까?
- 저장 위치: 프로젝트용? 전역용?
문서를 읽고 직접 파악하는 것은 시간이 걸립니다. 그래서 subagent-wizard를 만들었습니다.
해결: subagent-wizard 스킬
subagent-wizard는 5단계 대화형 워크플로우로 서브에이전트 생성을 안내합니다.
Phase 1: Purpose Discovery (목적 발견)
↓
Phase 2: Configuration Design (구성 설계)
↓
Phase 3: System Prompt Writing (프롬프트 작성)
↓
Phase 4: Scope Selection (범위 선택)
↓
Phase 5: Validation & Creation (검증 및 생성)Phase 1: 목적 발견
위자드가 핵심 질문을 던집니다.
- “이 서브에이전트가 처리할 작업은 무엇인가요?”
- “트리거되어야 하는 요청 예시 2-3개를 알려주세요”
- “자동 위임이 필요한가요, 명시적 호출만 필요한가요?”
Phase 2: 구성 설계
Description 작성이 가장 중요합니다. 위자드가 공식을 제공합니다.
[What it does]. [When to use]. [Proactive trigger]예시:
# 자동 위임용
description: Expert code reviewer. Use PROACTIVELY after code modifications.
# 명시적 호출용
description: Documentation writer. Use when user explicitly requests docs.도구 선택도 가이드합니다.
| 카테고리 | 도구 | 용도 |
|---|---|---|
| 읽기 전용 | Read, Grep, Glob, Bash | 코드 분석, 감사 |
| 수정 가능 | Read, Write, Edit, Grep, Glob, Bash | 버그 수정, 기능 개발 |
| 최소 권한 | Read, Grep, Glob | 보안 리뷰 |
| 전체 접근 | (필드 생략) | 범용 |
Phase 3: 시스템 프롬프트 작성
효과적인 프롬프트 구조:
You are an expert [role/specialty].
When invoked:
1. [First action]
2. [Second action]
3. [Third action]
Key responsibilities:
- [Responsibility 1]
- [Responsibility 2]
Output format:
- [What to include]
- [How to structure]Phase 4-5: 범위 선택 및 생성
.claude/agents/– 프로젝트 전용 (높은 우선순위)~/.claude/agents/– 사용자 전체 (모든 프로젝트)
최종 검증 체크리스트를 거쳐 파일을 생성합니다.
효과: 무엇이 달라지나?
Before (subagent-wizard 없이)
- subagent-creator 문서 읽기
- 예시 파일 찾아보기
- Description 어떻게 쓸지 고민
- 도구 뭘 줄지 시행착오
- 프롬프트 작성 후 테스트
- 트리거 안 되면 다시 수정…
After (subagent-wizard 사용)
- “서브에이전트 만들어줘”
- 질문에 답변
- 생성된 파일 확인
- 끝
제공되는 템플릿 (8가지)
| 유형 | 용도 |
|---|---|
| Code Reviewer | 품질 및 보안 리뷰 |
| Debugger | 오류 분석 및 수정 |
| Test Runner | 테스트 실행 및 수정 |
| Data Analyst | SQL 및 데이터 인사이트 |
| Doc Writer | 문서 작성 |
| Security Auditor | 취약점 스캔 |
| API Developer | REST/GraphQL 개발 |
| DevOps Engineer | CI/CD 및 인프라 |
실제 사용 예시
PR 리뷰어 서브에이전트를 만들어보겠습니다.
1. 위자드 시작
나: "PR 리뷰하는 서브에이전트 만들어줘"
Claude: Phase 1 - 목적 발견
"이 서브에이전트가 처리할 작업은 무엇인가요?"2. 질문 응답
나: "GitHub PR 변경사항을 분석하고 리뷰해주는 에이전트"
Claude: "트리거 예시 2-3개를 알려주세요"
나: "PR 리뷰해줘", "이 PR 확인해줘", "변경사항 검토해줘"3. 생성된 결과
---
name: pr-reviewer
description: GitHub PR review specialist. Use PROACTIVELY when reviewing pull requests or analyzing code changes.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior PR reviewer.
When invoked:
1. Run `gh pr view` to get PR details
2. Run `gh pr diff` to see all changes
3. Analyze each changed file systematically
Output format:
## PR Summary
[Brief description]
## Issues Found
- Critical: [Must fix]
- Warning: [Should fix]
- Suggestion: [Nice to have]
## Recommendation
[Approve / Request Changes]설치 방법
# Claude Code skills 디렉토리에 클론
git clone https://github.com/greeun/subagent-wizard.git ~/.claude/skills/subagent-wizard
# Claude Code 재시작 후 사용
저장소 구조
subagent-wizard/
├── SKILL.md # 5단계 위자드 가이드
├── LICENSE.txt # Apache 2.0 라이선스
├── README.md / README.ko.md # 영어/한국어 문서
├── references/
│ ├── tool-combinations.md # 도구 선택 가이드
│ ├── type-templates.md # 8가지 유형별 템플릿
│ └── description-examples.md # Description 작성 예시
└── assets/
└── subagent-template.md # 기본 템플릿마치며
subagent-wizard는 서브에이전트 생성의 진입 장벽을 낮춥니다.
- 문서 대신 질문: 읽을 필요 없이 답변만 하면 됨
- 시행착오 감소: 검증된 템플릿과 가이드 제공
- 즉시 사용 가능: 8가지 유형별 템플릿
반복되는 요청을 자동화하고 싶다면, subagent-wizard로 서브에이전트를 만들어보세요.