클로드 코드 서브에이전트(Subagent): 조사는 맡기고 요약만 받기
서브에이전트(Subagent)는 Claude Code에서 메인 대화의 Claude가 맡긴 일을 자기 컨텍스트에서 처리하고 요약만 돌려주는 보조 AI 에이전트입니다. 자기 지침, 쓸 수 있는 도구, 권한을 따로 가지며 마크다운 파일 하나로 직접 만들 수 있습니다.
같은 말:SubagentsSubagent서브에이전트서브 에이전트서브에이전트란클로드 서브에이전트클로드 코드 서브에이전트클로드코드 서브에이전트claude subagentsclaude code subagent서브에이전트 사용법서브에이전트 병렬Explore 에이전트.claude/agents보조 에이전트
회의록 40개처럼 파일이 많은 자료를 Claude Code에 읽혀 정리하게 하면, Claude가 읽은 내용과 검색 결과가 대화에 쌓여 대화가 금세 길어집니다. Claude Code 공식 문서는 이럴 때 쓰는 기능으로 서브에이전트를 소개합니다.
서브에이전트(Subagent)는 Claude Code에서 메인 대화의 Claude가 맡긴 일을 자기 컨텍스트에서 처리하고 요약만 돌려주는 보조 AI 에이전트입니다. 메인 대화는 사용자와 Claude가 지금 주고받는 대화이고, 컨텍스트는 Claude가 그 대화에서 참고하는 내용 전체입니다. 이 글은 2026년 10월 24일 기준 Claude Code 공식 문서를 근거로, 터미널에서 실행한 Claude Code를 기준으로 씁니다.
클로드 코드 서브에이전트(Subagent)
자료 조사는 따로 맡기고
메인 대화에는
요약만 돌려받습니다
회의록 40개처럼 파일이 많은 자료를 Claude Code에 읽혀 정리하게 하면, Claude가 읽은 내용이 대화에 쌓여 대화가 금세 길어집니다.
이 글은 같은 조사를 메인 대화에서 직접 할 때와 서브에이전트에게 맡길 때를 나란히 놓고 설명합니다.
Claude Code에 보낸 요청회의록 40개에서 거래처 요청만 표로 뽑아 줘
조사를 처리할 방식 고르기
편집장 책상(메인 대화)
아직 읽지 않은 회의록 40개
기자 수첩(서브에이전트의 컨텍스트)
아직 처리 방식을 고르지 않아 회의록 40개가 읽지 않은 채 편집장 책상에 놓여 있습니다.
서브에이전트(Subagent)는 Claude Code에서 메인 대화의 Claude가 맡긴 일을 자기 컨텍스트에서 처리하고 요약만 돌려주는 보조 AI 에이전트입니다.
공식 문서는 다시 보지 않을 검색 결과, 로그, 파일 내용이 메인 대화를 채울 것 같을 때 서브에이전트를 쓰라고 안내합니다.
컨텍스트는 Claude가 답을 만들 때 참고하는 대화와 자료 전체입니다. 이 그림에서 편집장 책상은 메인 대화(사용자와 Claude가 지금 주고받는 대화)를, 주황 기자 수첩은 서브에이전트의 컨텍스트를 뜻합니다. 회의록 40개, 거래처와 요청 표, 책상 위 종이의 양은 이 글에서 만든 가상 예시입니다.
일반 서브에이전트는
대화 기록을 물려받지 않고
Claude가 써 준 작업 메시지로 시작합니다
기자는 편집장 책상의 자료를 모두 들고 나가지 않고, 취재 지시서와 정해진 몇 가지만 가방에 넣어 나갑니다. 이 장면은 대화 전체를 물려받는 포크(fork)를 뺀 일반 서브에이전트를 기준으로 합니다.
책상 위 자료를 눌러 서브에이전트가 처음 받는 것과 받지 못하는 것을 봅니다.
메인 대화에 있는 자료 고르기
기자 가방(서브에이전트에게 가는 것)
책상에 남는 것(서브에이전트에게 가지 않는 것)
책상 위 자료를 누르면 그 자료가 서브에이전트에게 가는지와 조건이 이 결과 카드에 적힙니다.
받는 것과 받지 못하는 것은 2026년 10월 24일 Claude Code 서브에이전트 문서(What loads at startup)를 따릅니다. 이 그림에서 기자 가방은 서브에이전트가 처음 받는 것을, 책상에 남는 자료는 받지 못하는 것을 뜻합니다.
Claude Code에는
이미 들어 있는 서브에이전트가 있습니다
편집국에 상주 기자가 있듯, Claude Code에는 직접 만들지 않아도 Claude가 알맞은 때에 스스로 일을 맡기는 서브에이전트가 들어 있습니다.
기자증을 눌러 대표적인 세 가지가 하는 일과 쓸 수 있는 도구를 봅니다.
기본 제공 서브에이전트 고르기
기자증을 누르면 그 서브에이전트가 하는 일, 쓸 수 있는 도구, Claude가 맡기는 때가 이 결과 카드에 적힙니다.
이름과 설명은 2026년 10월 24일 Claude Code 서브에이전트 문서(Built-in subagents)를 따릅니다. Explore와 Plan은 빠르게 조사하도록 CLAUDE.md 없이 시작합니다. 이 그림에서 기자증 한 장은 서브에이전트 하나를 뜻합니다.
자주 맡기는 조사는
서브에이전트 파일 하나로 만들어 둡니다
같은 지시로 같은 종류의 일을 자주 맡긴다면, 그 지시를 서브에이전트 파일로 저장해 두고 다시 부를 수 있습니다.
다음 줄 채우기 버튼을 눌러 회의록 조사용 서브에이전트 파일을 한 줄씩 채우고, 기자증 앞면이 어떻게 채워지는지 봅니다.
프로젝트 폴더의 .claude/agents/minutes-researcher.md
기자증 앞면
- 이름
- 맡기는 때
- 쓸 수 있는 도구
- 모델
- 업무 수칙(뒷면)
다음 줄 채우기 버튼을 누르면 파일의 첫 줄이 채워지고, 그 줄이 하는 일이 이 결과 카드에 적힙니다.
필드 이름과 뜻은 2026년 10월 24일 서브에이전트 문서(Frontmatter reference)를 따릅니다. minutes-researcher라는 이름과 본문은 이 글에서 만든 가상 예시입니다. 이 그림에서 기자증은 서브에이전트 파일을, 도장은 tools로 정한 도구 범위를 뜻합니다.
서브에이전트를 부르는 방법은
세 가지입니다
서브에이전트는 Claude가 스스로 골라 일을 맡기기도 하고, 사용자가 요청에 이름을 적거나 목록에서 골라 맡기기도 합니다.
방법을 눌러 Claude Code 입력창에 무엇을 쓰고, 대화 기록에 어떤 줄이 보이는지 봅니다.
부르는 방법 고르기
터미널에서 실행한 Claude Code
>
부르는 방법은 2026년 10월 24일 서브에이전트 문서(Invoke subagents explicitly)를 따릅니다. 위임 줄의 형식(서브에이전트 이름 뒤 괄호에 짧은 작업 설명)은 공식 예시 code-improver(Suggest code improvements)와 같고, 괄호 안 문구는 Claude가 쓰는 것이라 이 글의 문구는 가상 예시입니다.
서로 기다리지 않는 조사는 동시에 맡기고,
앞 결과가 필요한 검수는 차례로 맡깁니다
편집국 외근 표시판에는 지금 밖에 나가 있는 기자의 이름표가 걸립니다. 공식 문서는 조사끼리 서로의 결과를 기다리지 않을 때 여러 서브에이전트를 동시에 쓰라고 안내합니다.
일감 카드를 눌러 그 일을 동시에 맡길지, 앞 일이 끝난 뒤 맡길지, 메인 대화에서 직접 할지 봅니다.
맡길 일 고르기
외근 중(동시에 실행)
대기(앞 일이 끝난 뒤)
편집장 책상(메인 대화에서 직접)
판정 기준은 2026년 10월 24일 서브에이전트 문서의 Run parallel research, Chain subagents, Choose between subagents and main conversation 절과 모범 사례 문서입니다. 기본 설정에서 실행 중인 서브에이전트가 20개에 이르면 더 띄울 수 없습니다. 이 그림에서 외근 중 칸의 이름표는 동시에 실행되는 서브에이전트를, 대기 칸은 앞 일이 끝난 뒤 맡길 일을, 편집장 책상 칸은 메인 대화에서 직접 할 일을 뜻합니다. 일감은 가상 예시입니다.
클로드 코드 서브에이전트를 정리하면 이렇습니다
- 1
서브에이전트는 메인 대화의 Claude가 맡긴 일을 자기 컨텍스트에서 처리하고 요약만 돌려주는 보조 AI 에이전트입니다. 다시 보지 않을 검색 결과와 파일 내용이 메인 대화를 채우지 않습니다.
- 2
포크가 아닌 서브에이전트는 메인 대화의 기록을 물려받지 않고 Claude가 써 준 작업 메시지로 시작하므로, 꼭 지킬 조건은 맡기는 요청에 다시 적습니다.
- 3
Explore, Plan, General-purpose가 기본으로 들어 있고, 직접 만들 때는
.claude/agents/폴더에 name과 description을 적은 마크다운 파일을 둡니다. - 4
Claude가 description을 보고 스스로 맡기거나, 사용자가 요청에 이름을 적거나
@로 골라 맡깁니다. 반드시 그 서브에이전트에게 맡기려면 사용자가@로 고릅니다. - 5
서로의 결과를 기다리지 않는 조사는 동시에 맡기고, 앞 결과가 필요한 검수는 조사가 끝난 뒤 차례로 맡깁니다. 서브에이전트가 보낸 요청도 메인 대화와 같은 사용량 한도에서 차감됩니다.
서브에이전트(Subagent)란: 맡긴 일을 따로 처리하고 요약만 돌려주는 보조 에이전트
신문사 편집장은 기사에 쓸 자료를 직접 다 읽지 않습니다. 기자에게 취재 지시서를 건네 내보내고, 기자는 자기 수첩에 취재 내용을 적은 뒤 돌아와 편집장 책상에 기사 메모 한 장을 올립니다. Claude Code의 서브에이전트도 메인 대화의 Claude가 맡긴 일을 자기 컨텍스트에서 처리하고, 메인 대화에는 정리한 결과만 돌려줍니다.
공식 문서는 서브에이전트를 특정한 종류의 일을 맡는 전문 AI 보조로 설명하고, 서브에이전트마다 자기 컨텍스트 창, 자기 시스템 프롬프트(일을 시작할 때 먼저 읽는 기본 지침), 쓸 수 있는 도구, 권한을 따로 가진다고 적습니다. Claude가 요청에 맞는 서브에이전트를 찾으면 그 서브에이전트에게 일을 넘기고, 서브에이전트는 따로 일한 뒤 결과를 돌려줍니다. 서브에이전트는 한 세션(claude를 실행한 뒤 끝낼 때까지 이어지는 한 번의 작업) 안에서 동작하는 기능입니다.
| 같은 요청 "회의록 40개에서 거래처 요청만 표로 뽑아 줘" | 메인 대화에서 직접 읽을 때 | 서브에이전트에게 맡길 때 |
|---|---|---|
| 회의록을 읽는 쪽 | 메인 대화의 Claude | 서브에이전트 |
| 메인 대화에 남는 것 | 회의록 40개의 내용, 검색 결과, 결과 표 | Claude가 쓴 작업 메시지와 돌아온 결과 표 |
| 사용량 | 메인 대화의 요청만 차감됩니다 | 서브에이전트의 요청도 같은 한도에서 차감됩니다 |
위 표의 회의록과 요청은 이 글에서 만든 가상 예시입니다.
서브에이전트를 쓰는 이유와 드는 비용
공식 문서가 꼽는 서브에이전트의 쓸모는 다섯 가지입니다. 찾아본 내용을 메인 대화 밖에 두어 컨텍스트를 아끼고, 쓸 수 있는 도구를 제한하고, 한 번 만든 설정을 여러 프로젝트에서 다시 쓰고, 지침을 좁혀 한 가지 일에 맞추고, Haiku처럼 빠르고 저렴한 모델에 일을 보내 비용을 조절할 수 있습니다.
다섯 가지 가운데 컨텍스트를 아끼는 쓸모는 파일이 많은 자료를 다룰 때 나타납니다. 회의록, 견적서, 보고서 폴더처럼 파일이 많은 자료를 Claude가 직접 읽으면, 다시 보지 않을 파일 내용이 메인 대화에 남아 컨텍스트를 차지합니다. 서브에이전트에게 맡기면 파일 내용은 서브에이전트 쪽에 남고 메인 대화에는 요약만 돌아오므로, 이어서 표를 고치거나 다음 일을 시킬 때 메인 대화가 덜 찬 상태로 시작합니다.
대신 서브에이전트는 자기 요청을 따로 보내고, 그 요청은 메인 대화와 같은 사용량 한도에서 차감됩니다. 공식 문서는 자세한 결과를 돌려주는 서브에이전트를 여럿 돌리면 돌아온 결과가 메인 대화의 컨텍스트를 크게 차지할 수 있고, 각 서브에이전트도 실행하는 동안 자기 토큰(AI가 글을 읽고 쓰는 단위)을 쓴다고 경고합니다. 짧은 질문 하나나 파일 하나를 고치는 일은 메인 대화에서 바로 하는 편이 낫습니다. 사용량 한도는 클로드 코드 플랜과 사용량 한도 수업에서 다룹니다.
서브에이전트가 처음 받는 것과 받지 못하는 것
포크(지금까지의 대화 전체를 물려받는 서브에이전트)가 아닌 일반 서브에이전트는 새 컨텍스트에서 시작합니다. 공식 문서에 따르면 서브에이전트는 메인 대화의 기록, 이미 부른 스킬, Claude가 이미 읽은 파일을 보지 못합니다. 메인 대화의 Claude가 맡길 일을 요약한 작업 메시지를 써서 건네고, 서브에이전트는 그 메시지로 일을 시작합니다.
| 구분 | 내용 |
|---|---|
| 처음 받는 것 | 자기 시스템 프롬프트와 작업 폴더 같은 기본 환경 정보, Claude가 쓴 작업 메시지, CLAUDE.md(기본 조사용 서브에이전트 Explore와 Plan은 받지 않음), Git 상태(지금 브랜치와 바뀐 파일 같은 버전 관리 정보, Explore와 Plan은 받지 않음), 서브에이전트 파일의 skills 필드에 적은 스킬의 전문 |
| 받지 못하는 것 | 메인 대화의 기록, Claude가 이미 읽은 파일 내용, 메인 대화의 자동 메모리, 출력 스타일(Output style, 답의 말투와 형식을 정하는 설정) |
CLAUDE.md는 Claude Code가 작업을 시작할 때 읽는 프로젝트 지침 파일이고, 자동 메모리(auto memory)는 사용자가 고쳐 준 점과 선호를 Claude가 스스로 적어 두는 기능입니다. 직접 만든 서브에이전트에 omitClaudeMd: true를 적으면 사용자와 프로젝트의 CLAUDE.md 없이 시작합니다.
서브에이전트는 메인 대화와 같은 작업 폴더에서 시작하므로 필요한 파일은 직접 열어 읽을 수 있습니다. 다만 "거래처 이름은 줄이지 말아 줘"처럼 메인 대화에서 말한 조건은 작업 메시지에 들어 있어야 서브에이전트에게 전달됩니다. 공식 문서는 서브에이전트가 꼭 지켜야 할 규칙을 맡기는 요청에 다시 적으라고 안내합니다.
포크(fork)는 대화 전체를 물려받는 서브에이전트입니다
포크는 새로 시작하지 않고 지금까지의 대화 전체를 물려받는 서브에이전트입니다. 메인 대화와 같은 시스템 프롬프트, 도구, 모델, 대화 기록을 보므로 상황을 다시 설명하지 않고 곁가지 일을 맡길 수 있습니다. 포크가 쓴 도구 기록은 메인 대화에 남지 않고 마지막 결과만 돌아옵니다.
공식 문서 기준으로 포크 모드는 기본으로 켜져 있어 Claude가 스스로 포크를 시작할 수 있습니다. 사용자가 직접 시작하려면 입력창 맨 앞에 /subtask와 할 일을 적습니다. 이 글의 다른 설명은 대화 기록을 물려받지 않는 일반 서브에이전트를 기준으로 합니다.
Claude Code에 기본으로 들어 있는 서브에이전트
Claude Code에는 직접 만들지 않아도 Claude가 알맞은 때에 스스로 쓰는 서브에이전트가 들어 있습니다. 2026년 10월 24일 공식 문서 기준 대표적인 세 가지는 아래와 같습니다.
| 이름 | 하는 일 | 쓸 수 있는 도구 |
|---|---|---|
| Explore | 파일을 찾고 검색해 분석하는 빠른 조사용 에이전트 | 읽기 전용 도구만 쓰고, 파일을 쓰는 Write와 고치는 Edit는 막혀 있음 |
| Plan | 플랜 모드에서 계획을 보여 주기 전에 필요한 내용을 모으는 조사 에이전트 | 읽기 전용 도구만 쓰고, Write와 Edit는 막혀 있음 |
| General-purpose | 찾아보기와 실제 작업이 함께 필요한 여러 단계 작업 | 서브에이전트가 쓸 수 있는 도구 전부 |
플랜 모드는 Claude가 파일을 고치기 전에 바꿀 계획을 먼저 보여 주고 승인을 받는 권한 모드이고, 플랜 모드 수업에서 다뤘습니다. 기본 제공 서브에이전트는 메인 대화의 권한 규칙을 물려받습니다. Explore와 Plan은 빠르고 저렴하게 조사하도록 CLAUDE.md와 Git 상태 없이 시작하므로, 이 둘이 조사할 때 지켜야 할 규칙은 요청에 직접 적습니다.
서브에이전트 만들기: .claude/agents 파일과 설정 필드
서브에이전트는 맨 위에 머리말(frontmatter)이 붙은 마크다운 파일 하나입니다. 머리말은 파일 맨 위에서 --- 줄 두 개 사이에 적는 설정 목록이고, 그 아래 본문은 서브에이전트의 시스템 프롬프트가 됩니다. 공식 문서는 같은 지시로 같은 종류의 일을 자꾸 맡길 때 서브에이전트를 직접 만들라고 안내합니다.
만드는 방법은 두 가지입니다. Claude Code에 만들어 달라고 요청하거나, 아래 폴더에 파일을 직접 씁니다. /agents 명령은 생성 화면을 열지 않고 이 두 방법을 안내하는 문구만 보여 줍니다.
| 저장 위치 | 쓰는 범위 |
|---|---|
프로젝트 폴더의 .claude/agents/ | 그 프로젝트에서만 씁니다 |
홈 폴더의 ~/.claude/agents/ | 내 컴퓨터의 모든 프로젝트에서 씁니다 |
두 폴더에 name이 같은 서브에이전트가 있으면 프로젝트 폴더의 것을 씁니다. 파일을 더하거나 고치면 Claude Code가 몇 초 안에 알아채고 다음 위임부터 반영합니다. 다만 세션을 시작할 때 없던 agents 폴더를 새로 만들었다면 Claude Code를 다시 시작해야 그 폴더를 읽습니다.
서브에이전트 파일에 적는 설정 필드
공식 문서에서 반드시 적어야 하는 필드는 name과 description 두 개입니다. 이 글에서 소개하는 필드는 아래와 같습니다.
| 필드 | 꼭 적는지 | 하는 일 |
|---|---|---|
name | 예 | 서브에이전트를 구별하는 이름. 파일 이름과 같지 않아도 됨 |
description | 예 | Claude Code가 언제 이 서브에이전트에게 일을 맡길지 판단하는 설명 |
tools | 아니요 | 쓸 수 있는 도구 목록. 적지 않으면 서브에이전트가 쓸 수 있는 도구를 모두 물려받음 |
disallowedTools | 아니요 | 물려받거나 tools에 적은 목록에서 뺄 도구 |
model | 아니요 | 쓸 모델. sonnet, opus, haiku, fable 같은 별칭이나 전체 모델 ID, 메인 대화와 같은 모델을 쓰는 inherit |
permissionMode | 아니요 | 파일을 고치거나 명령을 실행하기 전에 허락을 묻는 방식을 정하는 권한 모드 |
skills | 아니요 | 서브에이전트가 시작할 때 전문을 넣어 줄 스킬 |
maxTurns | 아니요 | 서브에이전트가 멈추기 전까지 이어 갈 수 있는 작업 횟수의 상한 |
memory | 아니요 | 서브에이전트가 세션을 넘어 기억을 쌓을 폴더의 범위(user, project, local) |
isolation | 아니요 | worktree로 정하면 임시 Git 워크트리(저장소를 따로 떼어 낸 작업용 사본)에서 실행 |
permissionMode를 적어도 메인 대화가 작업을 묻지 않고 실행하되 검토 모델이 안전 검사를 하는 auto 모드, 작업 폴더 안의 파일 수정을 묻지 않고 허용하는 acceptEdits, 몇 가지 예외를 빼고 권한 확인을 건너뛰는 bypassPermissions 가운데 하나이면 무시되고 서브에이전트는 메인 대화와 같은 모드로 일합니다. 메인 대화가 플랜 모드이면 서브에이전트도 플랜 모드에 머뭅니다. 지정한 값이 적용되는 것은 주로 메인 대화가 파일 읽기 말고는 작업마다 사용자에게 묻는 Manual 모드(설정 이름 default)일 때이며, 권한 모드의 값은 권한 모드 수업에서 다룹니다.
공식 문서의 예시는 아래와 같습니다. 코드 검토만 맡기므로 파일을 읽고 찾는 도구(Read, Glob, Grep)만 허용했습니다.
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---같은 형식으로 회의록 조사용 서브에이전트를 만들면 아래와 같습니다. 이 파일은 준이아빠블로그가 공식 필드로 만든 예시입니다.
---
name: minutes-researcher
description: 회의록 폴더에서 거래처, 요청한 일, 날짜를 찾아 표로 정리한다. 회의록 조사 요청에 쓴다.
tools: Read, Glob, Grep
model: inherit
---
요청받은 폴더의 회의록만 읽고 거래처, 요청한 일, 날짜를 표로 돌려준다.
파일을 고치지 않는다. 날짜를 찾지 못한 회의록은 표 아래에 파일 이름만 적는다.Read는 파일 내용을 읽고, Glob은 이름 규칙으로 파일을 찾고, Grep은 파일 내용에서 글자를 찾는 도구입니다. tools에 Write와 Edit가 없으므로 이 서브에이전트는 파일을 고치지 못합니다. 본문에 "파일을 고치지 않는다"라고 쓰는 것만으로는 막히지 않으므로, 읽기만 시킬 서브에이전트는 tools에 읽기 도구만 적습니다.
공식 문서는 서브에이전트마다 한 가지 일에 집중하게 만들고, description은 Claude가 여러 서브에이전트 가운데 하나를 바로 고를 수 있을 만큼 구체적으로 적으라고 안내합니다. 기본 제공을 뺀 서브에이전트들의 설명 합계가 15,000토큰을 넘으면 Claude Code가 시작할 때 경고를 보여 주므로, description은 짧게 쓰고 자세한 지시는 본문에 적습니다.
서브에이전트 사용법: 부르는 세 가지 방법
| 방법 | 입력 예 | 결과 |
|---|---|---|
| Claude가 알아서 맡기기 | 회의록 폴더에서 거래처 요청을 표로 뽑아 줘 | 요청과 description이 맞으면 Claude가 스스로 맡깁니다 |
| 요청에 이름 적기 | minutes-researcher 서브에이전트로 3분기 회의록을 조사해 줘 | Claude가 그 서브에이전트에게 맡길지 판단합니다 |
@를 쳐서 목록에서 고르기 | @"minutes-researcher (agent)" 3분기 회의록을 조사해 줘 | 그 요청 하나는 고른 서브에이전트가 반드시 맡습니다 |
@로 고를 때는 입력창에 @를 치고 나오는 목록에서 서브에이전트를 고릅니다. 목록에서 minutes-researcher를 고르면 입력창에 @"minutes-researcher (agent)"가 들어가고, 그 뒤에 요청을 이어 적습니다. 목록을 쓰지 않고 @agent-minutes-researcher를 직접 칠 수도 있습니다. 이렇게 직접 치는 동안 목록에는 서브에이전트 대신 파일이 보이지만, 메시지를 보내면 서브에이전트 지정으로 처리됩니다.
어느 방법이든 사용자의 메시지 전체는 메인 대화의 Claude에게 가고, Claude가 그 메시지를 바탕으로 작업 메시지를 써서 서브에이전트에게 건넵니다. 서브에이전트가 받는 것은 사용자가 쓴 문장이 아니라 Claude가 쓴 작업 메시지입니다.
실제로 맡겼는지는 대화 기록으로 봅니다. 위임은 code-improver(Suggest code improvements)처럼 서브에이전트 이름 뒤 괄호에 짧은 작업 설명이 붙은 줄로 나타납니다. Claude가 메인 대화에서 띄운 서브에이전트는 기본 설정에서 백그라운드로 실행되므로, 그동안 사용자는 메인 대화를 이어 갈 수 있고 결과는 끝난 뒤 알림으로 돌아옵니다. 백그라운드 서브에이전트가 허락이 필요한 일을 하면 그 질문은 메인 대화에 서브에이전트 이름과 함께 뜹니다. 지금 실행 중이거나 막 끝난 서브에이전트와 그 모델은 /tasks 명령으로 봅니다.
세션 전체를 한 서브에이전트로 일하게 하려면 터미널에서 claude --agent minutes-researcher처럼 실행합니다. 이때는 보조 작업자가 하나 더 생기는 것이 아니라, 메인 대화 자체가 그 서브에이전트의 지침, 도구 제한, 모델로 일합니다.
조사와 검수를 서로 다른 서브에이전트에게 나누기
조사한 서브에이전트에게 결과 검수까지 맡기면, 조사할 때 둔 가정을 다시 확인하지 않고 넘어갈 수 있습니다. Claude Code 모범 사례 문서는 검수를 새 서브에이전트 컨텍스트에서 하면 검수자가 결과를 만든 과정의 판단을 보지 않고 받은 결과와 기준만 본다고 설명하고, 일을 한 에이전트가 자기 결과를 채점하지 않게 하라고 권합니다.
앞의 minutes-researcher가 조사를 맡는다면, 검수는 아래처럼 원본과 결과를 대조하는 서브에이전트에게 따로 맡깁니다. 이 파일도 준이아빠블로그가 공식 필드로 만든 예시입니다.
---
name: minutes-reviewer
description: 지정한 원본 회의록과 결과 표를 대조해 다른 값과 빠진 줄을 보고한다. 표 검수 요청에 쓴다.
tools: Read, Glob, Grep
model: inherit
---
지정한 원본 회의록과 결과 표를 읽고, 값이 다르거나 빠진 줄을 목록으로 보고한다.
문제마다 파일 이름, 원본의 값, 표의 값을 함께 적는다.
확인하지 못한 항목은 확인하지 못했다고 적고, 파일을 고치지 않는다.별도 컨텍스트에서 검수해도 결과가 반드시 맞다는 보장은 아닙니다. 두 서브에이전트가 같은 실수를 할 수 있으므로, 검수 보고에 나온 값은 원본 파일을 직접 열어 대조합니다. 검수 구조를 더 깊게 설계하는 방법은 에이전트 검수와 평가 수업에서 다룹니다.
동시에 맡길 일과 차례로 맡길 일
공식 문서는 서로의 결과를 기다리지 않는 조사를 여러 서브에이전트에게 동시에 맡기면, 각자 조사하고 Claude가 결과를 합친다고 설명합니다. 앞 결과가 필요한 일은 차례로 맡기며, 이때 Claude는 앞 서브에이전트의 결과에서 필요한 내용을 다음 서브에이전트에게 넘깁니다.
| 맡길 일(예시) | 판단 | 이유 |
|---|---|---|
| 1분기 회의록 조사와 2분기 회의록 조사 | 동시에 맡기기 | 서로의 결과를 기다리지 않습니다 |
| 두 조사로 합친 표를 원본과 대조하는 검수 | 조사가 끝난 뒤 맡기기 | 합친 표가 있어야 시작할 수 있습니다 |
| 보고서 제목의 오타 한 글자 고치기 | 메인 대화에서 직접 | 범위가 좁고 빠르게 끝나는 수정입니다 |
| 표의 열 순서를 몇 번 바꿔 보며 고르기 | 메인 대화에서 직접 | 사용자와 여러 번 주고받으며 다듬는 일입니다 |
공식 문서는 메인 대화에서 할 일과 서브에이전트에게 넘길 일도 나눠 둡니다. 주고받기가 잦은 일, 여러 단계가 같은 맥락을 많이 공유하는 일, 빠르고 범위가 좁은 수정은 메인 대화에서 합니다. 메인 대화에 필요 없는 긴 출력이 나오는 일, 도구나 권한을 제한해야 하는 일, 혼자 끝내고 요약만 돌려주면 되는 일은 서브에이전트에게 넘깁니다.
기본 설정에서 한 세션에 동시에 실행 중인 서브에이전트가 20개에 이르면, 하나를 더 띄우려 할 때 Concurrent subagent limit reached 오류가 나고 실행 중인 수가 줄어야 다시 띄울 수 있습니다. 서브에이전트는 기본으로 메인 대화 아래 세 단계까지 자기 서브에이전트를 더 띄울 수 있습니다. 여러 세션이 서로 메시지를 주고받는 에이전트 팀 같은 구성은 멀티 에이전트 오케스트레이션 수업에서 다룹니다.
직접 해 보기: 회의록 조사 서브에이전트 만들어 부르기
실제 업무 폴더 대신 설치와 첫 실행 수업에서 만든 claude-practice 같은 연습 폴더에서 합니다.
- 연습 폴더 안에
회의록폴더를 만들고, 메모장이나 텍스트 편집기로 파일 세 개를 만듭니다.0903_한빛상사.txt에는 "거래처: 한빛상사, 날짜: 2026-09-03, 요청: 견적서 다시 보내기",0912_다온물산.txt에는 "거래처: 다온물산, 날짜: 2026-09-12, 요청: 납품일 앞당기기",메모_세움건설.txt에는 "거래처: 세움건설, 요청: 회의 일정 다시 잡기"를 적어 저장합니다. - macOS는 터미널, Windows는 PowerShell에서
cd로 연습 폴더로 이동한 뒤claude를 실행하고, 입력창에 다음 요청을 보냅니다. "이 프로젝트의 .claude/agents 폴더에 minutes-researcher 서브에이전트를 만들어 줘. 회의록 폴더에서 거래처, 요청한 일, 날짜를 찾아 표로 돌려주고, 날짜가 없는 회의록은 표 아래에 파일 이름만 적게 해 줘. 도구는 Read, Glob, Grep만 줘." - 같은 Claude Code 입력창에 "방금 만든 .claude/agents/minutes-researcher.md 파일 내용을 그대로 보여 줘"라고 보냅니다. Claude가 보여 준 파일의 머리말에 name과 description이 있고 tools에 Read, Glob, Grep만 적혀 있으면 됩니다.
/exit로 Claude Code를 끝내고, 같은 터미널 또는 PowerShell 창에서claude를 다시 실행합니다. 2번에서.claude/agents폴더가 처음 생겼다면, 이렇게 다시 시작해야 Claude Code가 새 서브에이전트를 읽습니다.- 입력창에
@를 치고 목록에서 minutes-researcher를 고릅니다. 입력창에@"minutes-researcher (agent)"가 들어가면 그 뒤에 "회의록 폴더를 조사해 줘"를 이어 적어 보냅니다. 목록에 minutes-researcher가 없으면 아래 "막혔을 때" 표의 첫 두 줄을 봅니다. - 대화 기록에
minutes-researcher(...)줄이 보이는지 봅니다. 돌아온 표에 한빛상사와 다온물산의 날짜와 요청이 맞게 들어 있고,메모_세움건설.txt는 날짜 없이 표 아래에 파일 이름으로 적혀 있으면 됩니다. 회의록폴더에 파일을 하나 더 만들고 같은 요청을 다시 보냅니다. 새 파일이 표에 들어왔는지 원본 파일과 대조합니다.
막혔을 때
| 상황 | 원인 | 할 일 |
|---|---|---|
| 새로 만든 서브에이전트를 Claude가 찾지 못함 | 세션을 시작할 때 agents 폴더가 없었습니다 | Claude Code를 끝내고 다시 실행합니다 |
| 파일을 만들었는데 서브에이전트로 쓰이지 않음 | name이나 description이 없거나, 첫 줄이 ---가 아니거나, 머리말 형식이 틀리면 Claude Code가 알리지 않고 그 파일을 건너뜁니다 | 머리말을 확인하고, 이유를 보려면 claude --debug로 실행해 디버그 로그를 봅니다 |
| 이름을 적어 요청했는데 Claude가 직접 처리함 | 이름을 적은 요청은 Claude가 맡길지 판단합니다 | 입력창에 @를 치고 목록에서 서브에이전트를 고릅니다 |
| 서브에이전트가 메인 대화에서 말한 조건을 지키지 않음 | 포크가 아닌 서브에이전트는 메인 대화의 기록을 물려받지 않습니다 | 맡기는 요청에 그 조건을 다시 적습니다 |
| 조사만 맡긴 서브에이전트가 파일을 고침 | tools를 적지 않아 쓸 수 있는 도구를 모두 물려받았습니다 | tools에 Read, Glob, Grep 같은 읽기 도구만 적습니다 |
Concurrent subagent limit reached 오류 | 기본 설정에서 동시에 실행 중인 서브에이전트가 20개에 이르렀습니다 | 실행 중인 서브에이전트가 끝나 수가 줄면 다시 맡깁니다 |
| Claude Code를 시작할 때 설명 합계 경고가 뜸 | 서브에이전트 설명의 합계가 15,000토큰을 넘었습니다 | description을 줄이고 자세한 지시는 본문으로 옮깁니다 |
자주 묻는 질문
스킬과 서브에이전트는 무엇이 다른가요?
스킬은 메인 대화의 컨텍스트 안에서 쓰는 저장된 지시와 절차이고, 서브에이전트는 별도 컨텍스트에서 일한 뒤 결과만 돌려주는 보조 에이전트입니다. 공식 문서는 다시 쓸 지시나 작업 순서를 메인 대화 안에서 실행하고 싶으면 서브에이전트 대신 스킬을 쓰라고 안내합니다.
스킬도 SKILL.md 머리말(맨 위 --- 사이)에 context: fork를 적으면 서브에이전트에서 실행할 수 있습니다. 스킬을 만드는 법은 슬래시 명령어 수업과 클로드 스킬 수업에서 다룹니다.
특정 서브에이전트를 못 쓰게 할 수 있나요?
프로젝트의 .claude/settings.json 같은 Claude Code 설정 파일에 있는 권한 규칙 permissions.deny에 Agent(Explore)처럼 적으면 그 서브에이전트를 막을 수 있습니다. 기본 제공 서브에이전트와 직접 만든 서브에이전트 모두 Agent(서브에이전트이름) 형식으로 막고, Claude Code를 시작할 때 claude --disallowedTools "Agent(Explore)"처럼 막을 수도 있습니다.
서브에이전트가 파일을 고쳐도 되나요?
tools에 Write나 Edit를 주거나 tools를 적지 않으면 서브에이전트도 파일을 고칠 수 있습니다. 여러 서브에이전트가 같은 파일을 동시에 고치면 서로의 변경을 덮어쓸 수 있으므로, 고치는 일은 파일이나 폴더를 나눠 맡기거나 차례로 맡깁니다.
Git으로 관리하는 폴더라면 isolation: worktree를 적어 서브에이전트가 임시 워크트리에서 일하게 할 수 있습니다. 워크트리는 저장소를 따로 떼어 낸 작업용 사본이라 원래 폴더의 파일과 섞이지 않지만, 나중에 변경을 합칠 때 생기는 충돌까지 막아 주지는 않습니다.
서브에이전트와 에이전트 팀은 무엇이 다른가요?
서브에이전트는 한 세션 안에서 메인 대화의 Claude가 부르면 일하고 요약을 돌려주는 기능이고, 에이전트 팀은 Claude가 여러 세션을 띄워 서로 메시지를 주고받으며 함께 일하게 하는 기능입니다. 둘의 차이와 고르는 기준은 멀티 에이전트 오케스트레이션 수업에서 다룹니다.
참고 자료
- Claude Code 공식 문서: Create custom subagents(서브에이전트 만들기, 부르기, 받는 것)
- Claude Code 공식 문서: Best practices(서브에이전트로 조사와 검수 나누기)
- Claude Code 공식 문서: Manage costs effectively(서브에이전트의 사용량)
- Claude Code 공식 문서: Commands(/agents, /subtask, /tasks)
- Claude Code 공식 문서: Configure permissions(Agent 규칙)
- Claude Code 공식 문서: How Claude remembers your project(CLAUDE.md와 자동 메모리)
제대로 이해했는지 한 문제로 확인해 볼까요?
답을 고르면 바로 풀이가 나와요.
메인 대화에서 "거래처 이름은 줄이지 말아 줘"라고 말한 뒤, 포크가 아닌 서브에이전트에게 회의록 조사를 맡깁니다. 서브에이전트가 이 조건을 지키게 하려면 어떻게 하나요?
예제나 확인 질문을 직접 시도한 뒤 완료 표시해요. 더 연습할 내용이 남으면 표시하지 않고 다음 글을 읽어도 됩니다. 완료 버튼은 이해도를 채점하지 않으며 잘못 표시하면 취소할 수 있어요.
