9. 내 업무 전용 AI 만들기 - Subagents

서브에이전트 = 내 워크플로우를 저장하는 것

이전 글에서 이런 AI 직원들을 봤다:

youtube-content-analyzer  → 영상 정리 4분
business-strategist       → 전략 수립 30분
cafe-launch-pm           → 프로젝트 기획 10분
seo-optimizer            → 발행 전 점검 2분

"이런 거 나도 만들 수 있을까?" "코드 짜야 하는 거 아냐?"

결론부터 말하자면:

❌ 코드 작성 필요 없다
❌ 개발 지식 필요 없다
✅ Claude에게 만들어달라고 시키면 된다
✅ 내 워크플로우만 설명하면 끝

슬래시 커맨드 만들 때를 떠올려 보자

이전 글에서 슬래시 커맨드를 만들었을 때:

나: "Claude, /idea 커맨드 만들어줘"

    # 내가 설명한 것
    - 아이디어를 카테고리별로 저장
    - 파일명은 날짜-제목.md
    - 위치는 40-personal/44-ideas/

Claude: [.claude/commands/idea.md 생성]
        ✅ 완료!

나: "/idea business 카페 메뉴 기획 아이디어"
→ 3초에 저장 완료

서브에이전트도 정확히 똑같다.

단지 더 복잡한 워크플로우를 설명하는 것이다.

차이점: 단순 vs 복잡

슬래시 커맨드 (5초 작업):

나: "아이디어 저장해줘"
Claude: [저장 완료]

서브에이전트 (10분 작업):

나: "YouTube 영상 분석해줘"

Claude: [에이전트 실행 중...]
        1. CLI로 자막 추출
        2. 메타데이터 수집
        3. 핵심 포인트 추출
        4. 타임스탬프 기록
        5. JSON 구조화
        ✅ 4분에 완료

핵심 차이:
- 슬래시 커맨드 = 프롬프트 하나 (.claude/commands/)
- 서브에이전트 = 워크플로우 여러 단계 (.claude/agents/)

서브에이전트는 어떻게 생겼을까

파일 구조

프로젝트 레벨 (팀 공유):
.claude/agents/agent-name.md

사용자 레벨 (나만 사용):
~/.claude/agents/agent-name.md

우선순위:
- 프로젝트 > 사용자
- 같은 이름이면 프로젝트 버전 우선

파일 내용

---
name: youtube-content-analyzer
description: YouTube 영상 자막 추출 및 분석
model: sonnet
tools: Read, Bash, Write
---

# YouTube Content Analyzer

You are a YouTube content analyzer...

## Process
1. Extract transcript using CLI
2. Collect metadata
3. Extract key points
4. Generate JSON output

## Output Format
...

구성 요소:
1. YAML 설정 (맨 위 --- 사이)
2. 시스템 프롬프트 (에이전트 역할 설명)

YAML 설정 이해하기

필수 항목 2개

---
name: agent-name              # 필수: 에이전트 이름
description: 언제 사용하는지   # 필수: Claude가 자동 실행 판단
---

중요: description이 핵심이다!

# ❌ 나쁜 예 (너무 모호)
description: Help with YouTube videos

# ✅ 좋은 예 (명확한 트리거)
description: YouTube 영상 자막 추출 및 분석. URL 입력 시 자동 실행.

Claude는 description을 읽고 "아, 이럴 때 이 에이전트 써야겠구나" 판단한다.

선택 항목 2개

---
name: agent-name
description: ...
model: sonnet        # 선택: 모델 지정
tools: Read, Write   # 선택: 도구 권한
---

1. model (모델 선택)

모델	언제?	속도	비용
haiku	간단한 작업	⚡⚡⚡ 매우 빠름	💰 저렴
sonnet	대부분 작업 (기본값)	⚡⚡ 빠름	💰💰 보통
opus	복잡한 전략 수립	⚡ 느림	💰💰💰 비쌈

실전 예시:

# 파일 검색 (haiku)
model: haiku

# 콘텐츠 생성 (sonnet, 기본값)
model: sonnet

# 전략 분석 (opus)
model: opus

---

2. tools (도구 권한)

왜 필요해요?
- 보안: 필요한 도구만 허용
- 명확성: "이 에이전트는 파일만 읽어요"

주요 도구:

# 읽기 전용
tools: Read, Grep, Glob

# 파일 수정
tools: Read, Edit, Write

# 시스템 명령어
tools: Read, Bash

# 전체 권한 (생략 시 기본값)
# tools 필드 없음 = 모든 도구 사용 가능

실전 예시:

# YouTube 분석기 (CLI 실행 필요)
tools: Read, Bash, Write

# SEO 점검기 (파일 읽기만)
tools: Read

