클로드 코드 서브에이전트: 일을 나눠 맡기기

Claude Code(클로드 코드)는 긴 작업을 혼자 다 하지 않고 보조 일꾼인 서브에이전트에게 나눠 맡길 수 있습니다. 대화가 길어질수록 컨텍스트 창이 검색 결과와 중간 로그로 채워지면서 정작 처음에 중요했던 지시가 뒤로 밀리는 한계 때문에 생긴 장치입니다. 서브에이전트는 이 부작업을 아예 다른 방, 그러니까 별도의 컨텍스트로 떼어 보내고 결과만 받아보는 장치입니다.

대화 하나에 자료 조사부터 초안 작성까지 전부 시키면 뒤로 갈수록 Claude Code의 답이 흐려지는 경험, 한 번쯤 있으실 겁니다.

지난 레슨에서 반복 절차를 스킬 하나로 만들었다면, 오늘은 그 스킬 하나가 감당하기엔 일이 너무 커졌을 때 나누는 차례입니다. 서브에이전트 만드는 법이 급해서 오셨다면 이 레슨만 보셔도 됩니다. 세부 옵션이 릴리스마다 조금씩 늘어나는 영역이니, 오래된 시점에 읽으신다면 공식 문서를 함께 확인해 주세요.

서브에이전트 (Subagent)

서브에이전트는 특정 작업을 처리하도록 위임받는 전문화된 AI 워커다. 주 대화와 분리된 자기만의 컨텍스트 윈도우에서 실행되고, 별도의 시스템 프롬프트와 도구 권한을 가지며, 작업을 마치면 과정 전체가 아니라 요약된 결과만 주 대화로 돌려준다. 스킬 하나가 자료 조사와 결과 작성을 동시에 떠안아 결과가 뭉개지기 시작했다면 서브에이전트로 나눌 때다.

서브에이전트가 하는 일

공식 문서 "사용자 정의 subagent 만들기"는 서브에이전트가 하는 일을 정확히 이 셋으로 설명합니다. 자기만의 컨텍스트 윈도우에서 실행되고, 사용자 정의 시스템 프롬프트와 특정 도구 액세스를 가지며, 독립적인 권한으로 작동합니다. 부작업이 검색 결과나 로그, 다시 참조하지 않을 파일 내용으로 주 대화를 채울 때 위임하면 그 내용은 서브에이전트 안에서만 쌓이고, 주 대화에는 결론만 돌아옵니다.

사실 Claude Code는 처음부터 서브에이전트 몇 개를 이미 내장하고 있습니다. 코드베이스 검색에 최적화된 Explore, 계획 모드에서 조사를 도맡는 Plan, 탐색과 수정을 함께 필요로 하는 복잡한 작업을 처리하는 general-purpose가 대표적입니다. 지금까지 이 트랙을 따라오며 Claude Code가 파일을 뒤져 답을 찾아준 순간이 있었다면, 이미 이 내장 서브에이전트 중 하나가 뒤에서 돌았을 가능성이 큽니다.

이름이 비슷해 헷갈리는 명령이 하나 있습니다. 터미널에 claude agents --help를 쳐보면 "Manage background agents"라는 전혀 다른 기능이 나옵니다. 이 명령은 이 레슨이 다루는 서브에이전트가 아니라, 터미널 창을 닫아도 별도 감독자 프로세스가 대신 붙잡고 있어 계속 도는 백그라운드 세션들을 관리하는 명령입니다. 다만 컴퓨터가 잠들면 세션도 같이 멈췄다가 깨어날 때 이어집니다. 컴퓨터를 완전히 꺼둔 채로도 도는 건 다음 레슨에서 다룰 클라우드 루틴 쪽입니다. 서브에이전트 파일은 어디까지나 .claude/agents/ 폴더에 있습니다. 공식 문서도 "유사한 이름에도 불구하고 이 둘은 별개"라고 못박습니다. 참고로 v2.1.198부터는 /agents를 입력해도 예전처럼 대화형 마법사가 뜨지 않고, 대신 Claude(클로드)에게 요청하거나 .claude/agents/를 직접 편집하라는 안내만 출력됩니다. claude --version으로 확인한 버전이 그보다 높으면 이 동작이 그대로 적용됩니다. 본인 환경에서 한 번 확인해 보시면 됩니다.

