클로드 에이전트 팀 만들기 — 서브에이전트로 역할 나누는 법 (2026)

“클로드 에이전트”로 검색하면 서로 다른 두 가지가 섞여 나옵니다. 하나는 Claude Cowork, 채팅창에서 작업을 통째로 맡기는 기능이고요. 다른 하나는 Claude Code의 서브에이전트, 역할이 다른 에이전트를 여러 개 만들어 두고 일을 나눠 주는 방식입니다. 말하자면 에이전트 팀을 꾸리는 것이죠. 긴 작업을 여러 단계로 쪼개서 돌리고 싶다면 찾으시는 건 뒤쪽입니다.

둘 중 어느 쪽을 찾고 있나

먼저 구분부터 하는 게 시간을 아낍니다.

	Claude Cowork	서브에이전트
어디서	claude.ai 웹·데스크톱·모바일 앱	Claude Code (제가 확인한 건 터미널)
쓰는 법	입력창에서 작업을 설명하면 끝	역할별 설정 파일을 만들어 둠
역할 나누기	작업을 쪼개 서브에이전트를 조율할 수 있다고 안내됨	역할별로 파일을 직접 만들어 둠
맞는 일	자료 조사, 파일 정리, 반복 업무	단계가 많고 오래 가는 작업
요금	Pro 이상 유료 플랜에 포함	같음

Cowork는 “이거 좀 해줘”에 가깝고, 서브에이전트는 “팀을 미리 꾸려 둔다”에 가깝습니다. 둘 다 작업을 쪼갤 수 있는데, 역할을 내가 직접 정의해 두느냐가 갈림길입니다. 단계마다 성격이 다른 작업을 반복한다면 서브에이전트 쪽이 손에 맞았습니다. 이건 제 기준이고 공식 안내에 적힌 구분은 아닙니다. 아래는 서브에이전트 이야기입니다.

서브에이전트가 실제로 해주는 것

핵심은 세 가지입니다.

첫째, 컨텍스트가 분리됩니다. 공식 문서는 “각 서브에이전트는 자체 컨텍스트 윈도우에서 실행된다”고 명시합니다. 더 정확히는 “새롭고 격리된 컨텍스트 윈도우로 시작하며, 대화 이력도, 이미 읽은 파일도 보지 않는다”고 돼 있고요. 로그나 검색 결과처럼 부피 큰 중간 산출물이 메인 대화를 밀어내지 않는다는 뜻입니다.

둘째, 모델을 따로 고를 수 있습니다. 문서에 “더 빠르고 저렴한 Haiku 같은 모델로 작업을 라우팅해 비용을 관리한다”고 적혀 있습니다. 단순 정리나 검색은 싼 모델에, 판단이 필요한 일은 비싼 모델에 맡기는 식이죠.

셋째, 도구와 권한을 묶어둘 수 있습니다. 읽기만 하면 되는 역할에 쓰기 도구를 쥐여 줄 이유가 없습니다. 역할마다 쓸 수 있는 도구를 정해 두면 사고가 줄어듭니다.

만드는 법 — 파일 하나면 됩니다

서브에이전트는 마크다운 파일 하나입니다. 프로젝트 안에서만 쓰려면 .claude/agents/, 모든 프로젝트에서 쓰려면 ~/.claude/agents/에 둡니다. 같은 이름이 양쪽에 있으면 프로젝트 쪽이 이깁니다. 두 폴더 모두 하위 폴더까지 훑기 때문에 agents/review/처럼 정리해 둬도 됩니다.

파일은 이렇게 생겼습니다.

---
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.

--- 아래 본문이 그 에이전트의 시스템 프롬프트입니다. 역할 설명은 여기에 씁니다.

제가 실제로 쓰는 파일

위 예시는 공식 문서의 샘플을 그대로 옮긴 것입니다. 제가 쓰는 건 이렇게 생겼습니다. 3D 애니메이션 작업에 쓰는 에이전트 중 하나예요.

---
name: character-designer
description: 캐릭터 디자이너. 캐릭터 컨셉, 캐릭터 시트(턴어라운드/표정 시트)를
  생성해 전체 샷의 캐릭터 일관성 기준을 만든다. 캐릭터 디자인·수정·표정 시트
  작업 시 사용.
model: sonnet
---

당신은 3D 애니메이션 캐릭터 디자이너다.

