학습 개요
서브에이전트 팀 구성, 등록 방법, Agent Teams와의 차이, 운영 팁 등을 학습했다.
1. 서브에이전트 기본 개념
- 서브에이전트는
~/.claude/agents/ (사용자 레벨) 또는 .claude/agents/ (프로젝트 레벨)에 .md 파일로 정의
- YAML frontmatter + 시스템 프롬프트(마크다운) 구조
- 필수 필드:
name, description / 선택 필드: tools, model
description은 Claude가 언제 이 에이전트를 쓸지 판단하는 트리거 → 영어로 작성이 위임 정확도에 유리- 시스템 프롬프트 본문은 한국어로 작성해도 무방
---
name: data-explorer
description: Use PROACTIVELY when the task involves EDA...
tools: Read, Bash, Glob, Grep
model: sonnet
---
당신은 탐색적 데이터 분석 전문가입니다...
2. 등록한 상시 팀 구성 (10개)
데이터 분석 팀
| 에이전트 |
역할 |
모델 |
data-explorer |
EDA, 데이터 품질 점검 |
sonnet |
sql-analyst |
SQL/DAX/D365 쿼리 |
sonnet |
viz-designer |
시각화 설계, 대시보드 |
haiku |
ml-optimizer |
모델 선택, 하이퍼파라미터 튜닝 |
sonnet |
바이브 코딩 팀
| 에이전트 |
역할 |
모델 |
architect |
시스템 설계, 기술 스택 결정 |
sonnet |
implementer |
코드 구현 |
sonnet |
code-reviewer |
코드 리뷰, 보안 점검 |
sonnet |
debugger |
오류 추적 및 수정 |
sonnet |
공유 유틸리티
| 에이전트 |
역할 |
모델 |
doc-writer |
문서, README |
haiku |
test-runner |
테스트 작성 및 실행 |
haiku |
비용 최적화: viz-designer, doc-writer, test-runner는 복잡한 추론이 불필요해 Haiku로 설정 → 한도 소진 속도를 늦추는 효과
3. 파일 생성 방법
- bash 스크립트(
create_agents.sh)로 10개 파일 일괄 생성
- 채팅 모드의 bash_tool은 클라우드 샌드박스에서 실행 → 로컬에 실제 파일이 생성되지 않음
- 실제 생성은 스크립트 다운로드 후 로컬 터미널에서 직접 실행해야 함
bash ~/Downloads/create_agents.sh # Mac
# Windows는 경로 형식 다름
4. 서브에이전트 vs Agent Teams
| 구분 |
서브에이전트 |
Agent Teams |
| 에이전트 간 소통 |
메인만 통해 보고 |
직접 메시지 가능 |
| 실행 방식 |
단일 세션 내 |
독립 세션 여러 개 |
| 토큰 소비 |
기준 |
약 3~5배 많음 |
| 상태 |
안정적 |
실험적 (2026년 3월 기준) |
| 활성화 |
기본 활성 |
별도 설정 필요 |
| 화면 분할 |
지원 안 함 |
tmux 설치 시 가능 |
언제 Agent Teams를 쓰나: 에이전트끼리 실시간 조율이 필요할 때
현실적 판단: 서브에이전트로 90% 커버 가능
보충: Agent Teams 활성화는 환경변수 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 설정 필요. 각 teammate는 자체 컨텍스트 윈도우를 가지며, 공유 task list를 통해 자기 조율하는 방식으로 동작함
5. 호출 방법
# 자동 위임 (Claude가 description 보고 판단)
"이 데이터 탐색해줘" → data-explorer 자동 호출
# 명시적 호출
"architect 에이전트로 설계해줘"
6. 병렬 vs 순차 실행
- 순차: 앞 단계 output이 다음 단계 input인 경우 (EDA → 설계 → 구현)
- 병렬: 독립적인 작업 (차트 3개 동시 생성 등)
- Claude가 description과 작업 의존성을 보고 자동 판단
7. Max 플랜과 과금
- Max 플랜은 서브에이전트 토큰도 구독에 포함 → 별도 과금 없음
/cost 명령어는 API 사용자용, Max 구독자는 /stats 사용- Agent Teams는 약 3~5배 토큰 소비 → 5시간 한도 소진 빠를 수 있음
- Max 플랜에서 한도 초과 시 속도 제한(rate limit)이 걸림
8. 터미널 줄바꿈
- Windows에서 Shift+Enter는 현재 공식 버그 (미지원)
- 대안:
\ 입력 후 Enter, VS Code 터미널에서 /terminal-setup 실행, 메모장에서 작성 후 붙여넣기
9. 채팅 모드 vs Claude Code 터미널
| 구분 |
채팅 모드 |
Claude Code 터미널 |
| 로컬 파일 접근 |
불가 |
가능 |
| 서브에이전트 실행 |
불가 |
가능 |
| bash_tool |
클라우드 샌드박스 |
로컬 환경 |
| 용도 |
설계/학습/문서 |
실제 코드 작업 |
출처