서브 에이전트 처음 만들어본 비개발자가 문서 분석 자동화한 썰 - 에이전트가 나보다 글 잘 쓰네?

📝 한줄 요약

Claude Code 서브 에이전트 2개를 만들어서 5개 AX 사례를 병렬로 분석하고, 프롬프트 패턴과 문제 해결 인사이트를 자동으로 문서화했습니다.

🎯 이런 분들께 도움돼요

• 여러 문서를 반복적으로 분석해야 하는 분

• Claude Code 서브 에이전트 개념을 실습하고 싶은 분

• 병렬 처리로 작업 속도를 높이고 싶은 분

• AX 사례에서 재사용 가능한 패턴을 추출하고 싶은 분

😫 문제 상황 (Before)

gpters 20기 과제: AX 사례 분석

gpters 20기 실습 과제로 AX(AI Automation Excellence) 사례 분석을 진행하게 됐습니다.

주어진 상황:

• 5개의 AX 사례 문서 (총 7개 파일, markdown 형식)

• 각 문서당 200~400줄 분량

• 프롬프트 패턴과 문제 해결 방법을 추출해야 함

문제점:

1. 수동 분석의 한계

   • 5개 문서를 일일이 읽고 분석하면 시간 소요가 큼

   • 패턴을 찾기 위해 문서를 여러 번 읽어야 함

   • 일관성 있는 분석이 어려움

2. 에이전트 설계 방법을 몰랐음

   • 서브 에이전트를 어떻게 만드는지 감이 안 옴

   • 어떤 도구를 주고 어떤 프롬프트를 써야 할지 불명확

   • 병렬 처리 방법을 몰랐음

3. 반복 작업 예상

   • 앞으로도 비슷한 분석 작업이 반복될 것 같음

   • 매번 수동으로 하기엔 비효율적

🛠️ 사용한 도구

• 도구명: Claude Code (CLI)

• 모델: Claude Sonnet 4.5

• 특이사항:

  • Subagent Creator 스킬 활용

  • 서브 에이전트 2개 생성 및 병렬 실행

  • general-purpose 에이전트로 대체 실행

🤝 AI와 협업한 과정

1. 서브 에이전트 설계 - "어떻게 만드는지 감이 안 와"

상황: 서브 에이전트를 만들어야 하는데 방법을 몰랐습니다.

이렇게 요청했어요:

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

Agent 1: Prompt Pattern Finder
---
name: ax-prompt-finder
description: 프롬프트 개선 패턴을 AX 사례에서 병렬 검색
tools: Read, Grep
model: haiku
---
현재 프롬프트를 분석해야 합니다.
1. AX 사례에서 비슷한 의도 찾기
2. 실제로 작동한 프롬프트 추출
3. "왜 효과적인가" 설명

결과:

• .claude/agents/ax-prompt-finder.md 파일 자동 생성

• .claude/agents/ax-case-finder.md 파일 자동 생성

• 각 에이전트의 역할, 실행 순서, 출력 형식이 상세히 정의됨

느낀 점: 서브 에이전트는 markdown 파일로 정의한다는 걸 처음 알았습니다. YAML frontmatter에 설정하고, 본문에 시스템 프롬프트를 작성하는 구조가 명확했어요.

2. 에이전트 명세 작성 - "도구와 역할을 명확히"

상황: 각 에이전트가 어떤 도구를 사용하고 어떤 출력을 내야 하는지 정의해야 했습니다.

ax-prompt-finder 명세:

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

당신은 프롬프트 개선 전문가입니다.

## 호출 시 수행할 작업
1. 현재 프롬프트 분석
2. AX 사례에서 비슷한 의도 찾기
3. 실제로 작동한 프롬프트 추출
4. 효과적인 이유 설명

## 출력 형식
- 패턴별 실제 프롬프트 예시
- 효과적인 이유
- 재사용 템플릿

ax-case-finder 명세:

• 200자 이내 간결한 출력 강제

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