tools도 maxTurns도 없습니다. 이름, 설명, 모델 세 줄이면 돌아갑니다. 처음부터 다 채우려고 하면 시작을 못 합니다.

핵심은 description 한 줄입니다

제 파일 열 개를 다시 보니 description이 전부 같은 모양이었습니다.

무슨 역할인지  +  뭘 만드는지  +  "~할 때 사용"

마지막 조각이 제일 중요합니다. 클로드는 이 설명을 읽고 “지금 이 에이전트를 부를 때인가”를 판단합니다. 그래서 역할만 적고 끝내면 안 불립니다. 언제 부르는지를 적어야 불립니다.

제 파일에서 시 사용 또는 할 때 사용으로 끝나는 게 열 개 중 아홉 개였습니다. 의식하고 쓴 건 아닌데, 잘 불리는 것들이 공교롭게 그 모양이더군요.

역할을 어떻게 쪼갰나 — 제 팀 열 명

추상적으로 “역할을 나누라”고만 하면 막막하니, 제가 실제로 만든 걸 그대로 적습니다. 3D 애니메이션 한 편을 만드는 조직이고, 아래 열 명과 별개로 총괄 역할을 하나 더 뒀습니다.

에이전트	하는 일	모델
story-writer	로그라인·시놉시스·시나리오	opus
storyboard-artist	시나리오를 샷 리스트와 스토리보드로	sonnet
art-director	룩앤필·조명·색보정 기준을 정하고 검수	opus
character-designer	캐릭터 컨셉과 시트	sonnet
character-sheet-artist	턴어라운드·표정 시트로 드리프트 교정	sonnet
environment-designer	씬별 배경 컨셉	sonnet
animator	샷별 키프레임과 영상 생성	sonnet
editor	컷 편집 설계와 모션그래픽	sonnet
sound-designer	음악·효과음·앰비언스	sonnet
qc-reviewer	산출물을 기준 문서와 대조	sonnet

쪼갠 기준은 “공정”입니다. 기능이 아니라요. 영상은 기획 → 보드 → 디자인 → 생성 → 편집 → 검수로 흘러가는데, 그 흐름의 한 칸을 한 명으로 잡았습니다. 제가 영상을 업으로 하고 있어서 어떤 칸이 필요한지는 처음부터 알았습니다.

두 가지만 짚어 두겠습니다.

모델이 다릅니다. 기준을 정하는 자리(story-writer, art-director)만 opus고 나머지는 sonnet입니다. 판단이 들어가는 자리와 시키는 대로 만드는 자리를 나눈 거예요.

검수 담당을 따로 뒀습니다. qc-reviewer는 만들지 않고 대조만 합니다. 만드는 쪽에 검수를 맡기면 자기 결과물을 통과시킵니다.

설정 항목, 뭘 넣을 수 있나

필수는 name과 description 둘뿐입니다. 나머지는 필요할 때만 넣으면 됩니다.

항목	필수	넣는 값
name	예	code-reviewer 같은 고유 이름. :은 못 씁니다
description	예	언제 이 에이전트를 부를지. 짧게 써야 합니다
tools	아니오	Read, Grep, Bash 식. 안 적으면 쓸 수 있는 도구를 전부 물려받습니다
disallowedTools	아니오	뺄 도구. tools보다 먼저 적용되고, 남은 도구 풀에서 tools가 해석됩니다
model	아니오	sonnet·opus·haiku·fable·inherit 또는 claude-opus-5-5 같은 전체 ID
permissionMode	아니오	default·acceptEdits·plan·bypassPermissions 등
maxTurns	아니오	몇 턴까지 돌릴지. 넘으면 결과가 ‘부분 완료’로 표시됩니다
memory	아니오	user·project·local. 세션이 바뀌어도 기억을 남깁니다
effort	아니오	low~max. 세션 설정보다 우선합니다
skills	아니오	시작할 때 미리 읽혀둘 스킬

tools를 안 적으면 전부 물려받는다는 점은 기억해 두는 게 좋습니다. 권한을 좁히고 싶다면 명시적으로 적어야 합니다.

부르는 법은 세 가지

맡겨두기. 그냥 일을 시키면 클로드가 description을 보고 알아서 고릅니다. 그래서 설명을 어떻게 쓰느냐가 중요합니다.

