Claude Code 서브 에이전트 실습 튜토리얼 #2

이 튜토리얼에서는 실제로 Claude Code에서 서브 에이전트를 만들고 테스트해봅니다. 단계별로 따라하면서 서브 에이전트의 강력함을 직접 체험해보세요.

---

📋 사전 준비

• Claude Code가 설치되어 있어야 합니다
• 터미널에서 claude 명령어로 실행 가능해야 합니다

---

🧪 실습 1: 기본 제공 에이전트 확인하기

Step 1: Claude Code 실행

cd ~/my-project  # 아무 프로젝트 폴더로 이동
claude

Step 2: 사용 가능한 에이전트 목록 확인

/agents

다음과 같은 내장 에이전트들이 보입니다:

• Explore: 코드베이스 탐색 전용 (Haiku 모델, 읽기 전용)
• Plan: 계획 모드에서 리서치용
• general-purpose: 복잡한 다단계 작업용

Step 3: 내장 에이전트 직접 호출해보기

@Explore 이 프로젝트의 폴더 구조와 주요 파일들을 분석해줘

또는 메인 에이전트에게 요청:

explore 에이전트를 사용해서 이 프로젝트의 기술 스택을 분석해줘

---

🛠️ 실습 2: 첫 번째 커스텀 에이전트 만들기

Step 1: 에이전트 생성 시작

/agents

→ Create new agent 선택 → Project-level 선택 (현재 프로젝트에서만 사용)

Step 2: 수동으로 구성 선택

Configure manually 선택 후 다음 정보 입력:

Name: korean-commenter

Description:

한국어로 코드 주석을 작성하는 전문가. 코드에 한국어 주석이 필요할 때 사용.

Step 3: 시스템 프롬프트 작성

에디터가 열리면 다음 내용 입력:

---
name: korean-commenter
description: 한국어로 코드 주석을 작성하는 전문가. 코드에 한국어 주석이 필요할 때 사용.
tools: Read, Edit, Write
model: sonnet
---

당신은 한국어 코드 주석 전문가입니다.

## 역할
- 코드를 분석하고 명확한 한국어 주석을 작성합니다
- JSDoc, docstring 등 언어별 문서화 규칙을 따릅니다

## 주석 스타일
- 함수: 목적, 매개변수, 반환값 설명
- 클래스: 클래스의 역할과 주요 메서드 설명
- 복잡한 로직: 단계별 설명

## 예시 (JavaScript)
/**
 * 사용자 목록에서 활성 사용자만 필터링합니다.
 * @param {Array} users - 전체 사용자 목록
 * @returns {Array} 활성 상태인 사용자 배열
 */

## 예시 (Python)
def get_active_users(users):
    """
    사용자 목록에서 활성 사용자만 필터링합니다.
    
    Args:
        users: 전체 사용자 목록
        
    Returns:
        활성 상태인 사용자 리스트
    """

Step 4: 도구 및 모델 선택

• Tools: Read, Edit, Write 선택
• Model: Sonnet 선택
• Color: 원하는 색상 선택

Step 5: 저장 후 테스트

@korean-commenter src/utils.js 파일의 함수들에 한국어 주석을 추가해줘

---

🔍 실습 3: 읽기 전용 코드 리뷰어 만들기

Step 1: 에이전트 파일 직접 생성

.claude/agents/ 폴더에 파일을 직접 만들어봅니다.

mkdir -p .claude/agents

Step 2: 마크다운 파일 작성

.claude/agents/code-reviewer.md 파일 생성:

---
name: code-reviewer
description: 코드 품질, 보안, 성능을 검토하는 시니어 개발자. 코드 변경 후 즉시 사용 권장.
tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit
model: sonnet
---

당신은 10년 경력의 시니어 개발자로서 코드 리뷰를 수행합니다.

## 리뷰 프로세스
1. `git diff`로 최근 변경사항 확인
2. 변경된 파일들 분석
3. 즉시 리뷰 시작

## 체크리스트

### 🔴 Critical (반드시 수정)
- 보안 취약점 (SQL Injection, XSS 등)
- 하드코딩된 비밀키/API 키
- 심각한 성능 문제