# Ghost 발행기 (파일 + 명령어)
tools: Read, Write, Bash

---

🛠 실제로 만들어봅시다

예제: 간단한 youtube-content-analyzer

이전 글에서 본 그 에이전트, 이제 만들어볼게요.

---

Step 1: 먼저 Claude에게 물어보기

일단 자연어로 편하게 물어보세요:

나: "YouTube 영상 자막을 자동으로 추출하고 정리해주는
     서브에이전트 만들고 싶은데, 가능할까?

     어떤 순서로 하면 될까?"

Claude: "네, 가능합니다! youtube-content-analyzer를 만들어볼까요?

        필요한 정보:
        1. 어떤 작업을 자동화하고 싶으신가요?
        2. 어떤 도구가 필요한가요? (CLI, API 등)
        3. 어떤 형식으로 결과를 받고 싶으신가요?

        준비되셨으면 /agents 명령어로 시작하시면 됩니다!"

핵심: 막막하면 먼저 Claude와 대화하세요!

---

Step 2: /agents 명령어 실행

Claude Code에서 /agents 입력:

/agents

그러면 이런 메뉴가 나와요:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Agents Management
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 ❯ Create new agent
   View existing agents
   Edit agent
   Delete agent
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

"Create new agent" 선택!

---

Step 3: 저장 위치 선택

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Choose location
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 ❯ 1. Project (.claude/agents/)
   2. Personal (~/.claude/agents/)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

어떤 걸 선택해야 할까?

Project (.claude/agents/):
  ✅ 팀과 공유하고 싶을 때
  ✅ Git에 커밋해서 버전 관리할 때
  ✅ 프로젝트 전용 에이전트

Personal (~/.claude/agents/):
  ✅ 나만 사용하고 싶을 때
  ✅ 모든 프로젝트에서 쓸 때
  ✅ 개인 워크플로우 에이전트

보통 1번 Project 선택 (팀 공유 용이)

---

Step 4: 생성 방법 선택

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Creation method
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 ❯ 1. Generate with Claude (recommended)
   2. Manual configuration
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

거의 항상 1번이에요!

1. Generate with Claude (추천):
  → Claude가 알아서 만들어줌
  → 내가 설명만 하면 됨
  → 초보자 친화적 ✅

2. Manual configuration:
  → YAML 직접 작성
  → 고급 사용자용
  → 필요한 경우에만

1번 선택!

---

Step 5: 자세하게 설명하기 (핵심!)

이제 가장 중요한 단계예요:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Create new agent
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 Describe what this agent should do and
 when it should be used (be comprehensive
 for best results)

 e.g., Help me write unit tests for my code...

 [여기에 입력]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

여기가 핵심이에요! "내가 원하는 결과"를 자연스럽게 설명하세요:

YouTube 영상 자막을 자동으로 추출하고 정리해주는 에이전트를 만들고 싶어요.

지금 문제:
- AI 공부하려고 YouTube 영상 10개를 봤는데 내용 정리가 너무 힘들어요
- 영상 보면서 메모하려니까 계속 일시정지해야 하고
- 중요한 부분 다시 찾으려면 타임라인 뒤적여야 하고
- 영상 하나 정리하는데 3시간씩 걸려요

원하는 결과:
- YouTube URL만 주면 자막을 자동으로 가져왔으면 좋겠어요
- 영상 제목이랑 채널명도 같이 나왔으면 좋겠고
- 핵심 포인트 3-5개 정도로 요약해줬으면 좋겠어요
- "이 부분 중요하다" 싶은 문장이랑 몇 분 몇 초에 나왔는지 알려줬으면 좋겠어요
- 나중에 다시 볼 수 있게 파일로 저장됐으면 좋겠어요

언제 사용:
- YouTube URL 입력하면 자동으로 실행

핵심: "지금 문제"와 "원하는 결과"를 구체적으로!

팁:
- ❌ "CLI 도구로 자막 추출" → 이런 기술 용어 몰라도 돼요
- ✅ "YouTube URL만 주면 자막 가져왔으면" → 이렇게 설명하세요

---

Step 6: Claude가 생성

입력 후 Enter를 누르면:

Claude: "youtube-content-analyzer 에이전트를 생성하고 있습니다..."

        [30초 정도 소요...]

        ✅ 에이전트 생성 완료!

        저장 위치: .claude/agents/youtube-content-analyzer.md

        다음과 같이 구성했습니다:
        - 자막 추출 프로세스
        - 메타데이터 수집
        - 핵심 포인트 추출
        - JSON 출력 형식
        - 에러 처리

        바로 사용하시겠습니까?

재시작 필요 없다! 바로 사용 가능하다.

Step 7: 생성된 내용 확인 (선택)

궁금하면 /agents → "View existing agents"에서 확인 가능하다.

