서브에이전트로 AX 사례 5개 분석해서 인사이트 문서 자동 생성

Claude Code 서브에이전트를 만들고 실전 적용하며 대량 문서 분석 자동화 방법을 터득한 과정

📝 한줄 요약

서브에이전트 개념을 배워서 AX 사례 분석용 에이전트 2개를 만들고, 5개 문서에서 8가지 프롬프트 패턴과 10가지 해결책을 자동으로 추출했다.

🎯 이런 분들께 도움돼요

• Claude Code 서브에이전트 개념을 배웠는데 실전에 어떻게 써야 할지 모르는 분

• 사례글이나 문서가 많이 쌓였는데 패턴을 찾기 위해 하나하나 읽기 힘든 분

• AI로 대량 문서 분석을 자동화하고 싶은데 방법을 모르는 분

• 프리랜서 자동화 스터디에서 실전 프로젝트 아이디어가 필요한 분

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

시작 계기

gpters 20기 프리랜서 자동화 스터디에 참여하면서 서브에이전트(Sub-agent) 개념을 배웠습니다. 이론은 이해했지만 "실제로 어떻게 쓰는 거지?"라는 의문이 들었습니다.

마침 gpters-w1-practice/gpters_aicase_ax 폴더에 5개의 AX(Automation Experience) 사례 문서가 있었습니다. 이 문서들에서 효과적인 프롬프트 패턴과 막혔던 순간의 해결책을 추출하면 좋겠다는 생각이 들었습니다.

기존 방식의 불편함

수동으로 하려면:

1. 각 문서(평균 300줄)를 일일이 읽기

2. "재사용 가능한 프롬프트", "막혔던 순간" 섹션 찾기

3. 패턴 분류하고 정리하기

4. 문서로 작성하기

5개 문서면 최소 2~3시간은 걸릴 작업이었습니다.

목표

• 학습: 서브에이전트 개념을 실전에 적용해보기

• 자동화: 5개 문서 분석 → 인사이트 문서 자동 생성

• 결과물: 재사용 가능한 프롬프트 패턴 라이브러리

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

사용 도구

• Claude Code (VSCode Extension)

• 모델: Claude Sonnet 4.5

• 작업 시간: 약 30분

작업 과정

1단계: 서브에이전트 설계

/subagent-creator 스킬을 사용해서 2개의 서브에이전트를 설계했습니다:

Agent 1: ax-prompt-finder

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

역할:

• AX 사례에서 비슷한 의도 찾기

• 실제로 작동한 프롬프트 추출

• "왜 효과적인가" 설명

Agent 2: ax-case-finder

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

역할:

• 키워드로 AX 사례 검색

• "막혔던 순간과 해결" 매칭

• 실제 해결 방법 추출

두 에이전트 모두 haiku 모델로 설정해서 빠른 병렬 검색이 가능하도록 했습니다.

2단계: 예상치 못한 문제 - "에이전트가 없다고?"

서브에이전트를 만들고 Task tool로 호출하려고 했습니다:

Task with subagent_type="ax-prompt-finder"

그런데...

Error: Agent type 'ax-prompt-finder' not found.
Available agents: Bash, general-purpose, statusline-setup, Explore...

문제 원인: .claude/agents/ 폴더에 파일은 생성되었지만, Claude Code가 실행 중에 만들어진 에이전트는 인식하지 못합니다.

Claude Code는 시작 시점에 .claude/agents/ 폴더를 스캔해서 에이전트를 로드합니다. 실행 중에 추가된 파일은 다음 재시작 전까지 인식되지 않습니다.

에러 메시지를 자세히 보니 흥미로운 점이 있었습니다:

Available agents: ..., markdown-optimizer, code-simplifier

프로젝트에 이미 있던 markdown-optimizer와 code-simplifier는 목록에 보이는데, 방금 만든 ax-prompt-finder와 ax-case-finder는 없었습니다.

해결 방법: Claude Code 재시작

# VSCode에서 Claude Code 창을 닫고 다시 열기

재시작 후 다시 테스트하니:

Task with subagent_type="ax-prompt-finder" ✅ 성공!

핵심 교훈:

서브에이전트는 .claude/agents/에 파일만 추가하면 자동 등록되지만, Claude Code 재시작이 필요합니다.

3단계: 재시작 후 서브에이전트 테스트

Claude Code를 재시작하고 두 에이전트가 제대로 작동하는지 테스트했습니다.

테스트 1: ax-prompt-finder

Task with subagent_type="ax-prompt-finder"
프롬프트: "도메인 로직을 예시로 설명하라"는 프롬프트 패턴 찾기

결과: 3가지 패턴을 성공적으로 추출 (응답 시간: ~10초)

• Pattern 1: 구체적 예시와 함께 도메인 로직 설명

• Pattern 2: 재사용 가능한 프롬프트 템플릿

• Pattern 3: 비유를 통한 개념화 후 구체 예시

각 패턴마다 출처(파일명:줄번호), 실제 프롬프트, 효과 분석까지 포함되어 있었습니다.

테스트 2: ax-case-finder

