클로드 코드 서브에이전트 — 일을 나눠 맡기고 요약만 받는 법

클로드 코드 서브에이전트란 — 따로 일하고 요약만 돌려주는 도우미

클로드 코드와 오래 대화하면 검색 결과, 긴 로그, 파일 내용이 대화에 계속 쌓인다. 그 대부분은 한 번 보고 다시 볼 일이 없는 내용이다. 공식 문서는 바로 이럴 때 서브에이전트를 쓰라고 한다. 서브에이전트는 그 곁일을 자기 컨텍스트 창(한 번에 기억하며 다룰 수 있는 대화 분량)에서 하고 요약만 돌려준다.

서브에이전트마다 따로 정한 시스템 프롬프트(그 도우미가 따를 기본 지시문), 쓸 수 있는 도구, 권한이 있다. 클로드는 맡길 일이 어떤 서브에이전트의 설명과 맞으면 그쪽에 넘기고, 서브에이전트는 혼자 일한 뒤 결과를 돌려준다. 공식 문서가 꼽는 쓸모는 다섯 가지다.

• 주 대화를 깨끗하게 지킨다. 찾아보기와 작업 과정이 주 대화에 쌓이지 않는다.
• 쓸 수 있는 도구를 좁힌다. 예를 들어 읽기만 하는 도우미를 만들 수 있다.
• 한 번 만든 설정을 여러 프로젝트에서 다시 쓴다.
• 한 가지 일에 맞춘 지시문으로 더 일관되게 일하게 한다.
• Haiku처럼 빠르고 값싼 모델로 일을 돌려 비용을 줄인다.

처음부터 들어 있는 서브에이전트 세 가지

직접 만들지 않아도 클로드 코드에는 기본 서브에이전트가 들어 있다. 클로드가 알맞을 때 알아서 부른다. 처음에는 아래 세 가지만 알면 된다.

• Explore: 코드와 파일을 빠르게 찾고 읽는 읽기 전용 도우미다. 파일을 쓰거나 고치는 도구는 막혀 있다. 클로드는 부를 때 꼼꼼함 정도를 quick · medium · very thorough 가운데서 고른다.
• Plan: 플랜 모드(고치기 전에 계획부터 세우는 읽기 전용 모드)에서 계획에 필요한 자료를 모으는 도우미다. 역시 읽기 전용이다.
• general-purpose: 찾아보기와 고치기가 함께 필요한 여러 단계 일을 맡는다. 서브에이전트가 쓸 수 있는 도구를 모두 쓴다.

이 밖에 /statusline을 실행할 때 쓰이는 statusline-setup, 클로드 코드 기능을 물을 때 쓰이는 claude-code-guide 같은 도우미도 있다. 이런 도우미는 보통 클로드가 알아서 부르므로 직접 쓸 일은 드물다.

한 가지 차이를 알아 두면 좋다. Explore와 Plan은 빠르고 값싸게 조사하도록 CLAUDE.md 파일과 git 상태 요약 없이 시작한다. 다른 기본 서브에이전트와 직접 만든 서브에이전트는 둘 다 읽고 시작한다. CLAUDE.md가 무엇인지는 클로드 코드 CLAUDE.md 쓰는 법 — 무엇을 적고 어디에 두나에 정리했다.

정리하면 «찾기만»은 Explore, «계획 전 조사»는 Plan, «찾고 고치기»는 general-purpose다. 같은 종류의 일을 같은 지시로 자꾸 맡기게 되면 그때 나만의 서브에이전트를 만들면 된다.

첫 서브에이전트 만들기 — 파일 하나로 4단계

서브에이전트는 맨 위에 설정 칸이 붙은 마크다운 파일 하나다. 이 설정 칸을 프런트매터(파일 맨 위 --- 두 줄 사이에 적는 설정)라고 한다. 클로드에게 만들어 달라고 해도 되고, 직접 써도 된다.

파일을 둘 곳은 두 군데 가운데 고른다.