서브에이전트 파일은 스킬과 똑같이 YAML frontmatter가 있는 마크다운입니다. 실제로 자주 쓰는 필드만 추리면 이렇습니다.

위치도 스킬과 결이 같습니다. 이 프로젝트에서만 쓰려면 .claude/agents/에, 내 모든 프로젝트에서 재사용하려면 ~/.claude/agents/에 둡니다. 도구를 제한하는 방법은 두 가지입니다. tools로 허용 목록을 적으면 그 목록에 없는 도구는 아예 못 쓰고, 반대로 disallowedTools로 제외 목록만 적으면 나머지 도구는 주 대화에서 상속한 그대로 씁니다. 자료를 읽기만 하고 아무것도 고치지 않아야 하는 서브에이전트라면 tools로 좁히는 편이, 대부분은 상속해도 되고 특정 도구 하나만 막고 싶다면 disallowedTools가 손이 덜 갑니다.

하나 만들어 시켜보기

이 트랙의 관통 시나리오인 고객사 월간 콘텐츠 리포트로 실습해 보겠습니다. 지난 레슨에서 만든 monthly-report-draft 스킬은 자료 수집부터 표 작성까지 한 번에 다 시켰습니다. 이번에는 자료 수집만 따로 떼어 전담 서브에이전트로 만듭니다.

.claude/agents/report-researcher.md를 이렇게 만듭니다.

---
name: report-researcher
description: 이번 달 고객사 콘텐츠 게시물 목록과 채널별 지표를 모아 요약으로 돌려준다. 자료 수집 단계에서 검색 결과와 로그로 대화창을 채우지 않으려 할 때 쓴다.
tools: Read, Grep, Glob, WebFetch
model: haiku
---
 
당신은 자료 수집 전담 조사원입니다. 이번 달과 지난달의 게시물 목록, 채널별 지표를
찾아 표로 정리해 돌려주세요. 훑어본 파일 경로나 중간 검색 과정은 결과에 넣지 말고
정리된 표와 한 줄 요약만 반환합니다.

model: haiku를 넣은 이유가 있습니다. 자료를 찾아 표로 정리하는 일은 복잡한 판단이 필요 없는 작업이라, 공식 문서가 안내하는 대로 더 빠르고 저렴한 모델로 라우팅해도 결과가 크게 달라지지 않습니다. tools도 읽기와 검색 계열로만 묶어, 이 서브에이전트가 실수로 파일을 고치는 일이 없게 했습니다.

저장한 뒤 "report-researcher 서브에이전트로 이번 달 자료부터 모아줘"처럼 요청하면 Claude가 위임을 판단합니다. 서브에이전트는 별도 컨텍스트에서 파일과 자료를 훑고, 표와 요약만 주 대화로 돌려줍니다. 그 결과를 받은 다음에야 지난 레슨의 monthly-report-draft 스킬로 넘겨 실제 초안을 씁니다. 진행되는 동안 주 대화창에는 위임했다는 표시(백그라운드로 돌면 "Backgrounded agent")와 하단의 에이전트 목록만 남고, 그 안에서 어떤 파일을 몇 개나 훑었는지는 보이지 않습니다 (2026년 8월 화면 기준). 감춘 게 아니라 애초에 그 정보가 주 대화의 컨텍스트로 넘어오지 않기 때문입니다.

주 대화창으로 돌아온 것은 이 정리된 표와 요약뿐입니다. 서브에이전트가 CSV를 몇 번 읽었는지는 여기 남지 않습니다.

스킬과 뭐가 다른가

레슨 1에서 다섯 장치가 헷갈리는 신호로 영어 자동완성 "subagents vs skills"를 짚었습니다. 이제 제대로 풀 차례입니다. 한 문장으로 구분하면 이렇습니다. 스킬은 무엇을 어떻게 할지 적어둔 절차서이고, 서브에이전트는 그 절차서를 포함해 일을 실제로 넘겨받아 처리하는 일꾼입니다.