• 실행 가능한 구체적 방법만 추출

배운 점:

• 도구 선택이 중요: Read, Grep, Glob만 주면 검색에 집중

• model: haiku: 빠른 검색용으로 경량 모델 선택

• 출력 형식 명시: AI가 헷갈리지 않도록 구조 제시

3. 병렬 호출 시도 - "에이전트가 인식이 안 돼!"

상황: 에이전트를 생성했는데 Task tool로 호출하니 'not found' 오류가 발생했습니다.

이렇게 요청했어요:

@agent-ax-case-finder
@agent-ax-prompt-finder
결과값을 다음 경로에 문서화를 해주세요

결과:

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

문제 원인:

• Claude Code를 재시작하지 않아서 새 에이전트가 등록 안 됨

• 커스텀 에이전트는 세션 시작 시 로드됨

해결:

general-purpose 에이전트를 사용하되,
에이전트 역할을 프롬프트에 명시하는 방식으로 대체

배운 점: 커스텀 에이전트 생성 후에는 Claude Code 재시작 필요. 하지만 general-purpose 에이전트에 역할을 부여하는 방식도 잘 작동함.

4. 병렬 실행 - "동시에 두 개 돌리기"

상황: 프롬프트 패턴 분석과 문제 해결 패턴 분석을 따로따로 하면 시간이 2배 걸립니다.

이렇게 요청했어요:

두 에이전트를 병렬로 호출하여 내용을 파악합니다.

실제 구현:

# 단일 메시지에 두 개의 Task tool call
Task(subagent_type="general-purpose",
     description="AX case pattern analysis",
     prompt="당신은 AX Case Finder 에이전트입니다...")

Task(subagent_type="general-purpose",
     description="AX prompt pattern analysis",
     prompt="당신은 AX Prompt Finder 에이전트입니다...")

결과:

• 두 에이전트가 동시에 실행됨

• 각각 별도의 문서 생성

• 작업 시간이 절반으로 단축

느낀 점: 병렬 실행은 단일 메시지에 여러 Tool Call을 보내면 됩니다. 각 에이전트가 독립적으로 작업하므로 효율적이었어요.

5. 결과 문서 생성 - "에이전트가 알아서 쓰네?"

상황: 에이전트들이 분석을 마치고 자동으로 문서를 생성했습니다.

생성된 문서:

ax-case-problem-solving.md (10KB):

• 가장 많이 막힌 순간 4가지

• 가장 효과적인 해결책

• 공통 패턴 분석

• 즉시 적용 가능한 체크리스트

ax-prompt-patterns.md (22KB):

• 7가지 효과적 프롬프트 패턴

• 실제 사용된 프롬프트 인용

• 12개 재사용 템플릿

• 패턴별 효과 분석

놀라운 점:

• 원본 문서에서 실제 프롬프트를 정확히 인용

• 패턴을 분류하고 체계화

• 재사용 가능한 형태로 정리

• 즉시 적용 가능한 실전 팁 포함

6. [여기서 병목] 처음 만든 문서 vs 에이전트 문서

상황: 제가 먼저 직접 분석한 문서와 에이전트가 만든 문서를 비교해봤습니다.

비교 결과:

느낀 점: 에이전트가 작성한 문서가 더 상세하고 실전 예시가 풍부했습니다. 특히 원본 프롬프트를 정확히 인용한 점이 좋았어요.

✅ 결과 (After)

Before vs After

구체적 성과

1. 실전 적용 가능한 인사이트 확보

프롬프트 패턴 7가지 추출:

• 구체적 예시 제공 패턴 (5회 사용, 100% 성공)

• 역할 부여 + Ultrathink 패턴

• 데이터 소스 명확화 패턴

• 제약사항 명시 패턴

• 직접 확인 요청 패턴

• 섹션별 수정 패턴

• 1회성 수정 방지 패턴

문제 해결 패턴 4가지:

• AI 오해 → 구체적 예시로 해결

• 외부 도구 제약 → 사전 공유

• 에러 반복 → 직접 진단 요청

• 같은 실수 반복 → 문서화

2. 재사용 가능한 템플릿 12개

# 데이터 연동
[Airtable/노션/구글시트]를 연동해줘.

# 전문가 관점
ultrathink 너가 [마케터/PM]라고 생각하고 기획해줘.

# 도메인 로직
[분류 기준]을 보고 판단해야 해.
예를 들어 [구체적 상황]이면 [결과 A]야.

# 직접 진단
너가 [서비스]도 직접 봐주면 안 돼?

# 재발 방지
이거 왜 자꾸 반복해서 실수해?
CLAUDE.md에 추가해줘.

3. 즉시 적용 가능한 체크리스트

문제 발생 시:

• [ ] 구체적 예시를 제공했는가?

• [ ] 외부 도구의 제약사항을 전달했는가?

• [ ] AI에게 직접 진단 요청했는가?

구현 전:

• [ ] 명세 문서(md)를 먼저 작성했는가?

• [ ] 코드로 할 것 / AI가 할 것 구분했는가?

• [ ] 데이터 소스를 명확히 정의했는가?

결과물

생성된 파일:

.claude/agents/
├── ax-prompt-finder.md      # 프롬프트 패턴 분석 에이전트
└── ax-case-finder.md         # 문제 해결 패턴 분석 에이전트

gpters-w1-practice/agent-review/
├── ax-prompt-patterns.md     # 프롬프트 패턴 인사이트 (22KB)
└── ax-case-problem-solving.md # 문제 해결 패턴 인사이트 (10KB)

통계:

• 분석한 사례: 7개 문서

• 추출한 프롬프트 패턴: 7개

• 재사용 템플릿: 12개

• 문제 해결 패턴: 4개

• 작업 시간: 약 10분 (병렬 처리)

💬 이 과정에서 배운 AI 활용 팁

효과적이었던 것

1. 서브 에이전트는 markdown으로 정의

---
name: agent-name
description: 언제 사용할지 명확히
tools: Read, Grep, Glob
model: haiku
---

시스템 프롬프트 작성
역할, 실행 순서, 출력 형식 명시

2. 병렬 실행은 단일 메시지에 여러 Tool Call

단일 메시지에:
- Task(prompt="에이전트 1...")
- Task(prompt="에이전트 2...")

순차 실행보다 2배 빠름

3. 에이전트 역할을 프롬프트에 명시

"당신은 AX Case Finder 에이전트입니다."
general-purpose 에이전트도 역할 부여로 전문화 가능

4. 출력 형식을 구체적으로 지정

## 출력 형식
- 사례별 핵심 해결 패턴
- 공통 문제 해결 패턴
- 즉시 적용 가능한 체크리스트
- 200자 이내 핵심 요약

5. 도구 선택이 에이전트 성능 결정

Read, Grep, Glob만 주면 → 검색에 집중
model: haiku → 빠른 검색
Edit, Write 주면 → 문서 수정도 가능

이렇게 하면 안 돼요

1. 에이전트 역할을 모호하게 정의

• ❌ "문서 분석해줘"

• ✅ "당신은 프롬프트 패턴 분석 전문가입니다"

2. 출력 형식을 명시 안 함

• ❌ "분석 결과 알려줘"

• ✅ "## 출력 형식: 1. 패턴 2. 예시 3. 템플릿"

3. 에이전트 생성 후 재시작 안 함

• 커스텀 에이전트는 세션 시작 시 로드

• 생성 후 Claude Code 재시작 필요

4. 순차 실행으로 시간 낭비

• ❌ 에이전트 1 완료 → 에이전트 2 실행

• ✅ 단일 메시지에 두 개 동시 실행

🌍 다른 업무에 적용한다면?

1. 고객 피드백 분석