• .claude/agents/: 프로젝트 폴더 안이다. 그 프로젝트에서만 쓴다. 버전 관리에 올리면 팀이 같이 쓴다.
• ~/.claude/agents/: 사용자 폴더 안이다. 내 모든 프로젝트에서 쓴다.

여기서 ~는 사용자 폴더를 뜻한다. Windows에서는 보통 C:\Users\내이름 자리다.

1. 프로젝트 폴더에서 claude를 실행하고, 만들 서브에이전트와 저장할 곳을 말한다. 공식 빠른 시작은 코드 개선 도우미를 예로 들고, 여기서는 같은 방식으로 긴 로그를 요약하는 도우미를 만든다.

이 프로젝트의 .claude/agents/ 폴더에 log-summarizer 서브에이전트를 만들어 줘. 긴 로그나 보고서 파일을 읽고 오류·경고 줄과 다섯 줄 요약만 돌려주게 해 줘. 읽기 전용으로 하고 Haiku 모델을 쓰게 해 줘.

잘 됐으면 클로드가 이름(name) · 설명(description) · 도구 목록(tools) · 모델(model) · 지시문이 든 파일을 썼다고 알려 준다.

1. 만들어진 파일을 열어 내용을 확인한다. 직접 만들 때는 메모장 같은 편집기로 아래 내용을 .claude/agents/log-summarizer.md 이름으로 저장하면 된다.

---
name: log-summarizer
description: 긴 로그·보고서 파일을 읽고 오류와 짧은 요약만 돌려준다. 붙여 넣기엔 너무 긴 파일일 때 쓴다.
tools: Read, Grep, Glob
model: haiku
---

너는 긴 텍스트 파일을 고치지 않고 요약한다.
불리면 이렇게 한다.
1. 맡은 파일이나 폴더를 읽는다.
2. 오류(error)와 경고(warning) 줄만 줄 번호와 함께 적는다.
3. 마지막에 다섯 줄 이내 요약을 붙인다.
파일을 고치거나 옮기거나 지우지 않는다.

잘 됐으면 맨 위 --- 두 줄 사이에 name · description · tools · model 네 줄이 보인다. 꼭 있어야 하는 칸은 name과 description 둘뿐이다. tools에 읽기 · 찾기 도구만 적었으니 이 도우미는 파일을 고칠 수 없다. 아래 지시문은 이 서브에이전트가 불릴 때만 실린다.

1. 형식이 맞는지 터미널에서 확인한다. 이 단계는 골라서 하면 된다. Claude Code v2.1.233 이상에서 쓰는 명령이다.

claude plugin validate .claude/agents

잘 됐으면 체크 표시와 함께 Validation passed가 나온다. 이 글을 정리한 Windows PC에서 위 파일을 시험 폴더에 두고 돌리니 그 문구가 나왔다. 일부러 프런트매터를 깨뜨린 파일로 다시 돌리자 YAML frontmatter failed to parse 오류와 함께 Validation failed가 나왔다. 오류 설명에는 이런 파일은 실행할 때 아예 실리지 않는다는 말도 붙어 있었다.

1. 대화에서 서브에이전트 이름을 넣어 일을 시킨다.

log-summarizer 서브에이전트로 logs 폴더의 app.log 파일을 요약해 줘.

이름을 말하면 클로드가 보통 그 서브에이전트에 맡긴다. 반드시 그 서브에이전트가 돌게 하려면 @를 치고 목록에서 고르는 @-멘션을 쓴다. 목록 없이 직접 칠 때는 @agent-log-summarizer처럼 쓴다.

잘 됐으면 대화에 log-summarizer(…)처럼 서브에이전트 이름 뒤에 짧은 작업 설명이 붙은 줄이 보인다. 이 4단계는 이 글의 시험에서 돌리지 않았다. 모델을 부르는 단계라 공식 문서의 설명만 옮겼다.

서브에이전트 파일에 적는 칸

파일 칸 이름은 표에 적힌 그대로 써야 한다. maxTurns처럼 두 낱말 이상인 칸은 가운데 낱말을 대문자로 붙여 쓴다. 철자가 틀린 칸은 오류 없이 그냥 무시된다. 처음에 알아 둘 칸은 아래와 같다.

