서브 에이전트 세부 가이드

AI 팀을 구성하여 복잡한 작업을 효율적으로 처리하는 혁신적인 기능

서브 에이전트란?

서브 에이전트는 특정 목적과 전문 분야를 가진 전문화된 AI 어시스턴트입니다. 각 서브 에이전트는 독립된 컨텍스트 창을 가지고 있어 메인 대화의 맥락을 보존하면서도 전문적인 작업을 수행할 수 있습니다.

주요 특징

  • 특정 목적과 전문 분야를 가진 AI
  • 독립된 컨텍스트 창으로 작업
  • 도구별 세밀한 권한 설정 가능
  • 커스텀 시스템 프롬프트 지원

주요 이점

  • 컨텍스트 오염 방지
  • 전문 분야별 최적화
  • 재사용 및 팀 공유 가능
  • 유연한 권한 관리

서브 에이전트 생성하기

1. 대화형 생성 (권장)

가장 쉬운 방법은 Claude Code에게 직접 생성을 요청하는 것입니다:

/agents

대화형 인터페이스에서 에이전트의 목적을 설명하면 Claude가 자동으로 초안을 생성합니다.

2. 파일 구조

서브 에이전트는 YAML 프론트매터가 포함된 마크다운 파일로 정의됩니다:

---
name: code-reviewer
description: Expert code review specialist focusing on quality and security
tools: Read, Grep, Glob, Bash
---

# 코드 리뷰 전문가

당신은 코드 품질과 보안을 중시하는 시니어 코드 리뷰어입니다.

## 리뷰 체크리스트:
- 코드가 간단하고 읽기 쉬운가
- 함수와 변수명이 명확한가
- 중복 코드가 없는가
- 적절한 에러 처리가 되어 있는가
- 보안 취약점이 없는가

3. 저장 위치

프로젝트 레벨

.claude/agents/

프로젝트별 특화 에이전트

사용자 레벨

~/.claude/agents/

모든 프로젝트에서 사용 가능

기본 제공 에이전트

code-reviewer

코드 품질, 보안, 유지보수성을 검토하는 전문가. git diff를 활용해 변경사항을 분석하고 개선점을 제안합니다.

debugger

오류 및 테스트 실패의 근본 원인을 분석하는 전문가. 체계적인 프로세스로 문제를 격리하고 수정합니다.

data-scientist

SQL 쿼리 작성 및 실행 전문가. BigQuery를 위한 bq 커맨드 라인 도구 사용에 특화되어 있습니다.

test-runner

코드 변경을 감지하면 자동으로 테스트를 실행하고, 실패 시 수정을 시도하는 에이전트입니다.

실전 활용 사례

1. 복잡한 리팩토링 프로젝트

대규모 코드베이스를 리팩토링할 때 여러 전문 에이전트를 조합하여 사용:

1단계:code-analyzer - 현재 구조 분석
2단계:refactoring-architect - 개선 계획 수립
3단계:implementation - 실제 코드 변경
4단계:test-runner - 테스트 실행 및 검증

2. 병렬 분석 작업

UI 컴포넌트를 여러 관점에서 동시에 분석:

디자인 전문가

UI/UX 패턴 분석

접근성 전문가

WCAG 준수 검토

성능 전문가

렌더링 최적화 제안

3. 자율 개발 팀 구성

claude-code-sub-agent-collective 프로젝트의 19개 전문 에이전트 팀:

PM연구원아키텍트프론트엔드백엔드QADevOps보안문서화

복잡도에 따라 자동으로 적절한 에이전트 조합을 선택하여 작업을 수행

모범 사례

✅ 권장 사항

  • 단일 책임 원칙: 각 에이전트는 하나의 명확한 역할만 담당
  • 명확한 설명: description 필드에 구체적이고 행동 지향적인 설명 작성
  • 최소 권한: 필요한 도구만 선택적으로 부여
  • 반복 개선: Claude가 생성한 초안을 지속적으로 커스터마이징

❌ 피해야 할 사항

  • 만능 에이전트: 모든 작업을 하나의 에이전트에 몰아넣기
  • 모호한 설명: 애매하거나 너무 일반적인 description
  • 과도한 권한: 불필요한 도구까지 모두 허용
  • 자동 위임 의존: 명시적 호출 없이 자동 선택만 기대

💡 Pro Tip: 현재는 자동 위임이 완벽하지 않으므로, 중요한 작업은"code-reviewer 에이전트를 사용해서..."와 같이 명시적으로 호출하는 것이 안정적입니다.

고급 오케스트레이션 패턴

1. 순차적 파이프라인

# 순차적 작업 흐름 예시
claude> 다음 에이전트들을 순서대로 사용해서 리팩토링을 진행해줘:
1. code-analyzer로 현재 구조 분석
2. refactoring-architect로 개선 계획 수립  
3. implementation으로 실제 변경 적용
4. test-runner로 테스트 실행

2. 병렬 처리

# 병렬 분석 예시
claude> 이 컴포넌트를 다음 에이전트들로 동시에 분석해줘:
- ui-designer: UI/UX 패턴 분석
- accessibility-expert: 접근성 검토
- performance-analyst: 성능 최적화 기회

3. 조건부 분기

# CLAUDE.md에서 복잡도 기반 라우팅
if (complexity === 'high') {
  // senior-architect → implementation → code-reviewer
} else {
  // implementation → test-runner
}

다음 단계

시작하기

  1. 1. /agents 명령으로 첫 에이전트 생성
  2. 2. 기본 제공 에이전트로 실험해보기
  3. 3. 프로젝트에 맞게 커스터마이징
  4. 4. 팀과 공유하여 생산성 향상

고급 활용

  • • 멀티 에이전트 워크플로우 구축
  • • CLAUDE.md와 연계한 자동화
  • • MCP 서버와 통합
  • • 커뮤니티 에이전트 활용 및 기여
고급 기능으로 돌아가기