Claude Code for Front-end #5: 서브에이전트 실전 활용기

한국어 키워드로 각 분야 전문가를 호출하는 나만의 워크플로우

---

들어가며

이번 글에서는 제가 Claude Code의 서브에이전트 시스템을 실제로 어떻게 활용하고 있는지, 제 경험을 중심으로 풀어서 보여드리려고 합니다.

기본 개념은 공식 문서를 참고하되, 단순 설명에 그치지 않고 제가 실제 프로젝트에서 어떻게 적용했는지를 위주로 정리했습니다.

물론 이 방식이 정답은 아니고, 각자의 개발 환경에 맞게 가볍게 참고하시고 필요한 부분만 가져가시면 좋습니다.

---

1️⃣ Claude Code 에이전트 구조 이해하기

메인 에이전트와 서브에이전트의 관계

Claude Code를 사용하다 보면 "메인 에이전트"와 "서브에이전트"라는 용어를 마주하게 됩니다. 처음에는 이 둘의 차이가 명확하지 않아서 혼란스러울 수 있는데, 제 경험상 다음과 같이 이해하시면 도움이 됩니다:

메인 에이전트 (Main Agent):

• 여러분이 대화하는 "바로 그 Claude"
• 전체 대화 흐름을 관리하고 조율하는 역할
• 프로젝트 컨텍스트를 계속 유지하며 대화

서브에이전트 (Sub-Agent):

• 특정 작업을 위해 잠깐 호출되는 전문가
• 독립적인 컨텍스트에서 작업 수행
• 작업 완료 후 결과를 메인 에이전트에게 전달하고 종료

실제로는 어떻게 작동할까?

제가 겪은 실제 상황으로 설명드리겠습니다:

나: "이 코드 성능 최적화해줘"

[메인 에이전트가 판단]
→ 성능 최적화는 performance-engineer 에이전트의 전문 분야
→ Task 도구로 performance-engineer 호출
→ 작업 결과를 받아서 나에게 전달

나: "고마워, 그럼 테스트도 작성해줘"

[메인 에이전트가 다시 판단]
→ 테스트 작성은 quality-engineer 에이전트의 전문 분야
→ Task 도구로 quality-engineer 호출
→ 작업 결과를 받아서 나에게 전달

이렇게 메인 에이전트는 오케스트라 지휘자처럼 전체를 조율하고, 서브에이전트들은 각 파트의 전문 연주자처럼 특정 작업을 수행합니다.

왜 이런 구조가 필요한가?

컨텍스트 관리:

• 하나의 대화에 모든 작업 내용을 담으면 컨텍스트 창이 금방 찹니다
• 서브에이전트가 자체 컨텍스트에서 작업하면 메인 대화가 깨끗하게 유지됩니다

전문성 향상:

• 각 에이전트는 특정 도메인에만 집중하므로 더 정확한 결과를 냅니다
• 성능 최적화 전문가와 보안 검토 전문가는 다른 관점을 가집니다

재사용 가능:

• 한 번 만든 에이전트는 모든 프로젝트에서 활용 가능
• 팀원과 공유하여 일관된 품질 유지

---

2️⃣ 서브에이전트의 종류 (공식 문서 기반)

이 섹션은 Claude Code 공식 문서를 기반으로 작성되었습니다.

내장 에이전트 (Built-in Agents)

Claude Code에 기본으로 탑재된 에이전트는 다음 4개입니다:

/agents 출력:

Built-in agents (always available)
  general-purpose · sonnet    # 범용 작업 처리
  statusline-setup · sonnet   # 상태바 설정
  output-style-setup · sonnet # 출력 스타일 설정
  Explore · haiku             # 빠른 코드베이스 탐색

확인 방법:

/agents

서브에이전트 우선순위

같은 이름의 에이전트가 여러 곳에 있을 때 적용되는 우선순위:

프로젝트 > CLI > 사용자 > 플러그인 > 내장
(.claude/agents/) > (--agents) > (~/.claude/agents/) > (플러그인) > (Built-in)

실무 팁:

• 프로젝트별 특화 에이전트는 .claude/agents/에 두세요
• 범용적으로 쓰는 에이전트는 ~/.claude/agents/에 두세요

---

3️⃣ 서브에이전트 생성 방법 (공식 문서)