지정해서 부르기. “test-runner 서브에이전트로 실패한 테스트를 고쳐줘”처럼 @agent-code-reviewer처럼 @로 콕 집으면 그 에이전트가 반드시 돕니다. 이름만 말하는 경우는 보통 위임되지만 반드시는 아닙니다.

세션 통째로. claude --agent code-reviewer로 시작하면 그 세션 전체가 해당 에이전트로 돕니다.

팀을 어떻게 구성할까

파일 만드는 법보다 어려운 건 역할을 어디서 끊느냐입니다. 몇 개를 만들지 정답은 없지만, 실제로 써보면서 정리한 기준은 이렇습니다.

작업 단계로 끊습니다. 기능으로 나누면 경계가 흐려집니다. “조사하는 애”, “쓰는 애”처럼 나누면 둘 다 조사하고 둘 다 씁니다. 대신 내 작업이 실제로 거치는 단계를 그대로 옮기면 경계가 분명해집니다. 영상이라면 기획·미술·캐릭터·배경·콘티·촬영·사운드·편집처럼요.

한 역할이 한 폴더를 봅니다. 역할마다 다루는 파일이 갈리면 충돌이 줄어듭니다. 폴더를 단계 번호로 나눠 두면 더 선명해지고요.

모델은 역할마다 다르게 답니다. 파일 정리나 목록 뽑기는 저렴한 모델로 충분하고, 판단이 필요한 자리에만 비싼 모델을 붙입니다. model 한 줄이면 됩니다.

총괄을 둘 거라면 “직접 하지 마라”를 명시합니다. 이게 제일 자주 어긋나는 지점입니다. 아래 “직접 해보니”에 그 이야기를 적어뒀습니다.

알아둘 제한들

여기부터는 숫자가 나옵니다. 넘길 일 없으면 읽지 않으셔도 됩니다.

• 설명 총량 15,000토큰. 서브에이전트들의 description을 다 합쳐 이 선을 넘으면 시작할 때 경고가 뜹니다. 문서는 “description을 줄이고 세부 내용은 각 서브에이전트의 시스템 프롬프트로 옮기라”고 안내합니다. 시스템 프롬프트는 그 에이전트가 실제로 돌 때만 로드되거든요.
• 중첩은 3단계까지. 서브에이전트가 또 서브에이전트를 부르는 깊이는 기본 3단계입니다. 한계에 닿으면 더 못 부르고 자기가 끝냅니다.
• 동시 실행은 20개까지. 넘기면 “Concurrent subagent limit reached” 오류가 납니다.
• 파일이 조용히 무시될 수 있습니다. name이 없거나, 여는 ---가 첫 줄이 아니거나, YAML이 깨지면 화면에 에러가 뜨지 않고 그냥 안 읽힙니다. 이유는 디버그 로그에만 남습니다. 만들었는데 안 불린다면 여기부터 보세요.

직접 해보니

여기까지는 공식 문서 내용입니다. 아래는 제가 직접 겪은 이야기입니다. AI로 3D 애니메이션 한 편을 만드는 9단계 중 조직을 짜는 부분에 해당합니다.

저는 개인 프로젝트로 3D 애니메이션을 만들면서 이 방식으로 조직을 짰습니다. 영상은 작업 단계가 잘게 나뉘는 영역이라, 에이전트 하나를 팀원 한 명으로 생각했어요. 지금 영상 만드는 일을 업으로 하고 있어서 어떤 역할이 필요한지는 처음부터 끝까지 압니다. 그래서 초기 세팅은 제가 직접 제안했습니다. 역할은 아홉 가지로 시작했고, 지금은 열 개가 됐습니다.

총괄 역할도 하나 뒀습니다. 처음에는 실제 팀의 팀장처럼 굴었어요. 제가 말한 걸 아래 에이전트들에게 잘 전달하는 듯했습니다. 이렇게 만든 데는 이유가 있습니다. 총괄에 쓰는 모델이 토큰을 많이 먹는데, 모든 대화와 작업을 그쪽으로 몰면 낭비가 심할 것 같았거든요.