• name: 꼭 필요하다. 겹치지 않는 이름이다. 파일 이름과 같지 않아도 된다.
• description: 꼭 필요하다. 클로드가 언제 이 서브에이전트에 맡길지 정하는 설명이다.
• tools: 쓸 도구 목록이다. 비우면 서브에이전트가 쓸 수 있는 도구를 모두 물려받는다.
• disallowedTools: 뺄 도구 목록이다. 예를 들어 Write, Edit를 적으면 파일 쓰기만 막는다.
• model: sonnet · opus · haiku · fable 같은 별칭이나 전체 모델 ID, 주 대화와 같은 모델을 뜻하는 inherit를 적는다.
• permissionMode: 이 서브에이전트가 쓸 권한 모드다.

파일을 고치면 다시 시작하지 않아도 된다. 클로드 코드는 두 agents 폴더를 지켜보다가 몇 초 안에 바뀐 내용을 알아챈다. 다만 세션을 시작할 때 없던 agents 폴더에 첫 파일을 만들었다면 클로드 코드를 다시 시작해야 한다.

인용 — Claude Code Docs «Create custom subagents»

«Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions.» — 각 서브에이전트는 따로 정한 시스템 프롬프트, 정해진 도구, 독립된 권한을 갖고 자기 컨텍스트 창에서 돈다.

같은 문서는 서브에이전트가 보내는 요청도 주 대화와 같은 사용 한도에 함께 들어간다고 덧붙였다.

무엇을 맡기고 무엇을 남길까 — 서브에이전트 쓰는 세 가지 방식

공식 문서가 보여 주는 쓰임은 세 가지다. 셋 다 특별한 명령 없이 평소 말로 부탁하면 된다.

첫째, 출력이 긴 일을 따로 돌린다. 시험 실행, 문서 가져오기, 로그 파일 처리는 컨텍스트를 많이 먹는다. 이런 일을 서브에이전트에 넘기면 긴 출력은 서브에이전트 쪽에 남고 필요한 요약만 돌아온다. 비용 문서도 같은 방법을 권한다. 공식 예시는 시험을 돌리고 실패한 시험만 알려 달라는 문장이다. 사무 일에 맞추면 아래처럼 쓸 수 있다.

서브에이전트를 써서 logs 폴더의 로그 파일을 모두 읽고, 오류 종류와 나온 횟수만 표로 알려 줘.

둘째, 서로 기대지 않는 조사를 나란히 돌린다. 서브에이전트마다 자기 몫을 따로 살핀 뒤 클로드가 결과를 묶는다. 조사 갈래가 서로에게 기대지 않을 때 가장 잘 된다.

서브에이전트를 따로 셋 띄워서 2024, 2025, 2026 폴더의 보고서를 나란히 읽고 폴더마다 핵심을 다섯 줄씩 정리해 줘.

셋째, 서브에이전트를 차례로 잇는다. 앞 서브에이전트의 결과를 클로드가 받아 필요한 내용만 다음 서브에이전트에 넘긴다.

log-summarizer 서브에이전트로 오류를 추린 다음, 그 결과로 general-purpose 서브에이전트가 오류별 확인 목록 파일을 만들게 해 줘.

조심할 점도 있다. 서브에이전트가 끝나면 결과가 주 대화로 돌아온다. 서브에이전트를 많이 돌리고 저마다 긴 결과를 돌려주면 그것만으로 컨텍스트를 꽤 먹는다. 서브에이전트는 도는 동안 자기 토큰(모델이 글을 세는 단위)도 따로 쓴다.

서브에이전트 대신 주 대화가 나은 일

모든 일을 나누는 것이 답은 아니다. 공식 문서는 아래 일은 주 대화에서 하라고 한다.

• 자주 주고받으며 조금씩 다듬어야 하는 일
• 계획 · 구현 · 시험처럼 여러 단계가 같은 맥락을 많이 나눠 쓰는 일
• 금방 끝나는 작은 수정
• 빨리 답을 받아야 하는 일. 새 서브에이전트는 맨 처음부터 시작해서 맥락을 모으는 데 시간이 든다.