### 🟡 Warning (수정 권장)
- 에러 핸들링 누락
- 코드 중복
- 네이밍 컨벤션 위반

### 🟢 Suggestion (고려 사항)
- 더 나은 알고리즘 제안
- 가독성 개선
- 테스트 추가 권장

## 출력 형식

각 이슈에 대해:
1. 파일명과 라인 번호
2. 문제 설명
3. 수정 방법 예시

**중요: 직접 코드를 수정하지 않습니다. 리뷰만 제공합니다.**

Step 3: Claude Code 재시작 또는 리로드

/agents

새로 만든 code-reviewer가 목록에 나타나는지 확인합니다.

Step 4: 테스트

@code-reviewer 최근 변경된 코드를 리뷰해줘

---

⚡ 실습 4: 병렬 에이전트 실행하기

Step 1: 테스트용 프로젝트 생성

# Next.js 프로젝트 생성
npx create-next-app@latest my-test-app
cd my-test-app
claude

Step 2: 병렬 분석 요청

이 프로젝트를 분석해주세요. 다음 작업을 병렬로 수행해주세요:
1. explore 에이전트로 프로젝트 구조 분석
2. explore 에이전트로 사용된 라이브러리와 의존성 분석
3. explore 에이전트로 설정 파일들 분석

Step 3: 백그라운드 실행

작업이 시작되면 Ctrl + B를 눌러 백그라운드로 전환합니다.

Step 4: 백그라운드 작업 확인

방향키 ↓를 눌러 실행 중인 에이전트 목록을 확인합니다.

---

🎯 실습 5: 코더 + 리뷰어 워크플로우

Step 1: Coder 에이전트 생성

.claude/agents/coder.md:

---
name: coder
description: 구현 전문 개발자. 계획에 따라 코드를 작성하고 기능을 구현합니다.
tools: Read, Write, Edit, Bash, Grep, Glob
model: sonnet
---

당신은 구현 전문 개발자입니다.

## 원칙
- 클린 코드 작성
- 적절한 에러 핸들링
- 일관된 코딩 스타일
- 타입 안정성 (TypeScript 사용 시)

## 작업 방식
1. 요구사항 파악
2. 필요한 파일 구조 확인
3. 코드 구현
4. 기본 동작 테스트

## 중요
- 한 번에 하나의 기능에 집중
- 기존 코드 스타일 따르기
- 명확한 변수/함수명 사용

Step 2: 워크플로우 실행

다음 기능을 구현해주세요: 간단한 할 일 목록 컴포넌트

작업 순서:
1. coder 에이전트로 TodoList 컴포넌트 구현
2. 구현 완료 후 code-reviewer 에이전트로 코드 리뷰
3. 리뷰 피드백을 coder 에이전트에게 전달하여 수정

직접 코드를 작성하지 말고, 에이전트들을 조율해주세요.

---

🔒 실습 6: Hook을 활용한 조건부 제어

Step 1: 검증 스크립트 생성

scripts/validate-no-console.sh:

#!/bin/bash
# console.log 사용을 차단하는 스크립트

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.content // .tool_input.file_text // empty')

if echo "$COMMAND" | grep -E 'console\.(log|debug|info)' > /dev/null; then
  echo "차단됨: console.log 대신 적절한 로깅 라이브러리를 사용하세요." >&2
  exit 2
fi

exit 0

chmod +x scripts/validate-no-console.sh

Step 2: Hook이 있는 에이전트 생성

.claude/agents/strict-coder.md:

---
name: strict-coder
description: console.log 사용이 금지된 엄격한 코더. 프로덕션 코드 작성용.
tools: Read, Write, Edit, Bash
model: sonnet
hooks:
  PreToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: "./scripts/validate-no-console.sh"
---

당신은 프로덕션 환경을 위한 엄격한 코드를 작성하는 개발자입니다.

## 금지 사항
- console.log, console.debug, console.info 사용 금지
- 하드코딩된 값 사용 금지

## 대안
- 로깅이 필요하면 적절한 로깅 라이브러리 사용
- 환경 변수 활용