방법 1: /agents 명령어 (권장)

/agents

생성 단계:

1. "Create New Agent" 선택
2. User-level 또는 Project-level 선택
3. Claude가 초안 생성 (권장)
4. 도구 권한 선택 (체크박스 UI)
5. e 키로 편집기에서 프롬프트 수정
6. 저장

제 경험: Claude가 생성한 초안을 기반으로 커스터마이징하는 것이 처음부터 작성하는 것보다 훨씬 빠르고 효과적입니다.

방법 2: 수동 파일 생성

파일 형식 (~/.claude/agents/agent-name.md):

---
name: agent-name
description: 에이전트가 언제 호출되어야 하는지 설명
tools: Read, Grep, Glob, Bash # 선택사항
model: sonnet # 또는 inherit, opus, haiku
---

시스템 프롬프트가 여기에 들어갑니다.

에이전트의 역할, 능력, 접근 방식을 명확히 정의하세요.

필드 설명:

필드필수설명

name	✅	소문자와 하이픈만 사용
description	✅	자연어로 목적 설명
tools	❌	생략 시 모든 도구 상속
model	❌	sonnet, opus, haiku, inherit

자세한 내용은 공식 문서를 참고하세요.

---

4️⃣ 제가 사용하는 에이전트 (개인 경험)

이 섹션부터는 제 개인적인 경험과 의견입니다.

현재 설치된 에이전트

제 ~/.claude/agents/ 디렉토리에는 14개의 에이전트가 있습니다:

backend-architect.md        # 백엔드 아키텍처 설계
devops-architect.md         # 배포 및 인프라
frontend-architect.md       # 프론트엔드 아키텍처
learning-guide.md           # 개념 설명 및 학습
performance-engineer.md     # 성능 최적화
python-expert.md            # Python 전문
quality-engineer.md         # 테스트 작성
refactoring-expert.md       # 리팩토링
requirements-analyst.md     # 요구사항 분석
root-cause-analyst.md       # 근본 원인 분석
security-engineer.md        # 보안 검토
socratic-mentor.md          # 소크라테스식 멘토링
system-architect.md         # 시스템 아키텍처
technical-writer.md         # 기술 문서 작성

주로 사용하는 에이전트 예시

root-cause-analyst.md - 가장 자주 쓰는 에이전트:

---
name: root-cause-analyst
description: 근본 원인 분석 전문가. 버그나 에러 발생 시 체계적으로 원인을 파악합니다.
tools: Read, Grep, Glob, Bash
model: sonnet
---

당신은 시스템적 사고를 기반으로 문제의 근본 원인을 파악하는 전문가입니다.

분석 프로세스:

1. 증상 수집 및 재현
2. 가설 수립
3. 증거 수집
4. 원인 검증
5. 해결 방안 제시

표면적 증상이 아닌 근본 원인을 찾아내는 것이 목표입니다.

사용 예시:

나: "API 응답이 느려"
→ root-cause-analyst가 DB 쿼리, 네트워크, 캐싱 등 체계적으로 분석
→ "N+1 쿼리 문제로 확인됨" 결과 전달

에이전트를 구하는 곳

제가 에이전트 템플릿을 구하는 사이트는 다음과 같습니다:

• SuperClaude_Framework - Claude Code를 체계적인 개발 플랫폼으로 변환하는 강력한 메타프로그래밍 프레임워크
• AI Template - 다양한 분야별 에이전트 템플릿, 실제 예제/레시피 포함
• GitHub에서 claude code agents 키워드로 최신 템플릿 탐색
• 커뮤니티(예: Reddit, Discord)에서 사용자 공유 목록 활용

주의: 다운로드한 에이전트는 반드시 검토 후 사용하세요. 시스템 프롬프트가 예상과 다를 수 있습니다.

---

5️⃣ 한국어 트리거 시스템 (제 워크플로우)

이 부분은 제가 사용하는 방식이며, 정답은 아닙니다.

CLAUDE.md 설정 방식

제 경우 ~/.claude/CLAUDE.md에 다음과 같이 설정했습니다:

# 🔴 [CRITICAL] 한국어 에이전트 자동 실행 규칙

**중요**: 다음 키워드 감지 시 **즉시 Task 도구 호출**