반대로 출력이 길어 주 대화에 남길 필요가 없는 일, 도구나 권한을 좁혀야 하는 일, 혼자 끝내고 요약만 돌려주면 되는 일은 서브에이전트에 맡긴다. 이미 대화에 있는 내용을 잠깐 묻고 싶을 때는 서브에이전트 대신 /btw를 쓴다. 전체 맥락을 보지만 도구는 못 쓰고, 답이 대화 기록에 남지 않는다. 이런 대화 안 명령은 클로드 코드 슬래시 명령 모음 — 상황별로 자주 쓰는 것부터에 모아 두었다.

되풀이하는 지시를 주 대화 안에서 그대로 쓰고 싶다면 서브에이전트보다 스킬이 맞다. 스킬은 클로드 스킬 — 반복하는 일을 규칙으로 저장하고 꺼내 쓰는 법에서 다뤘다.

모델과 도구를 좁히면 비용과 위험을 함께 줄일 수 있다. 서브에이전트의 요청도 사용량에 들어가므로 가벼운 일에는 작은 모델을 고르라고 비용 문서가 권한다. 모델은 «부를 때 클로드가 정한 모델 → 파일의 model 칸 → CLAUDE_CODE_SUBAGENT_MODEL 환경 변수 → 주 대화 모델» 순서로 정해진다. 사용 한도가 닳는 원리는 클로드 사용 한도 이해하기 — 왜 빨리 닳고 언제 풀리나에 있다.

권한은 하나 헷갈리기 쉽다. 주 대화가 bypassPermissions · acceptEdits · auto 모드라면 서브에이전트도 같은 모드로 돌고, 파일에 적은 permissionMode는 무시된다. 주 대화가 plan 모드면 서브에이전트도 플랜 모드에 머문다. 모드마다 무엇이 다른지는 클로드 코드 권한 모드 — 묻게 할 일과 맡길 일 나누기에 정리했다.

위 네 가지는 모두 공식 서브에이전트 문서에 방법이 있다. 처음에는 하나씩만 붙여 보고, 결과가 기대대로 나오면 다음 칸을 더하는 편이 원인을 찾기 쉽다.

클로드 코드 서브에이전트가 안 불릴 때와 알아 둘 한도

서브에이전트가 생각대로 움직이지 않으면 증상에 맞춰 아래 순서로 확인한다.

1. 새로 만든 서브에이전트를 클로드가 못 찾으면 클로드 코드를 다시 시작한다. 세션을 시작할 때 agents 폴더가 없었다면 지금 도는 세션은 새 폴더를 알아채지 못한다.
2. 목록에 아예 안 보이면 파일 맨 위를 본다. 아래 경우에는 클로드 코드가 알리지 않고 파일을 건너뛴다.

- name이 없다. - 여는 ---가 파일 첫 줄이 아니다. - name이 -로 시작하거나 :를 품고 있다. - description이 없다. - YAML(설정 칸을 적는 문법) 형식이 깨졌다.

1. 적은 칸이 먹히지 않으면 칸 이름 철자를 본다. claude --debug로 실행한 뒤 디버그 로그에서 does not recognize or apply를 찾으면 알아듣지 못한 칸 이름이 나온다. v2.1.296 이상에서 된다.
2. 클로드가 알아서 맡기지 않으면 description을 더 구체적으로 고친다. 알아서 자주 맡기게 하려면 설명에 "use proactively" 같은 말을 넣으라고 공식 문서가 안내한다. 한 번은 꼭 맡기고 싶다면 @-멘션을 쓴다.
3. 도구가 하나도 없다는 오류가 나면 tools 목록의 철자와, 서브에이전트가 쓸 수 없는 도구를 적지 않았는지 본다.

claude --debug

디버그 로그는 ~/.claude/debug/ 폴더에 세션 ID 이름의 텍스트 파일로 남는다.

서브에이전트에 걸린 한도와 모르면 놀라는 동작

알아 둘 한도와 동작은 아래와 같다.

