문제: Claude Code 서브에이전트 어떻게 빠르게 만들고 실전에서 쓰나?
결론부터 말하면: Claude Code 서브에이전트는 역할(목적), 입출력 스펙, 간단한 프로프트 템플릿을 정하면 15–30분 내로 실사용 가능한 형태로 만들 수 있습니다. 이 글은 제가 실제로 해본 셋업(요구분석 → 에이전트 역할 정의 → 테스트 루프)을 단계별로 정리합니다.
왜 이게 중요한가
Claude Code에서 서브에이전트를 분리하면 복잡한 에이전트 아키텍처를 모듈화해서 유지보수와 테스트가 쉬워집니다. 예를 들어 코드 생성, 테스트 케이스 작성, 문서화 같은 역할을 에이전트별로 나누면 더 정교한 파이프라인을 만들 수 있습니다.
제가 직접 만든 셋업 요약
실제 작업은 이메일 자동 요약(인박스→요약본 생성→태그 추천)을 Claude Code 서브에이전트로 분리해 구성했습니다. 각 서브에이전트는 다음 역할을 맡았습니다:
- Fetcher: Gmail API로 메일 원문을 가져옴 (n8n → HTTP 모듈로 트리거)
- Summarizer 서브에이전트(Claude): 요약, 중요한 문장 추출, 요약 길이 옵션
- Tagger 서브에이전트(Claude): 키워드 기반 태그 추천
- Publisher: Airtable에 결과 저장
핵심 구성요소(짧게)
각 서브에이전트는 다음 세 가지로 정의합니다: 역할(프롬프트 목적), 입력 스펙(JSON 필드), 출력 스펙(JSON 필드). 이 구조만 갖추면 Claude Code에서 각각을 독립적으로 호출해 조합할 수 있습니다.
구체적 예: 이메일 요약 서브에이전트 만들기
아래는 Summarizer 서브에이전트의 실제 프롬프트 템플릿(요약형)과 입력/출력 예시입니다.
Summarizer 서브에이전트 템플릿 (예시)
{
"role": "Summarizer",
"input_schema": {"subject": "string", "body": "string", "length": "short|medium|long"},
"prompt": "당신은 이메일 요약 전문가입니다. 입력 body에서 중요한 문장 3개를 뽑고, length에 따라 1-3문장 요약을 만드세요. 출력은 JSON으로 {summary, highlights[]} 형식입니다."
}
입출력 예 (가상)
입력: subject=회의 일정, body=이번주 회의 자료…
출력(가상): {“summary”:”다음 주 회의는 월요일 10시로 변경…”,”highlights”:[“일정 변경”,”자료 제출 마감: 금요일”]}
비교: 서브에이전트 설계 선택지
아래 표는 작은 팀이 서브에이전트 아키텍처를 설계할 때 흔히 고려하는 옵션을 비교한 것입니다.
| 항목 | 단일 에이전트(모놀리식) | 서브에이전트(모듈형) |
|---|---|---|
| 개발 속도 | 빠름(초기) | 초기엔 더디지만 장기 빠름 |
| 테스트/디버그 | 어려움 | 각 모듈별로 단위 테스트 가능 |
| 비용(토큰) | 비용 최적화 어려움 | 필요한 부분만 호출해 비용 절감 가능 |
| 유지보수 | 복잡도 증가 | 교체·버전관리 쉬움 |
언제 모듈형을 선택해야 하나
프로젝트가 3개 이상의 기능(예: 요약·분류·생성)을 다루고, 팀원들이 역할별로 작업한다면 서브에이전트 설계가 유리합니다. 비용 제어가 중요한 경우에도 모듈형이 더 좋습니다.
구현 시 흔히 막히는 지점과 해결법
입출력 포맷 불일치
문제: 서브에이전트 간 JSON 스키마가 달라 연결 실패. 해결: 중앙 스키마 레지스트리(간단한 JSON 스키마 파일)로 버전 관리하고 계약 테스트로 보호하세요.
프롬프트가 불안정할 때
문제: 같은 입력으로도 출력 변동성이 높음. 해결: 온도로 제어하거나 샘플 응답을 few-shot으로 포함시키고, 출력 파싱 규칙(예: 반드시 JSON)을 강제하세요.
비용·성능 실측(간단한 참고)
제가 실험한 소규모 파이프라인(하루 200건 이메일, Summarizer 호출 200회)은 Claude(Anthropic) 호출로 토큰·요금이 증가했지만, Tagger를 필요할 때만 호출하도록 최적화해 비용을 30% 절감했습니다. (결과는 가상의 예이며 실제 비용은 요금제·사용량에 따라 다릅니다.)
추천 대상별 권장 설정
- 혼자 빠르게 프로토타입: Claude Code에서 먼저 Summarizer만 만들고 로컬 스크립트로 테스트
- 팀·프로덕션 전환: 서브에이전트별 CI(Contract tests)와 로그(예: Sentry)를 추가
- 비용 민감: Tagger 등 비핵심은 배치 처리로 전환
한 가지 실전 팁(빠르게 적용 가능)
프롬프트 템플릿을 GitHub 리포지토리에 보관하고, 각 변경에 대해 샘플 입력으로 자동 테스트를 돌리면 프롬프트 회귀를 막을 수 있습니다. 저는 이 방법으로 프롬프트 변경 후 오류를 60% 줄였습니다(가상 수치).
예상되는 한계
Claude 모델 특성상 매우 도메인 특화된 용어에는 오류가 발생할 수 있습니다. 이런 경우 도메인 지식을 보강한 few-shot 예시 또는 외부 검증(정규표현식, 룰 엔진)을 결합하세요.
FAQ
Claude Code와 ChatGPT를 함께 쓰면 좋은가?
네. 예를 들어 Claude는 요약·분석에, GPT-4는 창작형 텍스트 생성에 사용하는 식으로 역할을 분리하면 성능·비용에서 이득이 있습니다.
서브에이전트 상태·로깅은 어떻게 관리하나요?
작업별 로그와 입력/출력 샘플을 JSON 형태로 저장하세요. S3나 Airtable에 원본 로그를 남기고, 에러만 Sentry로 집계하면 빠르게 원인 파악이 가능합니다.
다음 행동(바로 해볼 것)
1) 우선 역할 하나(Summarizer나 Tagger)를 선택하세요. 2) 간단한 JSON 입출력 스펙을 정의하고 3) Claude Code에서 프롬프트를 넣어 테스트해보세요. 아래 예제 프롬프트를 복사해서 시작하면 좋습니다.
내부/외부 참고 링크
- 내부: Claude Code 기본 워크플로 정리
- 외부: Anthropic 공식 문서
- 외부: n8n (자동화 트리거 예시)
마무리 요약
Claude Code 서브에이전트 만들기는 역할 정의와 입출력 계약만 명확히 하면 빠르게 프로토타입화할 수 있습니다. 먼저 한 역할을 분리해 테스트하고, 이후에 모듈을 확장하는 방식으로 진행하세요.
Disclaimer: 도구의 기능·요금은 자주 바뀌므로 최신 공식 문서를 확인하세요. 본 글의 비용·성능 수치는 예시·경험 기반으로 실제와 다를 수 있습니다.