또는 직접 파일 열어보기:

# 프로젝트 레벨
cat .claude/agents/youtube-content-analyzer.md

# 사용자 레벨
cat ~/.claude/agents/youtube-content-analyzer.md

YAML 설정 + 시스템 프롬프트가 저장돼 있다.

Step 8: 바로 사용하기

재시작 필요 없다! 바로 사용 가능하다:

나: "youtube-content-analyzer 사용해서 이 영상 분석해줘"
    https://youtube.com/watch?v=abc123

Claude: [에이전트 실행 중...]
        [4분 소요...]
        ✅ 분석 완료!

수정하고 싶다면

에이전트 만들었는데 수정하고 싶다면?

방법 1: /agents 명령어로 수정

/agents → Edit agent → youtube-content-analyzer 선택

그러면 Claude가 물어본다:

나: "에러 처리 부분을 더 강화해줘"

Claude: [에이전트 프롬프트 수정 중...]
        ✅ 수정 완료!

방법 2: 대화로 수정 요청

나: "youtube-content-analyzer 에이전트
     타임스탬프 형식을 MM:SS로 바꿔줘"

Claude: [에이전트 찾아서 수정]
        ✅ 타임스탬프 형식 변경 완료!

공식 문서 권장사항:

"Claude와 함께 초안을 만든 후 반복 개선"

처음부터 완벽할 필요 없다. 테스트하면서 개선하면 된다.

핵심 개념 4가지

공식 문서에서 강조하는 베스트 프랙티스다.

1. 단일 책임 원칙 (Single Responsibility)

✅ 좋은 예:

name: youtube-content-analyzer
description: YouTube 영상 자막 추출 및 분석

❌ 나쁜 예:

name: content-helper
description: 콘텐츠 관련 다양한 작업 처리

왜?
- 명확한 목적 → Claude가 언제 사용할지 정확히 판단
- 모호한 목적 → Claude가 사용 안 함

---

2. 상세한 프롬프트

✅ 좋은 프롬프트:

## Process

1. Extract transcript using CLI
2. Collect metadata (title, channel)
3. Extract 3-5 key points
4. Generate JSON output

## Output Format
[구체적인 JSON 예시]

## Error Handling
[예상 에러와 대응 방법]

❌ 나쁜 프롬프트:

YouTube 영상 분석해줘

왜?
- 상세할수록 → 일관된 결과
- 모호할수록 → 매번 다른 결과

---

3. 최소 권한 원칙 (도구)

보안과 명확성을 위해 필요한 도구만:

# YouTube 분석 (CLI 필요)
tools: Read, Bash, Write

# SEO 점검 (읽기만)
tools: Read

# 전체 권한 (생략)
# tools 필드 없음

실전 팁:

파일만 읽는다 → tools: Read, Grep, Glob
파일 수정한다 → tools: Read, Edit, Write
명령어 실행한다 → tools: Read, Bash
모든 작업 → tools 생략 (전체 권한)

---

4. Claude와 협업

공식 문서 원문:

"Claude와 함께 초기 서브에이전트를 생성한 다음 반복 개선하는 것이 최상의 결과를 얻습니다"

실전 워크플로우:

1단계: 아이디어 논의
나: "블로그 발행 에이전트 만들고 싶어"
Claude: "어떤 작업을 하나요? 도구는?"

2단계: Claude가 초안 생성
나: "SEO 최적화, 이미지 검증, Ghost 발행"
Claude: [초안 생성]

3단계: 테스트 및 개선
나: "이미지 검증이 너무 엄격해, 완화해줘"
Claude: [수정 및 재테스트]

4단계: 완성 및 저장
.claude/agents/ghost-publisher.md

핵심: 처음부터 완벽할 필요 없다. 테스트하면서 개선하면 된다.

트러블슈팅

문제 1: 에이전트가 실행 안 된다

증상:

나: "youtube-content-analyzer 써줘"
Claude: [일반 응답만 함, 에이전트 실행 안 함]

원인: description이 너무 모호

해결:

# ❌ 나쁜 description
description: Help with YouTube

# ✅ 좋은 description
description: YouTube 영상 자막 추출 및 분석. YouTube URL 입력 시 자동 실행.

팁: "자동 실행", "PROACTIVELY", "when user mentions X" 같은 키워드 추가

문제 2: YAML 오류

증상:

Error: Invalid YAML frontmatter

원인:
- --- 구분자 누락
- 탭 문자 사용 (공백만 허용)

해결:

# ✅ 올바른 형식
---
name: agent-name
description: Clear description
tools: Read, Write
---

# 시작과 끝에 --- 필수!
# 탭 금지, 공백 2칸 들여쓰기

문제 3: 도구 권한 오류

증상:

Error: Tool Bash is not available to this agent

