서브 에이전트 처음 만들어본 비개발자가 문서 분석 자동화한 썰 - 에이전트가 나보다 글 잘 쓰네?
2026.01.13
📝 한줄 요약
Claude Code 서브 에이전트 2개를 만들어서 5개 AX 사례를 병렬로 분석하고, 프롬프트 패턴과 문제 해결 인사이트를 자동으로 문서화했습니다.
🎯 이런 분들께 도움돼요
여러 문서를 반복적으로 분석해야 하는 분
Claude Code 서브 에이전트 개념을 실습하고 싶은 분
병렬 처리로 작업 속도를 높이고 싶은 분
AX 사례에서 재사용 가능한 패턴을 추출하고 싶은 분
😫 문제 상황 (Before)
gpters 20기 과제: AX 사례 분석
gpters 20기 실습 과제로 AX(AI Automation Excellence) 사례 분석을 진행하게 됐습니다.
주어진 상황:
5개의 AX 사례 문서 (총 7개 파일, markdown 형식)
각 문서당 200~400줄 분량
프롬프트 패턴과 문제 해결 방법을 추출해야 함
문제점:
수동 분석의 한계
5개 문서를 일일이 읽고 분석하면 시간 소요가 큼
패턴을 찾기 위해 문서를 여러 번 읽어야 함
일관성 있는 분석이 어려움
에이전트 설계 방법을 몰랐음
서브 에이전트를 어떻게 만드는지 감이 안 옴
어떤 도구를 주고 어떤 프롬프트를 써야 할지 불명확
병렬 처리 방법을 몰랐음
반복 작업 예상
앞으로도 비슷한 분석 작업이 반복될 것 같음
매번 수동으로 하기엔 비효율적
🛠️ 사용한 도구
도구명: 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 에이전트 문서
상황: 제가 먼저 직접 분석한 문서와 에이전트가 만든 문서를 비교해봤습니다.
비교 결과:
항목 | 직접 작성 | 에이전트 작성 |
|---|---|---|
파일 크기 | 7KB, 9KB | 22KB, 10KB |
프롬프트 인용 | 요약 위주 | 원문 그대로 인용 |
템플릿 개수 | 7개 | 12개 |
실전 예시 | 보통 | 매우 풍부 |
구조화 | 좋음 | 매우 체계적 |
느낀 점: 에이전트가 작성한 문서가 더 상세하고 실전 예시가 풍부했습니다. 특히 원본 프롬프트를 정확히 인용한 점이 좋았어요.
✅ 결과 (After)
Before vs After
항목 | Before | After |
|---|---|---|
분석 시간 | 수동 분석 (예상 2시간) | 병렬 자동화 (10분) |
일관성 | 사람마다 다름 | 에이전트가 일관되게 분석 |
재사용성 | 일회성 분석 | 에이전트 재사용 가능 |
문서 품질 | 요약 위주 | 원문 인용 + 체계적 구조 |
확장성 | 사례 추가 시 수동 작업 | 에이전트 재실행으로 자동 |
구체적 성과
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% 단축
문서 품질 향상 (원문 인용, 체계적 구조)
재사용 가능한 에이전트 확보
즉시 적용 가능한 인사이트 체계화
배운 것: 서브 에이전트는 반복 작업의 게임 체인저입니다. 한 번 만들면 계속 재사용 가능하고, 병렬 실행으로 속도를 배가할 수 있습니다.
🤖 이제 여러분도 서브 에이전트를 만들어보세요!

![[미니] 클로드 코웍 사용해서 가계부까지 도전해보기 썸네일](/_next/image?url=https%3A%2F%2Fcdn-beta.gpters.org%2Fexternal%2Fc6465620fff4957e3817a6b4.jpg&w=3840&q=75)