Claude Code 서브 에이전트를 활용하는 방법 #1

Claude Code를 단일 에이전트로만 사용하고 계신가요? 서브 에이전트와 백그라운드 에이전트를 제대로 활용하면 컨텍스트 윈도우를 절약하면서 더 높은 품질의 결과물을 얻을 수 있습니다. 이 글에서는 서브 에이전트의 개념부터 실전 워크플로우까지 자세히 알아보겠습니다.

---

🤔 서브 에이전트란?

서브 에이전트는 메인 에이전트가 특정 작업을 위임할 수 있는 전문화된 보조 에이전트입니다. 마치 팀장이 팀원들에게 업무를 분배하듯이, 메인 에이전트가 서브 에이전트들에게 작업을 할당하고 결과를 수집합니다.

서브 에이전트 사용의 장점

1. 컨텍스트 윈도우 절약: 서브 에이전트의 작업 내용이 메인 대화에 누적되지 않음
2. 병렬 처리: 여러 작업을 동시에 수행 가능
3. 전문화된 결과: 각 에이전트가 특정 영역에 집중하여 더 나은 품질 제공
4. 대규모 프로젝트 가능: 단일 스레드로는 불가능한 복잡한 구현 가능

---

🔧 기본 제공 서브 에이전트

Claude Code는 다음과 같은 내장 서브 에이전트를 제공합니다:

에이전트 설명 사용 모델

Bash Agent	Git 작업, 커맨드 실행, 터미널 작업 전문	-
General Purpose Agent	복잡한 질문 조사, 코드 검색, 다단계 작업	-
Explore Agent	코드베이스 빠른 탐색, 패턴 및 파일 검색	Haiku (빠르고 저렴)
Planning Agent	계획 단계에서 요구사항 분석 및 솔루션 계획	-
Claude Code Guide Agent	Claude Code 기능 관련 질문 답변	-

---

📝 서브 에이전트 호출 방법

방법 1: @ 기호로 직접 호출

@agent claude-code-guide hooks란 무엇인가요?

방법 2: 메인 에이전트에게 요청

프로젝트의 기술 스택과 핵심 기능을 요약해주세요. 
explore 에이전트 2개를 사용해서 병렬로 분석해주세요.

방법 3: 백그라운드 실행 (Ctrl + B)

작업을 백그라운드로 보내고 메인 에이전트와 다른 대화를 계속할 수 있습니다.

---

🎯 실전 예제 1: 코드베이스 분석

❌ 잘못된 방법 (서브 에이전트 미사용)

프로젝트의 기술 스택과 핵심 기능을 요약해주세요.

결과: 메인 에이전트가 모든 작업 수행 → 컨텍스트 15% 소비

✅ 올바른 방법 (서브 에이전트 활용)

프로젝트의 기술 스택과 핵심 기능을 요약해주세요.
explore 에이전트 2개를 사용해서 병렬로 분석해주세요.

결과:

• Explore Agent #1: 기술 스택과 설정 분석
• Explore Agent #2: 핵심 기능 분석
• 컨텍스트 14% 소비 + 더 높은 품질의 결과

---

🛠️ 실전 예제 2: 커스텀 에이전트 만들기

Claude Code에서 /agents 명령어를 실행하면 커스텀 에이전트를 만들 수 있습니다.

UI/UX 전문가 에이전트 예시

에이전트 이름: UI
설명: 20년 이상 경력의 UI/UX 전문가입니다.
이 프로젝트에서는 네오 브루탈리즘 디자인을 적용합니다.
- 밝은 색상과 강한 그림자를 가진 컴포넌트
- 생동감 있는 색상
- 미니멀리스트 UI
- 반응형 디자인

Code Review 에이전트 예시

에이전트 이름: Code Review
설명: 시니어 개발자로서 코드 리뷰를 수행합니다.
- 코드 구조 분석
- 보안 취약점 검토
- 성능 최적화 제안
- 접근성 검토

Coder 에이전트 예시

에이전트 이름: Coder
설명: 구현 전문 개발자입니다.
- 계획에 따른 정확한 구현
- 클린 코드 작성
- 에러 핸들링
- 테스트 고려

---

🚀 실전 예제 3: 복잡한 기능 구현 워크플로우

대규모 기능을 구현할 때 서브 에이전트의 진가가 발휘됩니다.