원인: tools 필드에 필요한 도구 미포함

해결:

# CLI 실행 필요하면
tools: Read, Bash, Write

# 또는 전체 권한
# tools 필드 생략

문제 4: 너무 느리다

증상: 응답이 오래 걸림

원인: 불필요하게 opus 사용

해결:

# 간단한 작업
model: haiku

# 보통 작업 (기본값)
model: sonnet

# 복잡한 전략만
model: opus

실전 템플릿

새 에이전트 만들 때 /agents → "Create new agent"에서 이렇게 입력한다:

[에이전트가 할 일]을 도와주는 에이전트를 만들고 싶다.

지금 문제:
- [내가 겪고 있는 구체적인 어려움]
- [얼마나 시간이 걸리는지]
- [왜 힘든지]

원하는 결과:
- [이렇게 됐으면 좋겠다]
- [저렇게 됐으면 좋겠다]
- [결과물 형태]

언제 사용:
- [어떤 상황에서]
- [어떤 키워드 입력하면]

핵심: "지금 문제"를 구체적으로, "원하는 결과"를 자연스럽게!

예시 1: 전략 고민 끝내기

비즈니스 전략 수립을 도와주는 에이전트를 만들고 싶어요.

지금 문제:
- 새로운 사업 기회가 생기면 3-4일 동안 고민만 하고 결정을 못 해요
- "시장이 있을까?" "경쟁자는?" "리스크는?" 이런 질문만 계속 반복하고
- 검색해봐도 정보가 너무 많아서 뭘 믿어야 할지 모르겠고
- 결국 막연한 불안감 때문에 기회를 놓쳐요

원하는 결과:
- "이 사업 할까 말까?"라고 물어보면 명확한 판단 기준을 줬으면 좋겠어요
- 단계별로 뭘 해야 하는지 로드맵이 나왔으면 좋겠고
- 최악의 경우 어떻게 대응할지도 알려줬으면 좋겠어요
- 숫자로 명확하게 (₩얼마, 몇 시간) 나왔으면 좋겠어요

언제 사용:
- "이 사업 어떻게 생각해?" 같은 질문 할 때
- 복잡한 전략 결정이 필요할 때

예시 2: 프로젝트 구조 잡기

카페 브랜딩 프로젝트 구조를 잡아주는 에이전트를 만들고 싶어요.

지금 문제:
- 클라이언트한테 계약서 받으면 "어디서부터 시작하지?" 막막해요
- 머릿속에는 15년 경험이 있는데 정리가 안 돼 있어서
- 매번 노트북 앞에 앉아서 처음부터 정리 시작해요
- 기획서 만드는데 2-3일 걸려요

원하는 결과:
- 프로젝트 정보 (예산, 기간, 목표) 주면 자동으로 구조 잡아줬으면 좋겠어요
- 8개월 일정을 단계별로 나눠줬으면 좋겠고
- 각 단계마다 체크리스트가 있었으면 좋겠어요
- 예상되는 위험 요소도 미리 알려줬으면 좋겠어요

언제 사용:
- 새 프로젝트 계약서 받았을 때
- "카페 브랜딩" 같은 키워드 언급하면

핵심 정리

서브에이전트 만들기는

❌ 코드 작성이 아니라
✅ 내 워크플로우를 설명하는 것이다

4단계 프로세스

1. 내 워크플로우 정리
   → "내가 이 작업 할 때 어떻게 했지?"

2. Claude에게 설명
   → "이 순서대로 해"

3. Claude가 에이전트 생성
   → .claude/agents/name.md

4. 테스트 & 개선
   → "여기 수정해줘"

핵심 4원칙

1. 단일 책임 → 하나의 명확한 역할만
2. 상세한 프롬프트 → 예제와 에러 처리 포함
3. 최소 권한 → 필요한 도구만
4. Claude와 협업 → 초안 생성 후 반복 개선

다음 편 예고

여기까지 읽고 이런 생각이 들 것이다:

나: "에이전트 하나 만드는 건 알겠어..."
    "그런데 여러 개가 협업하면?"
    "내 OSMU 시스템처럼?"

다음 편에서 볼 것:

실제 OSMU 파이프라인 - YouTube 영상이 30분 만에 블로그 글이 되는 과정

[YouTube URL]
  ↓ 4분
[youtube-content-analyzer]
  ↓ 5분
[experience-bridge]
  ↓ 7분
[imi-work-persona-writer]
  ↓ 2분
[seo-optimizer]
  ↓ 3분
[osmu-image-generator]
  ↓ 1분
[ghost-validator]
  ↓ 2분
[ghost-publisher]
  ↓
[✅ 완성] 30분 총 소요

6-7개 에이전트가 릴레이로 협업하는 실제 작업 흐름을 보여준다.