Claude Code 서브에이전트 만들어서 문서 분석 자동화하기

📝 한줄 요약

프리랜서 스터디 과제로 Claude Code 서브에이전트 2개를 만들어 7개 AX 사례 문서를 병렬 분석하고, 15가지 프롬프트 패턴과 7가지 공통 패턴을 자동 추출했습니다.

🎯 이런 분들께 도움돼요

여러 문서를 일일이 읽고 분석하는 게 번거로운 분
서로 다른 관점에서 동시에 분석하고 싶은 분
Claude Code 서브에이전트 개념을 실습해보고 싶은 분
프리랜서 클코 자동화 스터디 참여자

소개: 시도하고자 했던 것과 그 이유

시작 계기

프리랜서 클코 자동화 스터디 1주차 과제였습니다. 주어진 미션은:

gpters-w1-practice/gpters_aicase_ax 경로의 7개 문서 분석
두 가지 관점에서 인사이트 추출:
- ax-case-finder: 사례별 핵심 요약 (문제→해결→도구→인사이트)
- ax-prompt-finder: 효과적인 프롬프트 패턴 추출

해결하고자 한 문제

단순히 문서를 읽고 분석하는 것이 아니라, 서브에이전트 개념을 실습하고 싶었습니다.

메인 에이전트가 전체 맥락을 이해하고
두 서브에이전트가 각자의 역할에 집중하여
병렬로 실행되어 독립적으로 분석하는 구조

이 과정을 통해 실전에서 재사용 가능한 자동화 패턴을 배우고 싶었습니다.

진행 방법: 어떤 도구를 사용했고, 어떻게 활용했나요?

사용한 도구

Claude Code (VSCode Extension)
서브에이전트 시스템 (.claude/agents/)
Task tool (병렬 실행)
모델: Haiku (서브에이전트용, 비용 효율적)

작업 과정

1단계: 서브에이전트 설계 및 생성

먼저 두 개의 서브에이전트를 .claude/agents/ 폴더에 정의했습니다:

ax-case-finder.md

---
name: ax-case-finder
description: 현재 상황과 비슷한 AX 사례 병렬 검색
tools: Read, Grep, Glob
model: haiku
---

ax-prompt-finder.md

---
name: ax-prompt-finder
description: 프롬프트 개선 패턴을 AX 사례에서 병렬 검색
tools: Read, Grep, Glob
model: haiku
---

각 에이전트에 명확한 역할을 부여했습니다:

ax-case-finder: "문제 → 해결 → 도구 → 인사이트" 200자 요약
ax-prompt-finder: 실제 프롬프트 인용, 효과 분석, 재사용 방법 제시

2단계: 막혔던 순간 - 에이전트 인식 실패

처음에는 서브에이전트를 만들고 바로 호출했습니다:

Task(subagent_type="ax-case-finder", ...)
Task(subagent_type="ax-prompt-finder", ...)

문제: Agent type 'ax-case-finder' not found 에러 발생

원인 파악: Claude Code가 새로 생성된 에이전트를 즉시 인식하지 못했습니다.

해결: general-purpose 에이전트에 각 서브에이전트의 역할을 프롬프트로 전달하는 방식으로 우회했습니다.

Task(
    subagent_type="general-purpose",
    model="haiku",
    prompt="""
    # 역할: ax-case-finder
    당신은 AX Case Finder입니다...
    """
)

3단계: 메인 에이전트의 맥락 파악

메인 에이전트로서 먼저 7개 문서를 모두 읽고 전체 맥락을 이해했습니다:

Glob(pattern="gpters-w1-practice/gpters_aicase_ax/**/*.md")
Read(file_path=각 문서 경로)

이 단계가 중요한 이유:

서브에이전트에게 정확한 작업 지시 가능
전체 구조를 파악하고 분석 방향 설정

4단계: 서브에이전트 병렬 실행

두 에이전트를 동시에 실행했습니다:

# 단일 메시지에 두 개의 Task 호출
Task(subagent_type="general-purpose", description="ax-case-finder analysis", ...)
Task(subagent_type="general-purpose", description="ax-prompt-finder analysis", ...)

병렬 실행의 효과:

두 에이전트가 독립적으로 분석 수행
각자의 관점에서 인사이트 추출
시간 절약 (순차 실행 대비)

5단계: 결과 문서화

각 에이전트의 분석 결과를 별도 문서로 저장:

ax-case-AI활용사례핵심요약.md (7개 사례 200자 요약)
ax-prompt-실전프롬프트패턴.md (15가지 프롬프트 패턴)

결과와 배운 점

결과물

1. ax-case-finder 결과

7개 사례를 각각 200자 이내로 압축:

사례글 자동화: 수동 작성 번거로움 → /devlog, /ai-case 커맨드 →
Claude Code 세션 파싱 → 대화 내역 찾기 시간 0초