둘은 겹치기도 합니다. 서브에이전트 frontmatter에 skills 필드를 적어두면 그 서브에이전트가 시작할 때부터 특정 스킬의 내용을 미리 읽어 들인 채로 시작합니다. 예를 들어 report-researcher가 매번 같은 표 형식을 참고해야 한다면, skills: [monthly-report-draft]처럼 적어 절차서를 미리 쥐어줄 수 있습니다. 스킬이 일하는 방법을 적은 문서라면, 서브에이전트는 그 문서를 들고 실제로 방을 나가 일하고 오는 사람인 셈입니다.

서브에이전트를 쓰지 않는 경우: 짧은 일, 실시간 조정

공식 문서가 서브에이전트를 쓰라고 권하는 조건은 하나로 좁습니다. 부작업이 검색 결과나 로그, 다시 참조하지 않을 파일 내용으로 주 대화를 채울 때입니다. 거꾸로 읽으면 언제 쓰면 안 되는지도 나옵니다.

짧은 확인 하나에 서브에이전트를 붙이면 오히려 손해입니다. 새 컨텍스트를 열고, 작업을 마친 뒤 결과를 다시 요약해 돌려주는 왕복 자체가 시간입니다. 파일 하나를 열어 값 하나만 확인하면 되는 일이라면 직접 하는 편이 빠릅니다. 계속 참조해야 하는 정보도 서브에이전트에 맡기지 않는 편이 낫습니다. 서브에이전트가 돌려주는 건 결과 요약뿐이라, 중간에 훑은 파일 내용을 뒤에서 다시 들여다봐야 하는 작업이라면 애초에 컨텍스트를 나누지 않는 게 맞습니다. 결과를 실시간으로 지켜보며 다음 지시를 바로바로 조정해야 하는 일도 마찬가지입니다. 서브에이전트는 맡긴 뒤 결과가 돌아올 때까지 중간에 끼어들기 어렵습니다.

기준을 하나로 정리하면 이렇습니다. 이 작업이 끝난 뒤에도 중간 과정을 다시 들여다볼 일이 있는가, 아니면 결과 요약 하나로 충분한가. 후자라면 서브에이전트로 떼어내도 되고, 전자라면 애초에 나누지 않는 편이 낫습니다. report-researcher가 돌려준 표는 그 자체로 초안 작성에 필요한 전부라 후자에 해당하지만, 만약 어떤 파일에서 그 숫자가 나왔는지 하나하나 다시 확인해야 하는 작업이었다면 서브에이전트에 맡기지 않았을 겁니다.

서브에이전트보다 더 큰 병렬 작업도 공식 문서에 있습니다. 여러 세션을 흩어두고 나중에 확인하는 에이전트 뷰, 여러 에이전트가 협업하는 에이전트 팀, 대규모 작업을 스크립트로 조율하는 동적 워크플로우입니다. 다만 이들은 대규모 오케스트레이션에 가까운 개발자 영역이라 이 트랙에서는 다루지 않습니다. 지금 단계에서 필요한 건 부작업 하나를 깨끗이 떼어내는 것으로 충분합니다.

서브에이전트가 필요해지는 순간은 사람마다 다르게 옵니다. 어떤 분은 스킬 하나가 도는 동안 아무것도 못 하고 기다리는 시간이 아까워서, 어떤 분은 조사 결과가 대화창을 가득 채워 정작 하려던 작업의 맥락이 밀려나서, 어떤 분은 앞 레슨에서 만든 스킬이 여러 개가 되면서 순서 조율이 버거워서 넘어옵니다. 제 경우는 첫 번째였습니다. 스킬을 매번 순서대로 돌리다 보니 대기 시간이 계속 생겨서, 데이터를 받아오고 조사해 오는 일은 그것만 하는 에이전트에게 위임하고, 글 쓰는 에이전트와 팩트체크하는 에이전트를 따로 두는 쪽으로 넘어갔습니다. 어느 계기로 오셨든 도착하는 답은 같습니다. 부작업을 떼어내면 주 대화는 가벼워지고 기다림은 겹쳐집니다.