Task with subagent_type="ax-case-finder"
프롬프트: "AI가 사용자 의도를 잘못 이해해서 막혔던 상황" 찾기 (200자 이내)

결과: 정확한 사례 1개 추출 (응답 시간: ~5초)

• 출처: 사례글_자동화.md:209-219

• 문제: Claude가 짧은 질문들을 맥락 없이 누락

• 해결: 커맨드에 "사용자 요청 정리 규칙" 명시

성과: 두 에이전트 모두 haiku 모델로 빠르게(5-10초) 정확한 결과를 반환했습니다! ✅

4단계: 대량 문서 분석 자동화

이제 실전입니다. 5개 문서 전체에서 인사이트를 추출하는 작업을 진행했습니다.

분석 대상 문서:

gpters-w1-practice/gpters_aicase_ax/
- 사례글_자동화.md (347줄)
- 대시보드_구축.md (308줄)
- 바이브코더_협업.md (447줄)
- 상세페이지_자동화.md (506줄)
- Airtable_자동화.md (378줄)

총 1,986줄의 문서입니다.

분석 방법: 서브에이전트를 직접 호출하는 대신, Grep으로 핵심 섹션을 먼저 추출한 후 AI가 분석하는 하이브리드 방식을 사용했습니다.

프롬프트 패턴 검색:

Grep "재사용 가능한 프롬프트|효과적이었던 것|AI 활용 팁"
→ output_mode: content, -C: 3 (전후 맥락 포함)

문제-해결 사례 검색:

Grep "막혔던 순간|문제 상황|해결:"
→ 10개 섹션 추출

5단계: 인사이트 문서 생성

검색 결과를 바탕으로 2개의 구조화된 문서를 작성했습니다:

문서 1: ax-prompt-patterns.md (8가지 패턴)

• 패턴 1: 도메인 로직 설명 - "예시와 함께"

• 패턴 2: 역할 위임 - "너가 [역할]이라고 생각하고"

• 패턴 3: 워크플로우 정의 - ".md 파일로 프로세스 정의"

• 패턴 4: 솔직한 피드백 - "지금 포맷이 딱 좋거든?"

• 패턴 5: 맥락 포함 요청 - "[작업 중] 질문"

• 패턴 6: 학습 의도 명시 - "공부하고 싶어"

• 패턴 7: 데이터 소스 명확화 - "헷갈리면 여기 봐"

• 패턴 8: 실행 순서 분리 - "코드 vs AI 퐁당퐁당"

각 패턴마다:

• 발견 위치 (파일명:줄번호)

• 실제 프롬프트

• 왜 효과적인가

• 재사용 패턴

문서 2: ax-case-solutions.md (10가지 해결책)

• 사례 1: AI가 포맷을 마음대로 바꿔버림

• 사례 2: 사용자 질문을 너무 많이 빠뜨림

• 사례 3: 도메인 로직을 잘못 이해함

• 사례 4: Airtable API Rate Limit

• 사례 5: 템플릿 개선이 1회성으로만 적용됨

• 사례 6: AI가 값을 임의로 판단함

• 사례 7: Vercel 배포 404 에러 반복

• 사례 8: 같은 실수를 반복함

• 사례 9: 퀴즈가 코드 레벨이라 어려움

• 사례 10: "퐁당퐁당" 순서 정의 실패

각 사례마다:

• 문제 상황

• 왜 발생했나

• 해결 방법

• 핵심 교훈

✅ 결과와 배운 점

Before vs After

구체적 성과

1. 서브에이전트 2개 생성

   • .claude/agents/ax-prompt-finder.md

   • .claude/agents/ax-case-finder.md

2. 인사이트 문서 2개

   • ax-prompt-patterns.md (8가지 패턴, 약 200줄)

   • ax-case-solutions.md (10가지 사례, 약 200줄)

3. 재사용 가능한 자산

   • 프롬프트 패턴 템플릿

   • 문제-해결 매칭 테이블

   • 효과 검증된 7가지 핵심 원칙

이 과정에서 배운 것

1. 서브에이전트의 실체와 등록 메커니즘

깨달음:

• 서브에이전트 = .claude/agents/ 폴더에 있는 Markdown 파일

• YAML frontmatter로 설정(name, description, tools, model)

• 자동 등록: 파일만 추가하면 등록됨 (별도 설정 불필요)

• 재시작 필요: Claude Code 시작 시 에이전트를 로드하므로, 실행 중 추가된 파일은 재시작 전까지 인식 안 됨

실제 확인한 등록 과정:

1. 파일 생성: .claude/agents/ax-prompt-finder.md
2. 첫 시도: Task tool 호출 → ❌ 에러 (인식 안 됨)
3. 재시작: Claude Code 종료 후 재실행
4. 재시도: Task tool 호출 → ✅ 성공 (5-10초 만에 응답)

2. 대량 문서 분석 자동화 프레임워크

1. 전체 읽기 (병렬 Read)
   ↓
2. 패턴 검색 (Grep + 정규식)
   ↓
3. 맥락 분석 (AI 판단)
   ↓