• 대화 기록을 못 본다. 서브에이전트는 새 컨텍스트에서 시작해서 지금까지의 대화, 이미 쓴 스킬, 클로드가 읽은 파일을 모른다. 꼭 지킬 규칙이 있으면 맡길 때 다시 적는다.
• 기본은 백그라운드다. 주 대화에서 클로드가 띄운 서브에이전트는 따로 설정하지 않으면 백그라운드에서 돈다. 권한을 묻는 창은 주 대화에 뜨고, Esc를 누르면 서브에이전트는 멈추지 않고 그 한 번의 도구 호출만 거절된다.
• 깊이 한도가 있다. 서브에이전트는 주 대화 아래로 세 층까지 자기 서브에이전트를 띄울 수 있다. 층 수는 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 환경 변수로 바꾼다.
• 동시 실행 한도가 있다. 한 세션에서 서브에이전트 20개가 돌고 있으면 하나를 더 띄울 때 Concurrent subagent limit reached 오류가 난다. 한 세션 동안 띄우는 전체 개수에는 한도가 없다.
• 설명이 길면 경고가 뜬다. 기본 서브에이전트를 뺀 설명의 합이 15,000 토큰을 넘으면 시작할 때 경고가 나온다. 설명은 짧게 두고 자세한 내용은 지시문으로 옮긴다.
• 이어 하기는 된다. 끝난 서브에이전트에 "그 검토를 이어서 해 줘"처럼 말하면 앞 기록을 그대로 가진 채 이어 간다. Explore와 Plan은 한 번 쓰고 끝나는 도우미라 이어 하지 못한다.
• 기록은 30일 뒤 지워진다. 서브에이전트 대화 기록은 기본 보관 기간 30일이 지나면 정리된다.

표의 위 세 줄은 «파일이 제대로 읽혔느냐»의 문제다. 아래 세 줄은 «읽힌 서브에이전트를 클로드가 어떻게 쓰느냐»의 문제다. 처음에는 claude plugin validate로 형식을 보고, 그래도 안 되면 description을 고쳐 보는 두 가지만 해도 대부분 원인이 보인다. 클로드 코드 설치부터 낯설다면 클로드 코드 설치·요금제·첫 사용 (2026) — Windows에서 시작하기를 먼저 보면 된다.

일이 아주 커지면 서브에이전트 다음 단계가 있다. 공식 문서는 서브에이전트를 «클로드가 차례마다 판단해 띄우는 일꾼»으로, 한 차례에 몇 가지 일을 맡기는 크기로 설명한다. 동적 워크플로(클로드가 쓴 스크립트가 서브에이전트 여러 개를 지휘하는 기능)는 한 번에 수십에서 수백 개의 에이전트를 돌리고, 중간 결과를 대화가 아닌 스크립트 안에 둔다. 진행은 /workflows로 보고, Pro 요금제에서는 /config의 Dynamic workflows 줄에서 켠다. 한 번 돌릴 때 대화로 할 때보다 토큰을 꽤 더 쓸 수 있어서, 공식 문서는 작은 범위로 먼저 돌려 보라고 권한다. 에이전트 25개를 넘기거나 예상 토큰이 150만을 넘으면 Large workflow 경고가 뜬다. 세션끼리 서로 말을 주고받는 에이전트 팀은 아직 실험 기능이라 기본으로 꺼져 있다.

자주 묻는 것

서브에이전트와 스킬은 무엇이 다른가요?

스킬은 주 대화 안에서 클로드가 따르는 지시입니다. 서브에이전트는 따로 떨어진 컨텍스트 창에서 일하고 결과만 돌려주는 도우미입니다. 되풀이하는 지시를 주 대화 맥락 그대로 쓰고 싶으면 스킬이, 긴 출력을 주 대화 밖에 두고 싶으면 서브에이전트가 맞습니다.

서브에이전트도 사용 한도를 쓰나요?

씁니다. 서브에이전트가 보내는 요청도 주 대화와 같은 사용 한도에 들어갑니다. 가벼운 일을 맡기는 서브에이전트는 파일의 model 칸에 haiku처럼 작은 모델을 적어 두면 덜 씁니다.