Step 1: 계획 수립 (Planning Agent 활용)

Task Manager 앱에 다음 기능을 추가해야 합니다:
- 사용자 인증 (이메일/비밀번호)
- 할 일 CRUD
- 칸반 보드 (드래그 앤 드롭)
- 캘린더 뷰
- 필터링 및 정렬
- 카테고리 관리

planning 에이전트를 사용해서 구현 계획을 세워주세요.
각 단계별로 의존성을 파악하고 병렬 처리 가능한 작업을 식별해주세요.

Step 2: 병렬 구현 (다중 Coder Agent 활용)

이 기능을 구현해야 합니다.
직접 코드를 작성하지 마세요.
당신의 역할은 coding agent와 code review agent 간의 작업을 조율하는 것입니다.

구현 계획을 분석하고:
1. 서로 의존성이 없는 작업들을 찾아 다른 트랙으로 분류
2. 각 트랙에 coder 에이전트를 할당하여 병렬 구현
3. 구현 완료 후 code review 에이전트에게 전달
4. 리뷰 피드백을 coder 에이전트에게 다시 전달
5. 모든 구현 완료 후 3개의 code review 에이전트로 최종 검토
   - 보안 관점
   - 접근성 관점  
   - 성능 관점

결과

이 워크플로우를 사용하면:

• Wave 1: 프로젝트 기본 설정 (의존성이 있어 먼저 수행)
• Wave 2: 칸반 보드 / 캘린더 / 필터링 (병렬 처리)
• Wave 3: 최종 통합 및 리뷰

단일 스레드로 구현하면 Phase 8~9 정도에서 컨텍스트 압축이 발생하지만, 서브 에이전트를 활용하면 전체 프로젝트를 58% 컨텍스트만 사용하여 완료할 수 있습니다.

---

💡 핵심 팁

1. 백그라운드 작업 확인

Ctrl + B로 백그라운드 실행 후, 아래 방향키를 누르면 실행 중인 에이전트 목록을 확인할 수 있습니다.

2. 병렬 처리 가능한 작업 식별

서로 의존성이 없는 작업들은 항상 병렬로 처리하세요:

• 독립적인 컴포넌트 개발
• 서로 다른 페이지 구현
• 프론트엔드/백엔드 동시 작업

3. 컨텍스트 윈도우 모니터링

[Context: 15%] → 서브 에이전트 미사용
[Context: 14%] → 서브 에이전트 사용 (+ 더 나은 품질)

4. 에이전트 범위 설정

LLM은 범위가 좁을수록 더 나은 결과를 제공합니다. 서브 에이전트에게 명확하고 구체적인 작업을 할당하세요.

---

🔄 권장 워크플로우 요약

┌─────────────────────────────────────────────────────────┐
│                    메인 에이전트                          │
│                 (작업 조율 및 통합)                        │
└─────────────────────────────────────────────────────────┘
                           │
        ┌─────────────────┼─────────────────┐
        ▼                 ▼                 ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│  Track 1      │ │  Track 2      │ │  Track 3      │
│  Coder Agent  │ │  Coder Agent  │ │  Coder Agent  │
│      ↓        │ │      ↓        │ │      ↓        │
│ Review Agent  │ │ Review Agent  │ │ Review Agent  │
└───────────────┘ └───────────────┘ └───────────────┘
                           │
                           ▼
              ┌─────────────────────────┐
              │     최종 통합 리뷰        │
              │  (보안/접근성/성능)       │
              └─────────────────────────┘

---

📌 결론

Claude Code의 서브 에이전트는 단순한 기능이 아닌 필수 도구입니다. 특히:

• 코드베이스 분석 시
• 복잡한 기능 구현 시
• 대규모 리팩토링 시
• 여러 파일을 동시에 수정해야 할 때

서브 에이전트를 적극 활용하면 컨텍스트 윈도우 제한을 극복하고, 더 높은 품질의 결과물을 더 빠르게 얻을 수 있습니다.

"직접 코드를 작성하지 말고, 에이전트들을 조율하세요!"

---

참고 명령어 정리

명령어 설명

/agents	에이전트 목록 확인 및 생성
@agent-name	특정 에이전트 직접 호출
Ctrl + B	현재 작업을 백그라운드로 전환
↓ (방향키)	백그라운드 작업 목록 확인

---