Subagents & Agent Teams

Subagents (서브에이전트)

서브에이전트란?

서브에이전트는 메인 에이전트가 하위 작업을 전문 에이전트에게 위임하는 구조입니다. 각 서브에이전트는 자체 컨텍스트 윈도우에서 독립 실행되며, 결과만 메인 에이전트에게 반환합니다. 메인의 컨텍스트를 소비하지 않는 것이 핵심 장점입니다.

메인 에이전트 (사용자와 대화)
  |-- cafe24-analyst  (카페24 데이터 분석 전담)
  |-- brand-reporter  (브랜드 보고서 생성 전담)
  +-- code-reviewer   (코드 품질 리뷰 전담)

빌트인 서브에이전트

Claude Code에는 기본 내장된 서브에이전트가 있습니다:

커스텀 서브에이전트 만들기

서브에이전트 파일 구조

마크다운 파일에 YAML 프론트매터로 설정하고, 본문에 시스템 프롬프트를 작성합니다:

---
name: cafe24-analyst
description: 카페24 주문 데이터를 분석하고 인사이트를 추출합니다. 데이터 분석이 필요할 때 사용하세요.
tools: Read, Grep, Glob, Bash, Write
model: sonnet
memory: project
---

# 카페24 데이터 분석 에이전트

## 역할
각 브랜드별 카페24 스토어에서 내보낸 주문 엑셀/CSV를 분석하여 인사이트를 추출합니다.

## 규칙
- 각 브랜드별 카페24 스토어가 별도이므로, 입력 파일이 어떤 브랜드인지 먼저 확인
- 금액 단위는 원화, 천 단위 콤마 적용
- 이상치 탐지: 평균 대비 3배 이상 차이나는 주문 플래그
- 결과는 항상 JSON + 마크다운 테이블 두 가지로 출력

프론트매터 필드 전체 표

이그니스 맞춤 서브에이전트 3종

# .claude/agents/cafe24-analyst.md
---
name: cafe24-analyst
description: 카페24 주문 데이터를 분석하고 인사이트를 추출합니다
tools: Read, Write, Bash, Glob, Grep
model: sonnet
memory: project
---

# 카페24 데이터 분석 에이전트

## 규칙
- 브랜드별 카페24 스토어가 별도이므로 입력 파일의 브랜드를 먼저 확인
- 이상치 탐지: 평균 대비 3배 이상 차이나는 주문 플래그
- 결과는 JSON + 마크다운 테이블로 출력

## 출력 형식
- summary.json: 브랜드별 요약 통계
- report.md: 읽기 쉬운 분석 보고서
- anomalies.md: 이상치 목록

# .claude/agents/brand-reporter.md
---
name: brand-reporter
description: 8개 브랜드의 월간/주간 보고서를 표준 형식으로 생성합니다
tools: Read, Write, Bash
model: sonnet
memory: project
---

# 브랜드 보고서 에이전트

## 보고서 구조
1. 요약 (3줄 이내)
2. 핵심 지표 테이블 (매출, 주문수, AOV, 반품률)
3. 전월 대비 변동
4. Top 5 SKU 랭킹
5. 이슈 및 제안사항

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: 코드 보안, 품질, 성능을 검토합니다
tools: Read, Glob, Grep, Bash
model: opus
permissionMode: strict
---

# 코드 리뷰 에이전트

## 체크리스트
- .env 파일이 .gitignore에 포함되어 있는가
- API 키가 코드에 하드코딩되어 있지 않은가
- SQL injection 가능성이 있는 쿼리가 없는가
- 에러 핸들링이 적절한가
- 불필요한 console.log가 남아 있지 않은가

## 심각도 분류
- CRITICAL: 보안 취약점, 데이터 유출 위험
- WARNING: 성능 이슈, 잠재적 버그
- INFO: 코드 스타일, 개선 제안

Persistent Memory (영속 메모리)

서브에이전트가 세션 간에 학습한 내용을 유지하려면 memory 필드를 설정합니다.

메모리는 MEMORY.md 파일로 자동 관리됩니다. 에이전트가 작업하면서 발견한 패턴, 규칙, 이슈를 기록하고, 다음 세션에서 자동으로 로딩합니다.

# .claude/agent-memory/cafe24-analyst/MEMORY.md (자동 생성)

## 학습된 패턴
- 카페24 CSV의 날짜 형식이 가끔 YYYY/MM/DD로 들어옴 (정규식 처리 필요)
- 클룹 SKU 코드에 하이픈(-)이 포함된 경우 파싱 에러 발생
- 3월부터 '엑쎄라피' 브랜드가 추가됨

서브에이전트 호출 방법

# 1. 자연어로 호출 (메인 에이전트가 판단)
"cafe24-analyst 에이전트로 이번 달 주문 데이터를 분석해줘"

# 2. @멘션으로 직접 호출
@"code-reviewer (agent)" 인증 모듈 리뷰해줘

# 3. 세션 전체를 특정 에이전트로 실행
claude --agent code-reviewer

# 4. 등록된 에이전트 목록 확인
/agents

메인 에이전트가 Agent 도구를 사용해 서브에이전트를 호출하면, 서브에이전트는 독립된 컨텍스트에서 작업을 수행하고 결과만 메인 에이전트에게 반환합니다.

Agent Teams (에이전트 팀)

에이전트 팀이란?

Agent Teams는 여러 독립 Claude 세션이 협업하는 실험적 기능입니다 (Opus 4.6과 함께 출시). 서브에이전트가 "위임"이라면, Agent Teams는 "협업"입니다. 가장 큰 차이점은 팀원끼리 서로 직접 소통할 수 있다는 것입니다.

활성화

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Subagents vs Agent Teams 비교표

팀 구성 요소

실전 시나리오: 한끼통살 신제품 랜딩 페이지

에이전트 팀을 만들어서 한끼통살 신제품 랜딩 페이지를 만들자.

- 디자이너 팀원: UI/UX 설계, 컴포넌트 구조, 와이어프레임
- 개발자 팀원: React 코드 구현, Tailwind 스타일링
- QA 팀원: 접근성(a11y), 반응형, 성능 테스트

디자이너가 구조를 잡으면 개발자가 구현하고,
QA가 검증 결과를 양쪽에 피드백하는 방식으로 진행해줘.

팀이 생성되면 각 팀원이 독립 세션으로 실행되며, Task list와 Mailbox를 통해 자율적으로 협업합니다.

디스플레이 모드

팀 Best Practices

1. 팀 규모: 3-5명이 적절. 너무 많으면 조율 비용이 토큰 절약보다 커짐
2. 작업 배분: 팀원당 5-6개 태스크가 이상적
3. 파일 충돌 방지: 팀원별 다른 파일/디렉토리를 담당하도록 설계
4. 안전한 시작: 리서치/리뷰부터 시작 (코드 작성보다 안전하고 효과 검증 가능)
5. Worktree 활용: 각 팀원이 별도 worktree에서 작업하면 충돌 원천 차단