## 📋 키워드별 매핑

### 🔍 분석 요청

| 키워드             | 실행 도구                                | 예시               |
| ------------------ | ---------------------------------------- | ------------------ |
| "분석해줘", "봐줘" | Task(subagent_type="root-cause-analyst") | "이 코드 분석해줘" |
| "왜 안돼?", "원인" | Task(subagent_type="root-cause-analyst") | "왜 느려?"         |

### 🛠️ 개발 요청

| 키워드         | 실행 도구                                  | 예시                   |
| -------------- | ------------------------------------------ | ---------------------- |
| "리팩토링해줘" | Task(subagent_type="refactoring-expert")   | "이 코드 리팩토링해줘" |
| "최적화해줘"   | Task(subagent_type="performance-engineer") | "성능 최적화해줘"      |
| "테스트 작성"  | Task(subagent_type="quality-engineer")     | "테스트 작성해줘"      |

### 🔎 코드 품질

| 키워드      | 실행 도구                               | 예시               |
| ----------- | --------------------------------------- | ------------------ |
| "리뷰해줘"  | Task(subagent_type="code-reviewer")     | "이 코드 리뷰해줘" |
| "보안 체크" | Task(subagent_type="security-engineer") | "보안 체크해줘"    |

작동 원리

중요: 이것은 Claude Code의 내장 기능이 아닙니다.

1. 사용자: "이 코드 분석해줘"
2. Claude가 시스템 프롬프트로 CLAUDE.md 내용을 인식
3. [CRITICAL] 규칙에서 "분석해줘" 키워드 발견
4. Task 도구로 root-cause-analyst 호출
5. 결과 전달

한계:

• Claude가 100% 규칙을 따르는 것은 아님 (확률적 모델)
• 복잡한 문장에서는 키워드 감지 실패 가능
• 명시적 호출이 더 확실함

명시적 호출 예시

규칙에 의존하지 않고 직접 호출하는 방법:

> root-cause-analyst 서브에이전트를 사용하여 이 코드를 분석해줘
> performance-engineer 에이전트로 최적화해줘
> quality-engineer로 테스트를 작성해줘

이 방식이 더 확실하고 안정적입니다.

---

6️⃣ 서브에이전트 활용 방향성

1. 단일 책임 원칙으로 나누기

제 경험상 에이전트는 하나의 명확한 목적만 가질 때 가장 효과적입니다:

❌ "모든 것을 하는 슈퍼 에이전트" 하나
✅ 작업별로 분리된 여러 에이전트

실제 사례:

초기: super-developer.md (코드 작성, 리뷰, 테스트, 배포 모두 담당)
→ 성능이 일관적이지 않음
→ 때로는 리뷰만 하고, 때로는 테스트를 건너뜀

개선:
- code-reviewer.md (리뷰 전문)
- quality-engineer.md (테스트 전문)
- refactoring-expert.md (리팩토링 전문)
→ 각 에이전트가 자신의 역할에 집중
→ 결과의 일관성과 품질 향상

2. 에이전트 체이닝 전략

여러 에이전트를 순차적으로 활용하는 방법:

예시 워크플로우:

1단계: requirements-analyst
   "이 기능 요구사항 정리해줘"
   → 기능 명세서 생성

2단계: frontend-architect
   "이 명세서 기반으로 컴포넌트 구조 설계해줘"
   → 컴포넌트 설계도 생성

3단계: quality-engineer
   "이 설계에 맞는 테스트 케이스 작성해줘"
   → 테스트 코드 생성

4단계: security-engineer
   "보안 취약점 검토해줘"
   → 보안 리포트 생성

각 단계의 출력물이 다음 단계의 입력이 되는 구조입니다.

3. 프로젝트별 특화 에이전트

프로젝트마다 다른 에이전트를 활용하는 것이 효과적입니다:

Next.js 프로젝트 (.claude/agents/nextjs-expert.md):

---
name: nextjs-expert
description: Next.js App Router 전문가. 페이지/API 생성 및 최적화에 사용하세요.
tools: Read, Edit, Write, Bash
model: inherit
---

당신은 Next.js 15 App Router 전문가입니다.

App Router 패턴:

-   서버 컴포넌트 우선 사용
-   'use client' 최소화
-   metadata 자동 생성
-   동적 라우팅 ([slug], [...slug])