매출 대시보드: 수동 필터링 → Airtable API 연동 →
Claude Code + Recharts → 3,590개 레코드 일괄 재계산

공통 패턴 7가지 도출:

명세 먼저, 구현 나중
역할 맡기기
코드 vs AI 판단 구분
도메인 로직은 구체적 예시로
1회성이 아닌 반복 가능
솔직한 피드백
대화 맥락 활용

2. ax-prompt-finder 결과

15가지 실전 프롬프트 패턴 추출:

예시 - 패턴 3: 역할 기반 관점 차용

원본: "ultrathink 너가 마케터라고 생각하고
      어떤 지표를 봐야하는지 보고 대시보드 기획을 해줘"

효과적인 이유:
- "ultrathink"로 깊은 사고 유발
- 특정 역할 명시로 전문적 관점 적용
- 내가 모르는 관점을 "빌려올 수" 있음

배운 점

1. 서브에이전트 설계의 핵심

명확한 역할 분담이 가장 중요했습니다:

각 에이전트의 목표를 200자 description에 명확히
필요한 도구만 제한 (Read, Grep, Glob)
출력 형식을 구체적으로 지정

2. 메인-서브 에이전트 패턴

메인 에이전트: 전체 맥락 이해 → 작업 지시
    ↓
서브 에이전트 A: 사례 요약 분석 (병렬)
서브 에이전트 B: 프롬프트 패턴 분석 (병렬)
    ↓
메인 에이전트: 결과 통합 및 문서화

이 패턴은 대규모 문서 분석, 다관점 리서치, 병렬 처리가 필요한 모든 작업에 재사용 가능합니다.

3. 실패에서 배운 것

"에이전트 인식 안 됨" 문제:

처음 만든 에이전트는 즉시 사용 불가
하지만 general-purpose + 역할 프롬프트로 우회 가능
실제로는 에이전트 구조 자체가 중요, 이름은 부차적

4. 병렬 실행의 위력

순차 실행 대비:

시간 절약 (거의 절반)
각 에이전트의 독립성 보장
서로 다른 관점의 결과물 동시 획득

재사용 가능한 프롬프트

1. 서브에이전트 생성 프롬프트

/subagent-creator [에이전트명]

---
name: [에이전트명]
description: [언제 사용할지 명확히]
tools: Read, Grep, Glob
model: haiku
---

# 역할 정의

당신은 [구체적 역할]입니다.

## 수행 단계
1. [작업 1]
2. [작업 2]
3. [작업 3]

## 출력 형식
[구체적인 형식 예시]

2. 병렬 에이전트 실행 프롬프트

# 단일 메시지에 여러 Task 호출
Task(subagent_type="general-purpose",
     description="에이전트A 역할",
     model="haiku",
     prompt="# 역할: A\n당신은..."),
Task(subagent_type="general-purpose",
     description="에이전트B 역할",
     model="haiku",
     prompt="# 역할: B\n당신은...")

3. 메인 에이전트 맥락 파악 프롬프트

# 1. 전체 파일 목록 확인
Glob(pattern="경로/**/*.md")

# 2. 대표 파일 읽어서 구조 파악
Read(file_path="대표파일경로", limit=100)

# 3. 서브에이전트에 명확한 지시
"다음 경로의 모든 문서를 읽고 [목표]를 수행하세요"

도움 받은 글 (참고 자료)

이 작업은 다음 프롬프트 문서를 기반으로 진행되었습니다:

gpters-w1-practice/prompt/w1-step-1vibe-coding.md
- 초기 바이브코딩 접근법
gpters-w1-practice/prompt/w1-step-2-gen-sub-agent.md
- 서브에이전트 생성 가이드
- 역할 정의 및 출력 형식 설계
gpters-w1-practice/prompt/w1-step3-use-subagent.md
- 서브에이전트 활용 및 병렬 실행 방법

다음 단계

즉시 적용 가능한 활용 사례

이 패턴을 다른 작업에도 적용할 수 있습니다:

경쟁사 분석
- 에이전트A: 기능 비교
- 에이전트B: 가격 전략 분석
- 에이전트C: UX 평가
학습 자료 정리
- 에이전트A: 핵심 개념 추출
- 에이전트B: 예시 코드 수집
- 에이전트C: 연습 문제 생성
문서 감사
- 에이전트A: 기술적 정확성 검토
- 에이전트B: 가독성 개선 제안
- 에이전트C: 누락된 섹션 확인

개선 계획

[ ] 서브에이전트 재시작 없이 즉시 인식되게 하기
[ ] 3개 이상 에이전트 동시 실행 실험
[ ] 에이전트 간 협업 패턴 연구

프리랜서 클코 자동화 스터디 1주차 과제 완료 🎉

20개의 주제를 확인해보세요! AI 스터디 슈퍼 얼리버드 시작🕊️