Claude Code 서브에이전트 사용법언제 나누고 어떻게 정의하나

안녕하세요, muaco입니다.

Claude Code에게 큰일을 맡기다 보면 대화창이 금방 꽉 차요. 검색 결과와 로그가 쌓이면서 처음에 한 이야기를 Claude가 흐릿하게 기억하기 시작해요. 이럴 때 쓰는 기능이 서브에이전트예요. 오늘은 서브에이전트가 무엇인지, 언제 일을 나누는 게 좋은지, 파일 하나로 어떻게 정의하는지 차례로 볼게요.

한 줄로 말하면 따로 일하는 팀원이에요

회사에서 팀장이 "경쟁사 자료 좀 정리해 줘요" 하고 부탁하면, 팀원은 자기 자리에서 수십 개 문서를 읽어요. 팀장 책상에는 그 문서가 하나도 안 쌓여요. 정리된 보고서 한 장만 올라오죠.

Claude Code도 똑같아요. 지금 대화하고 있는 Claude가 팀장이고 따로 불려 나가 일하는 Claude가 팀원이에요. 이 팀원을 서브에이전트라고 불러요. 공식 문서는 서브에이전트를 자기만의 분리된 컨텍스트 창에서 특정 작업을 처리하는 전문 도우미로 설명해요. 컨텍스트 창은 AI가 한 번에 기억하고 볼 수 있는 책상 넓이라고 생각하면 돼요.

서브에이전트는 책상이 좁아서 생겼어요

AI의 책상은 넓이가 정해져 있어요. 파일 백 개를 뒤지고 테스트 로그 수천 줄을 읽으면 그 내용이 전부 책상에 올라와요. 정작 다시 볼 일 없는 자료인데도요. 그러면 원래 하던 이야기가 밀려나고 답이 점점 엉뚱해져요.

문서가 꼽는 장점은 이래요. 대화 맥락을 지키고 쓸 수 있는 도구를 좁혀 실수를 막아요. 한 번 만든 팀원을 여러 프로젝트에서 다시 쓰고, 쉬운 일은 Haiku처럼 빠르고 싼 모델에 넘겨 비용을 아낄 수 있어요.

일은 이렇게 흘러가요

핵심은 팀원마다 붙이는 설명(description)이에요. Claude는 이 설명을 읽고 "이 일은 저 팀원 담당이네" 하고 알아서 넘겨요. 설명에 "use proactively" 같은 말을 넣으면 더 적극적으로 맡긴다고 문서에 나와 있어요.

기본으로 들어 있는 팀원도 셋 있어요. 읽기만 하며 코드를 빠르게 뒤지는 Explore, 계획 모드에서 조사를 맡는 Plan, 여러 단계 작업을 다 하는 general-purpose예요. 따로 만들지 않아도 Claude가 필요할 때 이 셋을 불러 써요.

내 팀원을 만들려면 마크다운 파일 하나를 쓰면 돼요. 맨 위에 이름표를 붙이고 그 아래에 팀원에게 줄 업무 지시를 적어요. 문서에 실린 예시는 이래요.

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

name과 description은 꼭 있어야 해요. tools는 쓸 수 있는 도구 목록이고 이 줄을 아예 적지 않으면 모든 도구를 물려받아요. 위 예시는 읽기 도구만 줬으니 이 팀원은 파일을 고치지 못해요. model에는 sonnet, opus, haiku, fable 같은 별칭이나 claude-opus-5 같은 전체 모델 ID, inherit(지금 대화와 같은 모델)를 적어요. 생략하면 지금 대화의 모델을 써요.

파일을 두는 곳은 두 군데를 주로 써요. 이 프로젝트에서만 쓸 팀원은 .claude/agents/에, 모든 프로젝트에서 쓸 팀원은 ~/.claude/agents/에 넣어요. 같은 이름이 두 곳에 있으면 프로젝트 쪽이 이겨요. 프로젝트 폴더에 두면 git으로 팀 동료와 함께 쓸 수 있어요.