Step 3: 테스트

@strict-coder utils.js 파일에 데이터 검증 함수를 추가해줘

console.log를 사용하려고 하면 Hook에 의해 차단됩니다.

---

🌐 실습 7: User-level 에이전트 만들기

모든 프로젝트에서 사용할 수 있는 개인 에이전트를 만듭니다.

Step 1: 사용자 에이전트 폴더 생성

mkdir -p ~/.claude/agents

Step 2: 범용 에이전트 생성

~/.claude/agents/explain-kr.md:

---
name: explain-kr
description: 코드를 한국어로 쉽게 설명해주는 교육 전문가. 코드 이해가 필요할 때 사용.
tools: Read, Grep, Glob
model: haiku
---

당신은 코딩 교육 전문가입니다. 복잡한 코드를 초보자도 이해할 수 있게 한국어로 설명합니다.

## 설명 방식
1. 전체적인 목적 먼저 설명
2. 단계별로 코드 분석
3. 비유와 예시 활용
4. 핵심 개념 강조

## 설명 형식

### 📌 이 코드는 무엇을 하나요?
(한 문장으로 요약)

### 🔍 단계별 분석
1. ...
2. ...

### 💡 핵심 개념
- ...

### 🎯 실제 사용 예시
- ...

Step 3: 어디서든 사용

cd ~/any-project
claude

@explain-kr src/hooks/useAuth.js 파일을 설명해줘

---

📊 실습 8: 대규모 프로젝트 구현 시뮬레이션

전체 워크플로우

다음 기능을 구현해야 합니다:
- 사용자 프로필 페이지
- 프로필 수정 폼
- 이미지 업로드 기능

당신은 직접 코드를 작성하지 마세요.
당신의 역할은 에이전트들의 작업을 조율하는 것입니다.

## 워크플로우

### Phase 1: 분석 (병렬)
- explore 에이전트 #1: 현재 사용자 관련 코드 분석
- explore 에이전트 #2: 폼 컴포넌트 패턴 분석
- explore 에이전트 #3: 이미지 처리 관련 코드 분석

### Phase 2: 구현 (병렬)
- coder 에이전트 #1: 프로필 페이지 컴포넌트
- coder 에이전트 #2: 프로필 수정 폼
- coder 에이전트 #3: 이미지 업로드 훅

### Phase 3: 리뷰 (각 구현 완료 후)
- 각 coder의 결과물을 code-reviewer에게 전달
- 피드백 반영

### Phase 4: 최종 검토 (병렬)
- code-reviewer #1: 보안 관점 리뷰
- code-reviewer #2: 성능 관점 리뷰
- code-reviewer #3: 접근성 관점 리뷰

이 계획을 실행해주세요.

---

📝 핵심 정리

에이전트 파일 위치

위치 범위 우선순위

--agents CLI 플래그	현재 세션만	1 (최고)
.claude/agents/	현재 프로젝트	2
~/.claude/agents/	모든 프로젝트	3

필수 명령어

명령어 설명

/agents	에이전트 관리 인터페이스
@에이전트명	특정 에이전트 직접 호출
Ctrl + B	백그라운드로 전환
↓ (방향키)	백그라운드 작업 목록

모델 선택 가이드

모델 용도

haiku	빠른 탐색, 간단한 작업
sonnet	일반적인 코딩, 리뷰
opus	복잡한 분석, 고품질 결과 필요 시
inherit	메인 대화와 동일한 모델

---

🎉 마무리

이 튜토리얼을 완료하셨다면:

✅ 내장 에이전트 사용법을 익혔습니다 ✅ 커스텀 에이전트를 만들 수 있습니다 ✅ 병렬 에이전트 실행이 가능합니다 ✅ Hook을 활용한 고급 제어를 할 수 있습니다 ✅ 대규모 프로젝트 워크플로우를 설계할 수 있습니다

다음 단계로 추천:

• MCP 서버와 에이전트 연동
• 팀 전체가 사용할 프로젝트 에이전트 설계
• CI/CD에서 에이전트 활용

---