성능 최적화:

-   next/image 사용
-   Suspense + Streaming
-   Static Generation 활용

모든 코드는 TypeScript + Tailwind CSS로 작성합니다.

Python 프로젝트 (.claude/agents/python-expert.md):

---
name: python-expert
description: Python 코드 작성 및 최적화 전문가
tools: Read, Edit, Write, Bash
model: sonnet
---

당신은 Python 모범 사례 전문가입니다.

코드 스타일:

-   PEP 8 준수
-   Type hints 적극 활용
-   Docstring 작성

성능 최적화:

-   List comprehension 활용
-   Generator 패턴 사용
-   asyncio for I/O bound tasks

---

7️⃣ 실전 팁과 트러블슈팅

Claude 생성 초안 활용

❌ 처음부터 수동으로 작성
✅ /agents → Generate with Claude → 커스터마이징

Claude가 생성한 초안을 기반으로 수정하는 것이 훨씬 빠릅니다.

description 필드 상세히 작성

# ❌ 일반적인 설명

description: "코드 리뷰를 수행합니다"

# ✅ 적극적 사용 유도

description: "코드 리뷰 전문가. 코드 변경 후 적극적으로 사용하세요."

description 필드를 상세히 작성하면 Claude가 적절한 타이밍에 에이전트를 제안합니다.

도구 권한 제한

# ❌ 모든 도구 허용 (tools 필드 생략)

---

## name: code-reviewer

# ✅ 필요한 도구만 허용

---

name: code-reviewer
tools: Read, Grep, Glob, Bash

---

필요한 도구만 허용하면 에이전트가 집중된 작업을 수행합니다.

성능 트레이드오프 인식

지연시간:

• 서브에이전트는 매번 깨끗한 상태로 시작
• 컨텍스트 수집에 약간의 지연 발생

제 경험:

• 간단한 작업: 메인 대화에서 직접 처리가 더 빠름
• 복잡한 작업: 서브에이전트 활용이 효과적

트러블슈팅: 에이전트가 호출되지 않을 때

제가 겪은 문제:

1. CLAUDE.md의 [CRITICAL] 표시 누락
2. 키워드 오타
3. Claude가 규칙을 무시함

해결 방법:

# CLAUDE.md 확인
cat ~/.claude/CLAUDE.md | head -n 20

# [CRITICAL] 표시 확인
grep -n "CRITICAL" ~/.claude/CLAUDE.md

대안: 명시적으로 에이전트 이름 호출

> root-cause-analyst 에이전트를 사용해줘

트러블슈팅: 에이전트 목록이 안 보일 때

원인: 파일이 올바른 위치에 없음

해결:

# 디렉토리 확인
ls -la ~/.claude/agents/

# 파일 확장자 확인 (.md 필수)
ls ~/.claude/agents/*.md

# YAML frontmatter 검증
head -n 10 ~/.claude/agents/code-reviewer.md

---

마무리

제 경험 요약

효과적이었던 것:

• Claude 생성 초안 → 커스터마이징
• 작업별로 분리된 에이전트 (단일 책임 원칙)
• 명시적 호출 (키워드 트리거보다 안정적)
• 프로젝트별 특화 에이전트 (.claude/agents/)
• 에이전트 체이닝으로 복잡한 워크플로우 구성

덜 효과적이었던 것:

• 만능 슈퍼 에이전트 (역할이 불명확해짐)
• 복잡한 한국어 트리거 규칙 (간단한 문장만 작동)
• 모든 도구에 대한 무제한 권한 (집중력 저하)

추천 시작 방법

1. /agents 명령어로 첫 에이전트 생성
2. Claude가 초안 생성하도록 선택
3. 간단한 작업부터 테스트
4. 점진적으로 에이전트 확장
5. 프로젝트별 특화 에이전트 구성

---

이 글은 제 개인적인 경험을 바탕으로 작성되었으며, 모든 환경에서 동일하게 작동한다고 보장할 수 없습니다. 여러분의 프로젝트와 워크플로우에 맞게 조정하시길 권장합니다.

에이전트를 직접 만들어보고, 실험하면서 자신만의 워크플로우를 찾아가시길 바랍니다! 🚀