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에게 만들어 달라고 부탁하면 됩니다.