그런데 중간쯤부터 토큰이 이상하게 빨리 닳았습니다. 그래서 물어봤어요. 지금 나는 너하고만 이야기하고, 너는 아래 에이전트들을 시켜서 일을 하고 있는 게 맞냐고. 그랬더니 사실은 자기가 직접 일하고 있었다고 하더군요. 위임을 시켰는데 혼자 다 하고 있었던 겁니다. 작업이 길어지고 수정이 많아지면서 그렇게 된 게 아닐까 싶습니다. 중간중간 역할 정의를 다시 해줘야 말을 알아듣는 것 같아요. 토큰이 어디서 새는지는 따로 적어뒀습니다. 정확히 재 본 건 아니고 체감입니다.

폴더 구조는 기대 이상이었습니다. 제가 시키지 않았는데 에이전트가 알아서 작업 단계별로 폴더를 나눠줬어요. 01_story, 02_art, 03_characters처럼 번호를 붙여서요. 이게 보기에 매우 편했습니다. 어느 단계 파일인지 폴더 이름만 봐도 알게 되니까요.

다만 여기서 다음 숙제가 생겼습니다. 수정 컷을 넣고, 설정집을 갱신하고, 규칙을 새로 만들 때마다 히스토리가 쌓여서 용량이 계속 늘어납니다. 작업이 길어질수록 가파르게 늘어요. 이걸 어떻게 정리할지가 지금 남은 과제입니다.

도구를 나눈 기준도 적어둘게요. 캐릭터와 배경은 미드저니로 직접 뽑았고, 영상 생성 쪽은 자동으로 돌렸습니다. 이 프로젝트에서는 그렇게 쓰고 있는데, 다음번에는 영상 쪽도 제가 조금 더 직접 다뤄볼 생각입니다. 요즘 나온 다른 툴도 그 자리에 맞을 것 같아서 써보려 하고요. 클로드에만 너무 기대면 프로젝트가 산으로 가는 기분이 들어서입니다.

자주 묻는 질문

클로드 에이전트와 Claude Code는 같은 건가요

Claude Code는 개발자용 에이전트 도구이고, 서브에이전트는 그 안에서 역할을 나누는 기능입니다. Cowork는 코딩 밖의 일반 업무로 이 방식을 넓힌 별도 기능이고요. 셋 다 “작업을 맡긴다”는 점은 같지만 쓰는 곳이 다릅니다.

서브에이전트를 만들었는데 안 불립니다

먼저 파일이 읽혔는지 보세요. name이 없거나, 여는 ---가 첫 줄이 아니거나, YAML이 깨졌으면 화면에 에러가 뜨지 않고 그냥 안 읽힙니다. 이유는 디버그 로그에만 남습니다. 파일이 멀쩡하다면 description을 보세요. 클로드가 이 설명을 보고 고르기 때문에, 언제 쓰는 에이전트인지가 분명해야 합니다. 확실히 돌려야 할 때는 @agent-이름으로 직접 부르면 됩니다.

서브에이전트를 많이 만들면 느려지나요

설명이 쌓이면 부담이 됩니다. 전체 description 합이 15,000토큰을 넘으면 시작할 때 경고가 뜹니다. 설명은 짧게 쓰고 세부 지시는 시스템 프롬프트로 내리세요. 그쪽은 해당 에이전트가 실제로 돌 때만 읽힙니다.

무료 플랜에서도 쓸 수 있나요

공식 안내에서는 Pro 이상 유료 플랜 기능으로 소개하고 있습니다. 정확한 조건은 claude.com/pricing에서 직접 확인하시길 권합니다.

정리

• “클로드 에이전트”는 Cowork와 서브에이전트 두 가지를 가리킵니다. 단계가 많고 오래 가는 작업이라면 서브에이전트 쪽입니다.
• 서브에이전트는 각자 별도의 컨텍스트 윈도우에서 돌아서, 부피 큰 중간 결과가 메인 대화를 밀어내지 않습니다.
• 파일 하나면 만들어집니다. 필수는 name과 description 둘뿐이고, model로 역할마다 다른 모델을 붙일 수 있습니다.
• tools를 안 적으면 도구를 전부 물려받습니다. 권한을 좁히려면 명시해야 합니다.
• 설명 총량 15,000토큰, 중첩 3단계, 동시 실행 20개가 선입니다.
• 역할을 나눴다고 끝이 아닙니다. 총괄이 위임하지 않고 혼자 일하는 일이 실제로 생기므로, 중간중간 역할 정의를 다시 해주는 게 필요합니다.