클로드 코드(Claude Code)를 사용하다 보면 작업이 길어질수록 대화창이 무거워지고, 응답 속도가 느려지는 경험을 하게 됩니다. 이런 문제를 해결하기 위해 등장한 기능이 바로 서브에이전트(Subagents) 입니다. 이 글에서는 서브에이전트가 무엇인지, 왜 필요한지, 그리고 어떻게 사용하는지를 누구나 이해할 수 있는 쉬운 예제와 함께 정리해 드립니다.
참고로 이 글의 모든 내용은 Anthropic 공식 클로드 코드 문서를 기반으로 작성되었습니다.
1. 서브에이전트란 무엇인가요?
서브에이전트는 특정 작업을 전담하는 별도의 AI 보조 일꾼입니다. 메인 클로드(주 대화창)가 큰 프로젝트의 총괄 매니저라면, 서브에이전트는 매니저가 특정 업무를 맡기는 전문 직원이라고 생각하시면 됩니다.
핵심 특징은 다음과 같습니다.
- 독립된 대화창(컨텍스트 윈도우)에서 작업합니다. 즉, 서브에이전트가 처리한 내용은 메인 대화창을 어지럽히지 않습니다.
- 자체 시스템 프롬프트를 가지고 있어서, 특정 분야의 전문가처럼 행동하도록 설정할 수 있습니다.
- 사용 가능한 도구를 제한할 수 있어서, 보안과 안전성을 높일 수 있습니다.
- 작업이 끝나면 결과 요약만 메인 대화창으로 돌려보냅니다.
쉬운 비유: 회사의 팀장과 팀원
서브에이전트를 이해하는 가장 쉬운 방법은 회사를 떠올려 보시는 것입니다.
여러분이 팀장이라고 가정해 봅시다. 신규 기능을 개발해야 하는데, 그 전에 "기존 인증 시스템이 어떻게 동작하는지" 먼저 파악해야 합니다. 만약 팀장이 직접 100개의 코드 파일을 다 읽으면 머릿속이 너무 복잡해져서 정작 중요한 설계 작업에 집중할 수 없겠죠.
이때 팀장은 신입 사원에게 "기존 인증 시스템을 분석해서 핵심 내용만 한 페이지로 요약해 와" 라고 지시합니다. 신입 사원은 자기 자리에서 100개 파일을 모두 분석한 뒤, 핵심 요약만 들고 옵니다. 팀장은 100개 파일을 직접 보지 않고도 필요한 정보를 얻을 수 있습니다.
이 신입 사원이 바로 서브에이전트입니다.
2. 왜 서브에이전트가 필요한가요?
공식 문서에 따르면 서브에이전트는 다음과 같은 다섯 가지 이점을 제공합니다.
첫째, 컨텍스트 보존입니다. 탐색이나 조사 작업을 메인 대화창 밖에서 처리해서 메인 대화창을 깔끔하게 유지합니다.
둘째, 제약 조건 강제입니다. 서브에이전트가 사용할 수 있는 도구를 제한해서 의도하지 않은 작업을 방지합니다.
셋째, 설정 재사용입니다. 한 번 만든 서브에이전트를 여러 프로젝트에서 반복해서 사용할 수 있습니다.
넷째, 전문화된 행동입니다. 특정 도메인에 집중된 시스템 프롬프트로 해당 분야의 전문가처럼 동작합니다.
다섯째, 비용 절감입니다. 단순한 작업은 더 빠르고 저렴한 모델(예: Haiku)로 라우팅할 수 있습니다.
3. 클로드 코드에 기본 내장된 서브에이전트
클로드 코드를 설치하면 별도 설정 없이도 사용할 수 있는 내장 서브에이전트가 있습니다. 클로드가 상황에 맞게 자동으로 호출합니다.
Explore (탐색): 코드베이스를 검색하고 분석하는 데 최적화된 빠른 읽기 전용 에이전트입니다. Haiku 모델을 사용해서 속도가 빠르며, Write와 Edit 도구는 사용할 수 없습니다.
Plan (계획): 플랜 모드에서 코드베이스를 조사할 때 사용되는 에이전트입니다. 메인 대화의 모델을 그대로 상속받으며, 읽기 전용입니다.
General-purpose (범용): 탐색과 수정을 모두 필요로 하는 복잡한 다단계 작업에 사용됩니다. 모든 도구에 접근할 수 있습니다.
이 외에도 statusline-setup, Claude Code Guide 같은 보조 에이전트가 자동으로 호출되어 동작합니다.
4. 가장 쉬운 예제: 코드 리뷰 서브에이전트 만들기
이제 실제 예제를 살펴보겠습니다. 가장 흔하게 사용되는 코드 리뷰 서브에이전트입니다.
4-1. 서브에이전트 파일의 기본 구조
서브에이전트는 YAML 프론트매터(frontmatter) + 마크다운 본문 형태의 파일로 정의됩니다. 파일 확장자는 .md입니다.
---
name: code-reviewer
description: 코드 품질, 보안, 유지보수성을 검토하는 전문가. 코드 작성/수정 직후 적극적으로 사용할 것.
tools: Read, Grep, Glob, Bash
model: inherit
---
당신은 높은 코드 품질과 보안 기준을 보장하는 시니어 코드 리뷰어입니다.
호출되었을 때:
1. git diff를 실행하여 최근 변경 사항을 확인합니다
2. 수정된 파일에 집중합니다
3. 즉시 리뷰를 시작합니다
리뷰 체크리스트:
- 코드가 명확하고 가독성이 좋은가
- 함수와 변수의 이름이 적절한가
- 중복된 코드는 없는가
- 적절한 에러 처리가 되어 있는가
- 노출된 비밀키나 API 키는 없는가
피드백은 우선순위별로 구성합니다:
- 치명적 문제 (반드시 수정)
- 경고 (수정 권장)
- 제안 (개선 고려)
4-2. 각 항목이 뜻하는 것
상단의 ---로 감싸진 부분이 프론트매터이고, 메타데이터를 담습니다.
name: 서브에이전트의 고유 이름입니다. 소문자와 하이픈만 사용 가능합니다. (필수)description: 클로드가 "언제 이 서브에이전트를 호출해야 할지" 판단하는 기준입니다. (필수)tools: 사용 가능한 도구 목록입니다. 여기서는 읽기 도구만 허용해서 안전하게 만들었습니다.model: 사용할 모델입니다.sonnet,opus,haiku,inherit(메인과 동일) 중 선택할 수 있습니다.
--- 아래의 본문은 시스템 프롬프트입니다. 서브에이전트가 어떻게 행동해야 할지를 자세히 알려주는 부분입니다.
4-3. 어디에 저장하나요?
저장 위치에 따라 적용 범위가 달라집니다.
| 저장 위치 | 적용 범위 |
|---|---|
.claude/agents/ |
현재 프로젝트에서만 사용 |
~/.claude/agents/ |
내 컴퓨터의 모든 프로젝트에서 사용 |
팀과 공유하고 싶다면 .claude/agents/에 저장하고 git에 커밋하시면 됩니다.
5. 서브에이전트를 만드는 가장 쉬운 방법: /agents 명령어
직접 파일을 만드는 게 부담스러우시다면, 클로드 코드에서 제공하는 대화형 인터페이스를 사용하시면 됩니다.
클로드 코드 안에서 다음 명령어를 입력합니다.
/agents
그러면 탭 형태의 인터페이스가 열리고, 다음 단계로 서브에이전트를 만들 수 있습니다.
- Library 탭으로 이동 후 Create new agent 선택
- 저장 범위 선택 (Personal 또는 Project)
- Generate with Claude를 선택해서 클로드가 자동으로 식별자, 설명, 시스템 프롬프트를 생성하도록 합니다
- 사용할 도구 선택 (예: 읽기 전용 도구만 허용)
- 모델 선택
- 색상 선택 (UI에서 어떤 서브에이전트가 동작 중인지 식별하는 용도)
- 메모리 설정 (선택 사항)
- 저장 후 즉시 사용 가능
저장한 뒤에는 다음과 같이 자연어로 호출할 수 있습니다.
code-reviewer 에이전트를 사용해서 이 프로젝트의 개선점을 알려줘
6. 일상 업무로 보는 실제 활용 예제 3가지
이제 서브에이전트가 실제로 어떻게 도움이 되는지 세 가지 시나리오로 살펴보겠습니다.
예제 1: 테스트 실행 결과 정리
테스트 스위트를 돌리면 보통 수백, 수천 줄의 출력이 쏟아집니다. 메인 대화창에서 직접 돌리면 컨텍스트가 폭발적으로 차오릅니다.
이때는 다음과 같이 요청하면 됩니다.
서브에이전트를 사용해서 테스트 스위트를 실행하고, 실패한 테스트와 그 에러 메시지만 보고해줘
서브에이전트가 자기 대화창에서 모든 출력을 받아서 처리하고, 메인 대화창에는 실패 항목 요약만 돌아옵니다.
예제 2: 병렬로 여러 모듈 조사하기
큰 프로젝트에서 여러 모듈을 동시에 파악해야 할 때가 있습니다.
인증, 데이터베이스, API 모듈을 각각 별도의 서브에이전트로 병렬 조사해줘
세 서브에이전트가 동시에 자기 영역을 분석하고, 각자 요약된 결과를 가져옵니다. 한 번에 직렬로 조사하는 것보다 훨씬 빠릅니다.
예제 3: 다단계 워크플로우 체이닝
여러 단계로 이어지는 작업도 서브에이전트를 연결해서 처리할 수 있습니다.
code-reviewer 서브에이전트로 성능 이슈를 찾고, 그 다음 optimizer 서브에이전트로 그 이슈들을 수정해줘
각 서브에이전트가 자기 임무에만 집중하므로 결과의 품질이 높아집니다.
7. 서브에이전트를 명시적으로 호출하는 세 가지 방법
자동 위임에만 의존하기보다, 직접 호출하고 싶을 때가 있습니다. 공식 문서에서는 세 가지 방법을 제시합니다.
자연어 호출: 프롬프트에 서브에이전트 이름을 그냥 적어주시면 됩니다. 클로드가 위임 여부를 판단합니다.
code-reviewer 서브에이전트로 최근 변경 사항을 검토해줘
@-멘션: @를 입력하면 사용 가능한 서브에이전트 목록이 나타납니다. 이렇게 호출하면 반드시 그 서브에이전트가 실행됩니다.
@"code-reviewer (agent)" 인증 관련 변경 사항을 살펴봐줘
세션 전체에 적용: 클로드 코드를 시작할 때 --agent 플래그를 사용하면 세션 전체가 해당 서브에이전트의 시스템 프롬프트로 동작합니다.
claude --agent code-reviewer
8. 서브에이전트를 사용해야 할 때 vs 사용하지 말아야 할 때
서브에이전트가 만능은 아닙니다. 공식 문서는 명확한 가이드를 제공합니다.
메인 대화창을 사용해야 할 때:
- 잦은 상호작용과 반복적 다듬기가 필요할 때
- 여러 단계가 같은 컨텍스트를 공유할 때 (계획 → 구현 → 테스트)
- 빠르고 작은 변경을 할 때
- 응답 속도가 중요할 때 (서브에이전트는 컨텍스트를 새로 모으느라 시간이 걸립니다)
서브에이전트를 사용해야 할 때:
- 작업이 메인 컨텍스트에 굳이 필요 없는 장황한 출력을 만들 때
- 특정 도구 제한이나 권한을 강제하고 싶을 때
- 작업이 독립적이고 요약만 돌려받으면 될 때
또한, 서브에이전트는 다른 서브에이전트를 다시 호출할 수 없다는 제한이 있습니다. 중첩된 위임이 필요하다면 Skills 기능을 사용하거나, 메인 대화창에서 서브에이전트를 차례로 호출하는 방식을 써야 합니다.
9. 서브에이전트의 권한과 안전성
서브에이전트의 강력한 점 중 하나는 권한을 세밀하게 제어할 수 있다는 것입니다.
tools 필드로 사용 가능한 도구를 화이트리스트로 지정할 수도 있고, disallowedTools 필드로 특정 도구만 차단할 수도 있습니다. 예를 들어 다음과 같이 설정하면 파일 쓰기를 제외한 모든 도구를 사용할 수 있습니다.
---
name: no-writes
description: Write와 Edit를 제외한 모든 도구 상속
disallowedTools: Write, Edit
---
또한 permissionMode 필드로 권한 프롬프트 동작 방식도 제어할 수 있습니다. default(표준 확인), acceptEdits(편집 자동 승인), dontAsk(자동 거부), plan(읽기 전용 탐색) 등 다양한 모드가 있습니다.
10. 함께 알아두면 좋은 관련 기능
서브에이전트와 함께 보면 시너지가 큰 기능들입니다.
플러그인(Plugins): 서브에이전트를 패키지화해서 팀이나 프로젝트 간에 공유할 수 있습니다.
MCP 서버: 서브에이전트에 외부 도구나 데이터 접근 권한을 부여할 수 있습니다.
훅(Hooks): 서브에이전트의 도구 실행 전후에 자동으로 실행되는 스크립트를 설정할 수 있습니다.
스킬(Skills): 서브에이전트가 시작할 때 미리 도메인 지식을 주입할 수 있습니다.
에이전트 SDK: 클로드 코드를 프로그래밍 방식으로 사용할 때 서브에이전트를 정의하는 방법입니다.
마치며
서브에이전트는 클로드 코드를 단순한 AI 비서에서 체계적인 개발 시스템으로 끌어올리는 핵심 기능입니다. 처음에는 어렵게 느껴질 수 있지만, /agents 명령어로 대화형 생성을 한 번 해보시면 곧 익숙해지실 것입니다.
핵심 요약은 다음과 같습니다.
- 서브에이전트는 독립된 작업 공간을 가진 전문 일꾼입니다.
- 컨텍스트 절약, 권한 제어, 재사용성, 전문화, 비용 절감이라는 다섯 가지 이점이 있습니다.
- 마크다운 파일에 YAML 프론트매터를 넣어 정의합니다.
/agents명령어로 손쉽게 만들 수 있습니다.- 자동 위임, 자연어 호출, @-멘션,
--agent플래그 등 다양한 방법으로 호출할 수 있습니다.
더 자세한 정보는 Anthropic 공식 문서에서 확인하실 수 있습니다.