Claude Code 멀티 에이전트 완전 정리 — 설정 방법·호출법·실전 시나리오 총정리 2026
파트1에서 설치, 파트2에서 CLAUDE.md까지 써보고 나니 Claude Code가 손에 조금씩 익기 시작했습니다. 그러다가 우연히, "서브에이전트"라는 기능을 알게 됐습니다. AI 팀원을 여러 명 만들어서 동시에 일을 시킬 수 있다는 개념이었습니다. 처음엔 "이게 나한테 필요한 수준의 기능인가?" 싶었습니다. 그냥 메인 세션 하나로 쓰면 되는 거 아닌가 하고요.
그런데 직접 서브에이전트 파일을 만들어보면서 생각이 바뀌었습니다. 처음에는 YAML 헤더가 붙은 마크다운 파일이라는 형식 자체가 낯설었습니다. 설정 파일을 어떻게 작성해야 하는지, 어디에 저장해야 하는지 감이 오지 않아서 한참 들여다봤습니다. 그런데 막상 파일을 하나 만들고 나니 구조가 생각보다 단순했습니다. 이름, 역할 설명, 사용할 도구 목록, 모델 선택. 이 네 가지가 전부였습니다.
처음 만든 에이전트는 코드 리뷰 전담이었습니다. "@code-reviewer 방금 수정한 파일 리뷰해줘"라고 입력했더니 메인 세션의 흐름을 방해하지 않고 독립적으로 리뷰 결과를 가져왔습니다. 같은 Claude인데 역할이 분리되어 있으니 결과물의 집중도가 달랐습니다. 그래서 이 글은 에이전트 파일을 처음 만드는 분들이 저처럼 형식 때문에 막히지 않도록 처음부터 끝까지 실례를 들어 정리해서 만든 초보자 가이드입니다.
이 글은 그 방법을 처음부터 재현해 보고자 합니다. Claude Code의 서브에이전트(Subagent)가 무엇인지, 어떻게 만들고, 어떻게 여러 에이전트에게 동시에 일을 분배하는지를 실제 예시와 함께 단계별로 설명해 보겠습니다!
Claude Code에서 일반적으로 사용하는 메인 세션은 "만능 개발자 한 명"에 비유할 수 있습니다. 그런데 프로젝트가 복잡해질수록 한 명이 모든 일을 순서대로 처리하면 시간이 오래 걸리고, 이전 작업의 흔적이 컨텍스트에 쌓여 새 작업에 방해가 되는 경우가 많습니다.
서브에이전트(Subagent)는 Claude Code 안에 있는 "작은 전문 AI 팀원들"입니다. 각각의 서브에이전트는 특정 역할에 맞게 프롬프트·사용 가능한 도구·AI 모델을 따로 설정해 두고, 필요할 때 호출해서 쓰는 구조입니다. (출처: code.claude.com 공식 서브에이전트 문서) 예를 들어 이런 팀을 꾸릴 수 있습니다.
| 에이전트 이름 | 역할 | 사용 모델 | 허용 도구 |
|---|---|---|---|
| code-reviewer | 코드 품질·보안 리뷰 | Sonnet | Read, Bash(git diff) |
| bug-hunter | 버그 탐지·수정 | Sonnet | Read, Edit, Bash |
| explorer | 코드베이스 탐색만 담당 | Haiku (빠르고 저렴) | Read, Glob, Grep 전용 |
| test-runner | 테스트 실행·커버리지 확인 | Sonnet | Bash(npm run test:*) |
(출처: tech.hyperithm.com·tilnote.io, 2026년 기준 실전 예시. 에이전트 구성은 프로젝트에 따라 자유롭게 변경 가능.)
서브에이전트의 핵심 장점은 세 가지입니다. 첫째, 각 에이전트는 독립된 컨텍스트에서 작업하므로 메인 대화의 흐름이 복잡해지지 않습니다. 둘째, 여러 에이전트가 동시에 병렬로 작업할 수 있어 시간을 대폭 단축합니다. 셋째, 위험한 작업(파일 삭제, 배포 명령 등)은 권한이 제한된 에이전트에게만 맡겨 안전하게 운영할 수 있습니다.
서브에이전트는 YAML 헤더(frontmatter)가 붙은 Markdown 파일로 정의됩니다. 파일 하나가 팀원 한 명입니다. 저장 위치에 따라 적용 범위가 달라집니다. (출처: code.claude.com 공식 서브에이전트 문서)
| 저장 위치 | 적용 범위 | 팀 공유 여부 |
|---|---|---|
| .claude/agents/ | 현재 프로젝트 전용 | Git 커밋 시 팀 공유 가능 |
| ~/.claude/agents/ | 내 PC 모든 프로젝트 | 개인 전용 (공유 안 됨) |
방법 1 — 대화형으로 만들기 (가장 쉬운 방법)
Claude Code를 실행한 상태에서 아래 명령어를 입력하면 대화형 마법사가 실행됩니다.
마법사가 에이전트 이름, 역할 설명, 사용할 모델(Haiku/Sonnet/Opus), 허용할 도구, 배경색(UI 구분용), 메모리 범위를 순서대로 물어봅니다. 답변을 입력하면 에이전트 파일이 자동 생성됩니다. 저장 후 Enter를 누르면 즉시 사용 가능합니다.
방법 2 — 파일 직접 작성하기 (세밀한 설정 가능)
프로젝트 폴더에서 .claude/agents/ 폴더를 만들고 code-reviewer.md 파일을 생성합니다. 아래가 실제 작성 예시입니다.
name: code-reviewer
description: 코드 변경사항을 리뷰하고 품질 보고서를 작성합니다.
MUST BE USED for all code changes before commit.
model: claude-sonnet-4-6
tools:
- Read
- Bash(git diff:*)
- Bash(git log:*)
---
당신은 시니어 개발자 역할의 코드 리뷰어입니다.
git diff로 변경사항을 먼저 확인하고,
리뷰 결과를 아래 3가지 카테고리로 나눠 제공하세요.
🔴 Critical: 즉시 수정 필요한 보안·버그 문제
🟡 Warning: 성능·가독성 개선이 필요한 부분
🟢 Suggestion: 더 나은 코드를 위한 선택적 제안
(출처: tech.hyperithm.com·tilnote.io 실전 예시 기반 재구성, 2026년)
파일을 저장하면 즉시 에이전트가 활성화됩니다. 현재 등록된 모든 에이전트 목록을 보려면 터미널에서 claude agents를 실행하면 됩니다.
에이전트를 만들었다면 이제 실제로 사용할 차례입니다. 두 가지 호출 방법이 있어요.
방법 A — 자동 위임 (Claude가 알아서 선택)
Claude Code는 사용자의 요청과 각 에이전트의 description을 자동으로 비교해 적합한 에이전트를 선택합니다. 예를 들어 "코드 리뷰해줘"라고 입력하면 Claude가 code-reviewer 에이전트로 자동 위임합니다. 자동 위임을 더 확실하게 하고 싶다면 에이전트 파일의 description에 "MUST BE USED" 또는 "PROACTIVELY use" 같은 키워드를 포함하면 됩니다.
방법 B — 명시적 호출 (직접 에이전트 지목)
에이전트 이름 앞에 @를 붙여 직접 호출합니다. 중요하거나 민감한 작업은 이 방식을 권장합니다.
@code-reviewer 방금 수정한 auth.js 파일을 리뷰해줘
# 또는 이름만 언급해도 됨
test-runner 서브에이전트를 사용해 실패한 테스트를 고쳐줘
실전에서는 일상적인 작업은 자동 위임, 중요하고 민감한 작업(배포, 파일 삭제 등)은 명시적 호출을 혼합해서 쓰는 것이 가장 효율적입니다. (출처: tilnote.io, 2026년)
이제 도입부의 민준 씨 이야기로 돌아가 봅시다. 그는 아래 세 가지 에이전트를 프로젝트에 미리 설정해 두고 있었습니다.
.claude/agents/
├── code-reviewer.md # 코드 품질·보안 리뷰 담당
├── bug-hunter.md # 버그 탐색·수정 담당
└── feature-builder.md # 새 기능 구현 담당
Step 1 — 병렬 작업 지시
민준 씨는 Claude Code 메인 세션에 아래처럼 한 번에 지시했습니다.
1. @bug-hunter: src/ 폴더 전체에서 버그를 찾아 모두 수정해줘
2. @code-reviewer: 수정된 코드 전체를 리뷰하고 report.md 파일로 정리해줘
3. @feature-builder: CLAUDE.md에 정의된 스펙대로 결제 기능을 추가해줘
Claude Code 메인 세션은 이 요청을 받아 각 에이전트에게 작업을 위임합니다. 에이전트들은 독립된 세션에서 동시에 작업을 수행하고, 결과를 메인 세션으로 다시 전달합니다. (출처: tech.hyperithm.com, 2025년)
Step 2 — 컨텍스트 공유 (에이전트 간 소통)
서브에이전트들이 서로의 결과를 공유해야 할 때는 MD 파일을 중간 저장소로 활용합니다. bug-hunter가 버그 수정을 완료하면 bug-report.md에 결과를 저장하고, code-reviewer가 그 파일을 읽어 이어서 리뷰를 진행합니다. 서브에이전트는 다른 서브에이전트를 직접 생성할 수 없으므로, 이 파일 기반 컨텍스트 공유 방식이 실전에서 가장 안정적입니다. (출처: gpters.org·code.claude.com, 2025~2026년)
버그 수정 완료 후 반드시 bug-report.md에 아래 형식으로 기록하세요:
- 발견된 버그 위치 (파일명:라인)
- 수정 내용 요약
- 수정 전·후 코드 스니펫
Step 3 — 결과 통합 및 확인
모든 에이전트 작업이 완료되면 메인 세션에서 결과를 확인하고 통합합니다. 개발자 Sankalp의 사례에서는 이와 같은 방식으로 작업 시간을 50% 단축했습니다. (출처: devocean.sk.com, 2025년)
처음부터 모든 에이전트를 직접 만들 필요는 없습니다. Claude Code에는 기본 내장 에이전트가 이미 탑재되어 있습니다.
| 내장 에이전트 | 역할 | 특징 |
|---|---|---|
| general-purpose | 복잡한 다단계 작업 전반 | 광범위한 도구 권한, Sonnet 모델 |
| explorer | 코드베이스 탐색·분석만 | 읽기 전용, Haiku (빠르고 저렴) |
| plan | Plan Mode 시 계획 수립 | 실행 없이 계획·리서치 전용 |
(출처: code.claude.com 공식 서브에이전트 문서·tilnote.io, 2026년. 내장 에이전트 목록은 버전 업데이트에 따라 변경될 수 있음.)
처음 시작하는 분을 위한 3단계 추천 로드맵
1단계 (오늘): 내장 에이전트를 먼저 써보세요. "explorer 에이전트를 사용해 이 프로젝트 구조를 분석해줘"처럼 기본 에이전트를 호출해보는 것부터 시작합니다.
2단계 (이번 주): 가장 자주 반복하는 작업(예: 코드 리뷰, 테스트 실행) 하나만 골라 에이전트 파일을 직접 만들어보세요. /agents 마법사를 쓰면 5분 안에 완성됩니다.
3단계 (이번 달): 프로젝트에 맞는 에이전트 팀을 .claude/agents/에 구성하고 팀원들과 Git으로 공유해 표준화된 워크플로우를 만드세요.
초보자라면 처음부터 병렬 에이전트를 무리하게 구성하기보다, 한 번에 하나씩 단계별로 진행하면서 각 에이전트 결과를 모니터링하는 습관을 먼저 들이세요. 에이전트가 예상치 못한 방향으로 진행할 때는 Esc 키로 즉시 중단할 수 있으니 너무 걱정하지 않으셔도 됩니다!
민준 씨의 이야기는 꾸며낸 것이 아닙니다. 에이전트 하나가 일하는 동안 나는 다른 에이전트의 결과를 검토하고, 또 다른 에이전트에게 다음 작업을 지시합니다. "혼자 일하지만 혼자가 아닌" 이 새로운 개발 방식이 지금 가장 빠르게 퍼지고 있는 이유입니다. 오늘 바로 /agents 명령어 하나로 첫 번째 팀원을 만들어 보세요.😄
Q. 서브에이전트가 실수로 중요한 파일을 수정하거나 삭제할 수 있나요?
A. 에이전트 파일의 tools 항목에 허용할 도구만 명시하면 됩니다. 예를 들어 탐색 전용 에이전트에는 Read, Glob, Grep만 허용하고 Edit, Bash는 제외하면 해당 에이전트는 어떤 파일도 수정할 수 없습니다. 위험한 도구는 반드시 필요한 에이전트에만 제한적으로 부여하는 것이 핵심입니다.
Q. 서브에이전트를 많이 만들면 비용이 크게 늘어나지 않나요?
A. 오히려 잘 설계된 에이전트 시스템은 비용을 줄이는 데 도움이 됩니다. 탐색처럼 단순한 작업은 저렴한 Haiku 모델을 쓰는 explorer 에이전트에게 맡기고, 복잡한 구현만 Sonnet 이상의 모델을 사용하는 에이전트에게 위임하면 됩니다. 또한 각 에이전트가 독립된 컨텍스트를 가지므로 메인 세션의 컨텍스트가 불필요하게 쌓이지 않아 토큰 낭비도 줄어드니 더 이득입니다.
Q. 팀 프로젝트에서 서브에이전트를 팀원 모두와 공유하려면 어떻게 하나요?
A. 에이전트 파일을 프로젝트의 .claude/agents/ 폴더에 저장하고 Git에 커밋하면 됩니다. 팀원 모두가 저장소를 pull하면 동일한 에이전트 구성을 즉시 사용할 수 있습니다. 이 방식으로 코드 리뷰 기준, 테스트 실행 방법, 배포 절차를 에이전트로 표준화해 팀 전체의 작업 품질을 일관되게 유지할 수 있습니다.
— Jin Jin
댓글
댓글 쓰기