여기서 다들 한 번 멈칫해요. 예전 글에는 /agents 명령으로 만드는 화면이 나오는데, 문서에 따르면 v2.1.198부터는 이 명령이 화면을 열지 않고 파일 위치만 알려줘요. 지금은 파일을 직접 쓰거나 Claude에게 만들어 달라고 부탁하면 돼요.

나눌 때와 나누지 않을 때

문서는 기준을 꽤 분명하게 줘요. 서브에이전트가 맞는 경우는 이래요.

• 결과물이 길고 지저분한데 내 대화창에는 필요 없을 때. 테스트를 다 돌리고 실패한 것만 보고받는 일이 좋은 예예요.
• 도구나 권한을 좁혀 두고 싶을 때. 읽기만 해야 하는 검토 담당이 그렇죠.
• 일이 따로 떨어져 있어서 요약 한 장으로 돌려받으면 충분할 때.

반대로 지금 대화에서 바로 하는 편이 나은 경우도 있어요.

• 여러 번 주고받으며 다듬어야 하는 일. 팀원은 요약만 들고 오니 중간에 방향을 틀기 어려워요.
• 여러 단계가 같은 맥락을 많이 나눠 쓰는 일.
• 한두 줄 고치는 작은 일. 팀원을 새로 부르면 처음부터 자료를 다시 읽어서 오히려 느려요.
• 빨리 답을 받아야 할 때.

병렬로 돌릴 때 주의할 점

서로 관계없는 조사라면 여러 팀원을 동시에 보낼 수 있어요. "인증, 데이터베이스, API 모듈을 각각 다른 서브에이전트로 동시에 조사해 줘"처럼 부탁하면 돼요. 가장 느린 팀원이 끝나는 시간이면 전부 끝나요. 다만 몇 가지는 알고 시작하세요.

• 토큰 사용량이 늘어요. 팀원 수만큼 따로 일하니 사용량도 그만큼 불어나요. 요금제 한도에 빨리 닿을 수 있어요.
• 보고서도 책상을 차지해요. 팀원마다 긴 결과를 들고 오면 결국 내 대화창이 다시 차요. 그래서 "요약만", "실패한 것만"처럼 돌려받을 양을 정해 주는 편이 좋아요.
• 같은 파일을 동시에 고치면 부딪혀요. 이럴 땐 isolation: worktree를 적어 팀원마다 별도 작업 폴더(git worktree)를 주세요.
• 한꺼번에 돌 수 있는 수에 한도가 있어요. 기본은 동시에 20개예요.

팀원이 또 팀원을 부를 수도 있어요. 기본으로 지금 대화 아래 세 층까지 내려가요. 너무 깊어지면 무슨 일이 어디서 벌어지는지 알기 어려워지니, 처음에는 한 층만 쓰는 편이 마음 편해요.

첫걸음은 읽기 전용 팀원 하나

처음이라면 파일을 고치지 못하는 검토 담당 하나부터 만들어 보세요. Claude Code에 "읽기 전용이고 Sonnet을 쓰는 코드 검토 서브에이전트를 .claude/agents/에 만들어 줘"라고 부탁하면 Claude가 파일을 써 줘요. 그다음 이름이 code-reviewer라면 @"code-reviewer (agent)"처럼 @로 불러 일을 맡겨 보세요. @로 부르면 그 팀원이 반드시 실행돼요. 요약만 돌아오고 내 대화창이 깨끗하게 남는지 보면 이 기능이 왜 있는지 바로 감이 와요.

팀원을 잘 두면 팀장 책상이 가벼워져요. 다만 팀원이 많다고 일이 저절로 잘되지는 않아요. 나눌 일과 직접 할 일을 가르는 눈이 먼저예요.

이상으로 글 마치겠습니다.

출처

• Create custom subagents, Claude Code Docs
• Run agents in parallel, Claude Code Docs