Claude Code를 쓰다 보면 한 가지 아쉬운 점이 생깁니다. 복잡한 작업을 시키면 컨텍스트 윈도우가 금방 차오르고, 중간 과정의 잡음이 대화를 어지럽힌다는 것입니다. 서브에이전트(Sub-agent)는 바로 이 문제를 해결하기 위해 등장했습니다.
서브에이전트는 말 그대로 "부하 AI"입니다. 메인 에이전트가 특정 작업을 서브에이전트에게 위임하면, 서브에이전트는 자신만의 독립된 컨텍스트에서 작업을 수행하고 결과만 돌려줍니다. 마치 팀장이 팀원에게 업무를 배분하는 것과 같습니다.
서브에이전트란 무엇인가
서브에이전트는 Claude Code 안에서 동작하는 전문화된 AI 어시스턴트입니다. 각 서브에이전트는 고유한 시스템 프롬프트, 제한된 도구 접근 권한, 그리고 독립된 컨텍스트 윈도우를 갖습니다.
핵심 특징을 정리하면 이렇습니다:
- 컨텍스트 격리: 서브에이전트의 중간 작업은 메인 대화에 영향을 주지 않습니다
- 도구 제한: 서브에이전트별로 사용 가능한 도구를 지정할 수 있습니다
- 병렬 실행: 여러 서브에이전트를 동시에 실행할 수 있습니다
- 단일 계층: 서브에이전트는 또 다른 서브에이전트를 생성할 수 없어 구조가 단순합니다
Claude Code에는 Explore, Plan 같은 빌트인 서브에이전트가 이미 내장되어 있습니다. Explore는 코드베이스를 빠르게 탐색하고, Plan은 구현 전략을 설계하는 데 특화되어 있습니다.
서브에이전트의 작동 원리
서브에이전트의 동작 흐름은 놀라울 정도로 심플합니다.
- 메인 에이전트가
Agent도구를 호출하며 프롬프트를 전달합니다 - 서브에이전트가 독립된 컨텍스트에서 작업을 수행합니다 (파일 읽기, 검색, 코드 실행 등)
- 작업이 끝나면 최종 결과만 메인 에이전트에게 반환합니다
- 메인 에이전트는 결과를 받아 다음 단계를 진행합니다
이 구조의 가장 큰 장점은 컨텍스트 절약입니다. 예를 들어 코드베이스에서 특정 패턴을 찾기 위해 수십 개 파일을 읽어야 한다면, 그 과정이 모두 메인 대화에 쌓이면 금방 한계에 도달합니다. 서브에이전트에게 위임하면 중간 과정은 서브에이전트의 컨텍스트에서 소화되고, 핵심 결과만 깔끔하게 돌아옵니다.
메인 에이전트 ──┬── 서브에이전트 A (코드 탐색) ──→ 결과 A
├── 서브에이전트 B (보안 검사) ──→ 결과 B
└── 서브에이전트 C (테스트 분석) ──→ 결과 C
커스텀 서브에이전트 만들기
서브에이전트를 직접 만드는 방법은 간단합니다. 프로젝트의 .claude/agents/ 디렉토리에 마크다운 파일을 생성하면 됩니다.
---
name: security-scanner
description: 코드의 보안 취약점을 분석하는 에이전트
tools:
- Read
- Grep
- Glob
---
당신은 보안 전문가입니다.
코드에서 OWASP Top 10 취약점을 탐지하고,
구체적인 수정 방안을 제시하세요.
파일 이름이 곧 에이전트 ID가 됩니다. security-scanner.md로 저장하면 Claude Code가 자동으로 인식하고, 관련 작업에서 이 에이전트를 활용합니다.
설계 팁 몇 가지:
description을 명확하게 작성하세요. Claude가 언제 이 에이전트를 쓸지 판단하는 기준입니다tools를 최소한으로 제한하세요. 읽기 전용 에이전트에 Edit 도구를 줄 필요가 없습니다- 시스템 프롬프트에 구체적인 출력 형식을 지정하면 결과의 일관성이 높아집니다
실전 활용 시나리오
서브에이전트가 빛나는 대표적인 시나리오를 소개합니다.
코드 리뷰 병렬화: PR 리뷰 시 스타일 검사, 보안 스캔, 테스트 커버리지 분석을 각각 서브에이전트에게 맡기면 순차 실행 대비 시간을 대폭 줄일 수 있습니다.
대규모 코드베이스 탐색: 수백 개 파일에서 특정 패턴을 찾아야 할 때, Explore 서브에이전트는 메인 컨텍스트를 오염시키지 않고 결과만 반환합니다.
멀티 태스크 자동화: 문서 생성, 테스트 작성, 린트 수정 같은 독립적인 작업을 동시에 실행할 수 있습니다. 한 에이전트가 README를 업데이트하는 동안 다른 에이전트가 유닛 테스트를 작성하는 식입니다.
PDCA 워크플로우: bkit 같은 도구와 결합하면 Plan → Design → Do → Check 각 단계에 전문 에이전트를 배치하여 체계적인 개발 프로세스를 구축할 수 있습니다.
서브에이전트 활용 베스트 프랙티스
서브에이전트를 효과적으로 사용하기 위한 핵심 원칙입니다.
- 프롬프트를 구체적으로: 서브에이전트는 메인 대화의 맥락을 모릅니다. 필요한 정보를 모두 프롬프트에 담아주세요
- 독립적인 작업만 병렬화: 의존관계가 있는 작업을 동시에 실행하면 안 됩니다
- 결과를 검증: 서브에이전트의 출력은 신뢰할 수 있지만, 중요한 결정은 직접 확인하세요
- 남용하지 않기: 단순한 파일 읽기나 검색은 직접 하는 게 빠릅니다. 복잡한 멀티스텝 작업에만 사용하세요
서브에이전트는 Claude Code의 가장 강력한 기능 중 하나입니다. 적절히 활용하면 혼자서도 팀 단위의 생산성을 낼 수 있습니다. 다음에 복잡한 개발 작업이 생기면, "이걸 여러 에이전트에게 나눠줄 수 없을까?"라고 먼저 생각해보세요. 분명 더 효율적인 방법이 보일 것입니다.