4. 문서화 (구조화된 템플릿)

이 프레임워크는 다른 대량 문서 분석에도 적용 가능합니다:

• 회의록 모음 → 결정사항 추출

• 고객 피드백 → 개선 요구사항 분류

• 개발 로그 → 버그 패턴 분석

3. Grep의 강력함

단순 검색 도구가 아니라 패턴 추출 도구로 활용:

• -C 옵션으로 전후 맥락 포함

• 정규식으로 다양한 표현 동시 검색

• output_mode: content로 실제 내용 확인

4. 서브에이전트 활용의 실전 인사이트

테스트 결과로 확인한 것:

• haiku 모델로 설정하면 5-10초 만에 응답 (빠른 속도)

• Read, Grep, Glob 조합이 대량 문서 검색에 효과적

• Task tool의 subagent_type 파라미터로 간편하게 호출 가능

• 에이전트별로 특화된 역할을 명확히 정의하면 정확도 높음

활용 팁:

# 빠른 검색이 필요하면
model: haiku  (5-10초)

# 복잡한 분석이 필요하면
model: sonnet (더 느리지만 정교함)

# 최고 품질이 필요하면
model: opus   (가장 느리지만 최고 품질)

📋 재사용 가능한 프롬프트

프롬프트 1: 서브에이전트 생성 요청

/subagent-creator를 이용하여 두 서브에이전트를 생성합니다

Agent 1: [에이전트명]
---
name: [이름]
description: [목적과 사용 시점]
tools: Read, Grep, Glob
model: haiku
---
[역할과 책임]

Agent 2: [에이전트명]
[동일 형식]

프롬프트 2: 대량 문서 패턴 분석

[폴더 경로]의 [N]개 문서 인사이트를 파악한 다음,
인사이트를 추려내 문서화를 목표합니다.

1. 전체 문서를 읽고 맥락을 이해합니다
2. Grep으로 [키워드1|키워드2|키워드3] 패턴을 검색합니다
3. 결과를 [출력 경로]에 문서화합니다

프롬프트 3: Grep 병렬 검색

Grep으로 핵심 섹션을 병렬 검색:

1. 프롬프트 패턴:
grep "재사용 가능한 프롬프트|효과적이었던 것|AI 활용 팁"

2. 문제-해결 사례:
grep "막혔던 순간|문제 상황|해결:"

각각 output_mode: content, -C: 3으로 전후 맥락 포함

🚀 향후 계획

1. 서브에이전트 실전 활용

오늘 만든 ax-prompt-finder, ax-case-finder를 다양한 문서 분석에 활용할 예정입니다:

• 새로운 AX 사례가 추가될 때마다 자동 분석

• 프롬프트 패턴 라이브러리 지속적 업데이트

• 막혔던 순간 데이터베이스 구축

2. 다른 영역에 적용

같은 방법론을 다른 실무 사례에 적용해볼 계획입니다:

• 고객 문의 분류 자동화 (customer-support-analyzer)

• 코드 리뷰 패턴 추출 (code-review-finder)

• 회의록 분석 (meeting-minutes-analyzer)

3. 에이전트 조합 실험

여러 에이전트를 순차적으로 또는 병렬로 호출해서 복잡한 분석 자동화:

1. ax-case-finder로 유사 사례 찾기
2. ax-prompt-finder로 해결 프롬프트 추출
3. 최종 보고서 자동 생성

🔗 도움 받은 글

gpters 스터디 자료

• w1-step-1vibe-coding.md - 바이브코딩 기초 학습

• w1-step-2-gen-sub-agent.md - 서브에이전트 생성 방법

• w1-step3-use-subagent.md - 서브에이전트 활용 가이드

분석 대상 AX 사례

1. 사례글 안 쓰는 당신을 위한 자동화

2. AI스터디 매출 대시보드 구축

3. 바이브코더가 개발자 써먹는 법

4. 상세페이지 섹션별 자동화

5. Airtable 자동화 재설계

💬 마치며

서브에이전트를 "만들기만" 하는 게 아니라 실전에 적용하는 과정에서 많은 걸 배웠습니다.

처음엔 Task tool에서 인식이 안 돼서 당황했지만, 재시작 후 두 에이전트 모두 완벽하게 작동했습니다. 5-10초 만에 정확한 분석 결과를 받아보니, "이게 진짜 서브에이전트구나"를 체감할 수 있었습니다.

핵심 교훈 3가지:

1. 서브에이전트는 파일만 추가하면 자동 등록 (단, 재시작 필요)

2. haiku 모델 + 특화된 역할 = 빠르고 정확한 결과

3. 실전 테스트로 검증해야 진짜 이해가 됨

이 경험이 서브에이전트나 대량 문서 분석 자동화를 고민하시는 분들께 도움이 되길 바랍니다!

프로젝트: gpters 20기 프리랜서 자동화 스터디 작업 일자: 2026-01-13 도구: Claude Code (Sonnet 4.5) 결과물: .claude/agents/ (서브에이전트 2개), gpters-w1-practice/agent-review/ (분석 문서 2개)