서브에이전트가 내 CLAUDE.md를 읽나요?

직접 만든 서브에이전트와 general-purpose는 주 대화가 읽는 CLAUDE.md를 함께 읽고 시작합니다. Explore와 Plan은 빠른 조사를 위해 읽지 않습니다. 다만 어느 쪽이든 지금까지 나눈 대화 기록은 보지 못하니, 꼭 지킬 규칙은 맡길 때 다시 적는 편이 안전합니다.

서브에이전트가 또 서브에이전트를 부를 수 있나요?

기본으로 주 대화 아래 세 층까지 부를 수 있습니다. 맨 아래 층에 닿은 서브에이전트는 더 맡기지 않고 직접 일한 뒤 요약 하나를 돌려줍니다. 읽기만 해야 하는 서브에이전트가 남을 부르지 못하게 하려면 tools 목록에서 Agent를 빼면 됩니다.

같은 이름의 서브에이전트가 두 곳에 있으면 어떻게 되나요?

우선순위가 높은 쪽 하나만 씁니다. 순서는 조직 관리 설정, 실행할 때 넘긴 --agents 값, 프로젝트의 .claude/agents 폴더, 사용자 폴더의 .claude/agents 폴더, 플러그인 순입니다. 그래서 프로젝트에 같은 이름을 두면 사용자 폴더의 것보다 먼저 쓰입니다.

정리 — 곁일은 나눠 맡기고, 요약만 받는다

서브에이전트는 곁일을 자기 컨텍스트 창에서 하고 요약만 돌려주는 도우미다. 찾기만 할 때는 Explore, 계획 전 조사는 Plan, 찾고 고치기는 general-purpose가 기본으로 들어 있다. 나만의 서브에이전트는 .claude/agents/에 name과 description이 든 마크다운 파일 하나로 만든다. 출력이 긴 일, 도구를 좁혀야 하는 일, 혼자 끝낼 수 있는 일을 맡기고, 자주 주고받는 일은 주 대화에 남긴다. 안 불리면 형식, 칸 이름, 설명 순서로 본다. 서브에이전트도 사용 한도를 쓰니 가벼운 일에는 작은 모델을 고른다. 명령과 동작은 판마다 바뀔 수 있으니, 이 글은 2026년 11월 3일 기준으로 읽고 쓰기 전에 공식 문서를 한 번 더 확인한다. 지금 하나만 해 본다면, 긴 로그 하나를 골라 요약 서브에이전트에 맡겨 보자.

참고 자료

1. Claude Code Docs. Create custom subagents — 서브에이전트 정의 · 기본 서브에이전트(Explore · Plan · general-purpose) · 빠른 시작 · 저장 범위와 우선순위 · 파일 칸 · 모델 순서 · 도구 제한 · 권한 모드 · 불러 쓰기(자연어 · @-멘션 · --agent) · 백그라운드 · 흔한 쓰임 · 주 대화와 고르는 기준 · 깊이 · 동시 실행 한도 · 시작할 때 실리는 것 · 이어 하기 · 건너뛰는 파일 · 모범 사례(2026-11-03 확인). code.claude.com
2. Claude Code Docs. Orchestrate subagents at scale with dynamic workflows — 서브에이전트 · 스킬 · 에이전트 팀 · 워크플로 비교 표 · Pro에서 켜기 · /workflows · 비용과 큰 워크플로 경고(2026-11-03 확인). code.claude.com
3. Claude Code Docs. Orchestrate teams of Claude Code sessions — 에이전트 팀은 실험 기능 · 기본 꺼짐 · 서브에이전트와 비교(2026-11-03 확인). code.claude.com
4. Claude Code Docs. Manage costs effectively — 긴 출력은 서브에이전트에 맡기기 · 서브에이전트 요청도 사용량에 들어감 · 작은 모델 고르기(2026-11-03 확인). code.claude.com
5. Claude Code 문서. 사용자 정의 subagent 만들기 — 한국어판 용어(subagent · 컨텍스트 윈도우 · 사용 제한)(2026-11-03 확인). code.claude.com