Agent 1: 긍정/부정 분류 에이전트
Agent 2: 개선 아이디어 추출 에이전트

병렬로 100개 피드백 분석 → 10분

2. 경쟁사 분석

Agent 1: 기능 비교 에이전트
Agent 2: 가격 전략 분석 에이전트

5개 경쟁사 동시 분석

3. 코드 리뷰

Agent 1: 보안 취약점 검사 에이전트
Agent 2: 성능 개선 제안 에이전트

여러 파일 동시 리뷰

핵심 원칙

반복되는 분석 작업이라면
→ 서브 에이전트로 자동화
→ 병렬 실행으로 속도 향상
→ 결과를 템플릿화

🚀 앞으로의 계획

1. 에이전트 개선

• 이미지 분석 기능 추가 (스크린샷에서 UI 패턴 추출)

• 더 많은 AX 사례 누적 시 재실행으로 패턴 업데이트

2. 에이전트 확장

• 회의록 분석 에이전트

• 버그 리포트 자동 분류 에이전트

• 주간 업무 요약 에이전트

3. 팀 공유

• 팀원들이 같은 에이전트 사용할 수 있도록 공유

• 사내 AX 사례 분석 표준화

📋 재사용 가능한 프롬프트

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

/subagent-creator

Agent 1: [에이전트 이름]
---
name: [kebab-case-name]
description: [언제 사용할지 명확히]
tools: [필요한 도구만]
model: [sonnet/haiku/opus]
---

당신은 [역할] 전문가입니다.

## 호출 시 수행할 작업
1. [단계 1]
2. [단계 2]

## 출력 형식
- [형식 1]
- [형식 2]

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

아래 에이전트를 병렬로 호출하여 내용을 파악합니다.
@agent-[name-1]
@agent-[name-2]

결과값을 [경로]에 문서화를 해주세요.

프롬프트 3: 에이전트 역할 명시 (general-purpose 사용 시)

당신은 [역할] 에이전트입니다.

**목표**: [구체적 목표]

**분석 초점**:
1. [초점 1]
2. [초점 2]

**출력 형식**:
- [형식 1]
- [형식 2]

**중요**: [도구명] 도구를 사용하여 실제로 [작업]하세요.

결과를 [파일 경로]로 작성해주세요.

프롬프트 4: 에이전트 개선 요청

[에이전트 파일]을 읽고,
[문제점]을 개선해줘.

특히:
- [개선 사항 1]
- [개선 사항 2]

🎓 핵심 교훈

1. 서브 에이전트는 "역할 특화"가 핵심

하나의 에이전트가 모든 걸 하려고 하지 마라
각자 역할을 명확히 → 품질 향상

2. 병렬 실행은 "독립적 작업"에만

두 작업이 서로 의존하지 않으면 → 병렬 실행
순차적으로 해야 하면 → 하나의 에이전트에서 처리

3. 에이전트 설계는 "명세부터"

바로 구현 ❌
역할 정의 → 도구 선택 → 출력 형식 → 구현 ✅

4. general-purpose도 강력하다

커스텀 에이전트 등록 안 되면
→ general-purpose + 역할 프롬프트로 대체 가능

📌 최종 요약

Before: 5개 AX 사례를 수동으로 분석 (예상 2시간)

After:

• 서브 에이전트 2개 생성 (10분)

• 병렬 자동 분석 (10분)

• 상세한 인사이트 문서 2개 자동 생성

• 재사용 가능한 템플릿 12개 확보

핵심 성과:

• 작업 시간 85% 단축

• 문서 품질 향상 (원문 인용, 체계적 구조)

• 재사용 가능한 에이전트 확보

• 즉시 적용 가능한 인사이트 체계화

배운 것: 서브 에이전트는 반복 작업의 게임 체인저입니다. 한 번 만들면 계속 재사용 가능하고, 병렬 실행으로 속도를 배가할 수 있습니다.

🤖 이제 여러분도 서브 에이전트를 만들어보세요!