[Claude Code] Sub Agent

1. 서브 에이전트란?

서브 에이전트는 메인 AI 에이전트가 복잡한 작업을 처리할 때, 특정 하위 작업을 별도의 AI 인스턴스(에이전트)에게 위임하는 구조입니다. 즉, 하나의 클로드가 "오케스트레이터(지휘자)" 역할을 하고, 여러 개의 클로드 인스턴스가 각각 독립적인 서브 에이전트로서 세부 작업을 처리하는 계층적 구조입니다.

메인 에이전트 (오케스트레이터)
    ├── 서브 에이전트 A (데이터 수집 담당)
    ├── 서브 에이전트 B (분석 담당)
    └── 서브 에이전트 C (보고서 작성 담당)

 

2. 언제 활용?

서브 에이전트가 특히 유용한 상황은 다음과 같습니다.

1) 병렬 처리가 필요할 때 :

여러 작업을 동시에 진행해야 할 때 각 서브 에이전트에게 독립적으로 작업을 분배하면 처리 시간을 대폭 줄일 수 있습니다.

2) 컨텍스트 분리가 필요할 때 :

각 서브 에이전트는 자신의 작업에만 집중하므로 컨텍스트 오염(context pollution) 없이 깔끔하게 작업할 수 있습니다.

3) 전문화된 역할 분리가 필요할 때 :

코드 작성, 테스트, 문서화처럼 성격이 다른 작업을 각각 전문화된 서브 에이전트가 처리할 때 품질이 높아집니다.

4) 긴 작업 체인이 필요할 때 :

단일 에이전트의 컨텍스트 윈도우 한계를 넘어서는 장기 작업을 처리할 때 효과적입니다.

 

전통적인 AI 활용 방식과 비교해 보면 좀 더 감이 올 수 있는데요. 개발자가 모든 기획과 테스트를 도맡고 AI에게는 단순 코딩만 지시하는 '구시대적' 방식을 생각해볼까요? 이는 결과물의 퀄리티 컨트롤(Quality Control)을 어렵게 만들고, AI의 판단이 '블랙박스'화 되어 왜 특정 기능이 누락되거나 변형되었는지 파악하기 어렵게 합니다. 이렇게되면 동일한 요청에도 매번 다른 결과물이 생성되고(일관성 결여), 개발자가 직접 모든 테스트와 리뷰를 수행해야 합니다(생산성 한계).
마치 개발자는 회사의 CEO처럼 상위 수준의 요구사항만 전달하고, 구체적인 기획, 설계, 구현, 테스트는 전문화된 서브 에이전트들이 수행하도록 구조화하는 방식이 Sub-Agent를 활용하는 방식이라 할 수 있겠습니다. 

 

다음과 같은 예시를 볼까요?

메인 에이전트: "이 프로젝트를 리팩토링해줘"
    ├── 서브 에이전트 A: 파일 구조 분석 및 의존성 파악
    ├── 서브 에이전트 B: 각 모듈별 리팩토링 실행
    ├── 서브 에이전트 C: 테스트 코드 작성
    └── 서브 에이전트 D: 문서화 업데이트

 

 

3. Skills와의 차이점

저는 Skills와 약간 개념이 헷갈렸는데요

정의	특정 작업을 잘 수행하기 위한 지식/가이드라인 문서	독립적으로 작동하는 AI 인스턴스
형태	텍스트 기반 SKILL.md 파일	별도의 API 호출로 생성되는 모델 인스턴스
역할	"어떻게 해야 하는가"를 알려주는 레시피	"실제로 실행하는" 요리사
실행 주체	단일 에이전트가 스킬을 읽고 스스로 수행	별도의 에이전트가 독립적으로 수행
병렬성	없음 (순차적)	여러 에이전트가 동시 실행 가능
컨텍스트	메인 에이전트 컨텍스트 공유	각자 독립적인 컨텍스트 보유
사용 목적	품질 향상, 베스트 프랙티스 적용	복잡한 작업의 병렬/분산 처리

비유하자면 Skills는 요리책(레시피)이고 서브 에이전트는 실제 요리사입니다. 요리책을 읽고 혼자 요리할 수도 있지만(단일 에이전트 + Skills), 복잡한 연회를 준비할 때는 여러 요리사(서브 에이전트)가 각자 역할을 나눠 동시에 요리하는 것이 훨씬 효율적입니다.

 

4. 사용방식

클로드 코드에서 /agents 명령어를 사용하면 agents 폴더 아래에 *.md 파일이 생성됩니다. 

/agents 명령어는 서브 에이전트를 대화형으로 관리하는 인터페이스를 제공합니다. 이를 통해 사용 가능한 모든 서브 에이전트 확인, 새 서브 에이전트 생성 (가이드 방식 또는 Claude 자동 생성), 기존 서브 에이전트 수정 및 도구 접근 권한 편집, 그리고 중복 이름이 있을 때 어느 것이 활성화되어 있는지 확인이 가능합니다. 

# Claude Code CLI에서 실행
/agents          # 서브 에이전트 관리 인터페이스 열기
/agents create   # 새 서브 에이전트 생성

 

예를 들어 아래와 같은 방식으로 만들 수 있겠죠.

---
name: code-reviewer
description: 코드 품질, 보안, 유지보수성 검토가 필요할 때 사용.
             PR 리뷰, 보안 감사, 코드 스타일 점검 시 자동 호출됨.
tools: Read, Grep, Glob, Bash
model: sonnet
---

당신은 시니어 보안 중심 코드 리뷰어입니다.
코드를 검토할 때는 다음을 확인하세요:
- SQL Injection, XSS, CSRF 취약점
- 민감한 정보 노출 (API 키, 비밀번호)
- 성능 병목 지점
- 코드 가독성 및 유지보수성

## 출력 형식
항상 다음 형식으로 결과를 제공하세요:
# 🔍 코드 리뷰 결과
- **판정**: [수정 필요 | 승인]
- **긴급 이슈**: X건
- **권고 사항**: Y건

 

 

참고) Skills와 Sub-Agent의 연계

서브 에이전트 정의 시 skills 필드를 사용하면, 서브 에이전트 시작 시 스킬 내용을 컨텍스트에 주입할 수 있습니다. 이렇게 하면 실행 중에 스킬을 직접 로드할 필요 없이 도메인 지식을 갖춘 채로 시작합니다. 

예) 성능 최적화 Agent

---
name: performance-optimizer
description: 데이터베이스 쿼리, API 응답 속도, 메모리 사용량 최적화 시 사용.
             "느리다", "최적화", "성능" 키워드가 나오면 자동 호출.
tools: Read, Edit, Bash, Grep
model: sonnet
skills:
  - query-optimization
  - caching-patterns
---

당신은 성능 최적화 전문가입니다...

 

5. Market Place에서 Sub Agent의 등록과 설치

Market place에 등록된 subagent 패키지를 추가하는 명령어는 아래와 같습니다. 

/plugin marketplace add popup-studio-ai/bkit-claude-code

 

그리고 나서 실제로 설치하는 명령어는 아래와 같습니다. 

/plugin install bkit