클로드 코드 서브에이전트 사용법: 병렬 에이전트와 한도

AI에게 일을 맡기면 AI는 방금 쓴 질문만 읽지 않습니다. 앞에서 나눈 대화와 작업에 필요한 자료도 함께 봅니다. 이렇게 답을 만들 때 펼쳐 두는 정보 묶음을 컨텍스트라고 합니다. Claude Code(클로드 코드)는 대화 중에 파일도 열기 때문에 채팅 내용과 읽은 파일이 모두 이 묶음에 들어갑니다.

처음에는 파일 하나만 열었는데 자료를 찾아 달라고 할수록 읽은 내용이 쌓입니다. Claude Code는 다음 답을 만들 때 지금까지 쌓인 내용을 통째로 다시 읽습니다. 토큰은 AI가 읽고 쓰는 글의 양을 세는 단위입니다. 컨텍스트가 커지면 같은 질문에도 더 많은 토큰이 들고 사용 한도가 빨리 닳습니다.

이럴 때 Claude(클로드)는 서브에이전트라는 별도 도우미에게 일을 맡길 수 있습니다. 서브에이전트가 자기 공간에서 자료를 읽고 결과 요약만 돌려주면 조사 과정이 내 대화에 쌓이지 않습니다. 이 글에서는 이 원리부터 기본 서브에이전트, 직접 만드는 법, 여러 도우미가 함께 일하는 에이전트 팀까지 차례로 살펴보겠습니다.

이 글은 2026년 8월 24일, Claude Code 2.1.241 기준입니다. 에이전트 팀은 실험 기능이라 특히 자주 바뀝니다.

컨텍스트: 다시 읽는 대화와 파일

긴 메일에 답장하는 장면을 떠올려 보세요. 직전 메일 한 줄만 보는 게 아니라 아래에 이어진 이전 메일과 첨부 자료까지 다시 훑어야 합니다. Claude Code의 대화도 비슷합니다. 답을 한 번 더 받을 때마다 앞선 대화와 중간에 연 파일을 다시 읽습니다.

그래서 대화 중간에 로그 파일 하나를 열면 그 내용이 이후 모든 대화에 따라다닙니다. 다시 볼 일이 없어도 컨텍스트 안에 남아 있습니다. 자료를 많이 찾은 뒤 정작 글을 쓰거나 파일을 고치려 할 때 한도가 이미 줄어 있는 이유입니다.

서브에이전트: 조사 대신 요약 받기

서브에이전트는 이 흐름을 중간에서 끊습니다. 일을 맡기면 자기 공간에서 파일을 열고 내용을 정리합니다. 작업이 끝나면 내 대화에는 요약 한 덩어리만 돌아옵니다. 서브에이전트가 열어본 파일은 넘어오지 않습니다.

서브에이전트는 별도 공간에서 일하고 결과 요약만 돌려줍니다. 뒤진 과정은 내 대화에 쌓이지 않습니다.

직원에게 자료 조사를 시키는 것과 같습니다. 그 직원이 도서관에서 책 서른 권을 뒤졌더라도 나에게 오는 건 A4 한 장짜리 보고서입니다. 서른 권을 내 책상에 쌓아두지 않습니다. 공식 문서도 검색 결과나 로그처럼 다시 볼 일이 적은 자료가 주 대화를 채울 때 서브에이전트를 쓰라고 안내합니다.

한도가 빠듯한 플랜을 쓰신다면 이건 실질적인 절약입니다.

Claude Code에는 서브에이전트가 기본으로 들어 있습니다. Claude가 필요하다고 판단하면 알아서 부릅니다. 먼저 기본 구성을 알면 언제 별도 도우미가 움직이는지 이해하기 쉽습니다.

기본 구성: 세 가지 서브에이전트

읽기 전용은 파일을 찾아서 읽을 수는 있지만 고치지는 못한다는 뜻입니다. 계획 모드는 바로 수정하지 않고 무엇을 어떻게 할지 먼저 조사하는 상태입니다. 이 두 표현을 알고 아래 표를 보면 차이가 선명해집니다.

Explore와 Plan은 CLAUDE.md와 저장소 상태를 일부러 읽지 않습니다. CLAUDE.md는 Claude가 따라야 할 프로젝트 설명서입니다. 저장소 상태는 현재 어떤 파일이 바뀌었는지를 보여 주는 정보입니다. 조사만 하는데 이 자료까지 읽으면 토큰을 더 쓰기 때문입니다. 나머지 서브에이전트는 두 자료를 모두 읽습니다.

Explore에는 조사 깊이도 있습니다. 콕 집어 찾을 때는 quick, 적당한 범위는 medium, 샅샅이 훑을 때는 very thorough입니다. Claude가 맡길 일에 맞춰 이 셋 중 하나를 고릅니다.

직접 만들기: 설정 파일 한 개

같은 종류의 일을 반복해서 맡긴다면 나만의 서브에이전트를 만들 수 있습니다. 필요한 것은 마크다운 파일 하나입니다. 마크다운은 이 글처럼 제목과 본문을 간단한 기호로 구분해 적는 문서 형식입니다.

아래 경로에서 ~는 내 계정의 기본 폴더를 뜻합니다. 그 안의 .claude/agents/는 Claude Code가 서브에이전트 설정을 찾는 폴더입니다.

~/.claude/agents/code-reviewer.md

그 폴더에 code-reviewer.md라는 파일을 만들고 아래 내용을 넣습니다.

---
name: code-reviewer
description: 코드 품질과 모범 사례를 검토합니다. 코드를 쓰거나 고친 뒤에 사용합니다.
tools: Read, Glob, Grep
model: sonnet
---
 
당신은 코드 검토자입니다. 읽기 쉬운지, 예외 처리가 빠지지 않았는지,
같이 고쳐야 할 테스트가 있는지를 중심으로 봅니다.
발견한 것마다 심각도를 붙여 보고하세요.

위아래의 --- 사이에는 이 도우미의 설정이 들어갑니다. 그 아래에는 실제로 어떻게 일할지 적습니다. 설정 네 가지를 하나씩 보겠습니다.

name은 이 서브에이전트의 이름입니다. 파일 이름이 아니라 이 값이 식별자입니다.

description은 하는 일과 부를 시점을 적는 설명입니다. Claude는 이 문장을 보고 지금 맡길 일과 맞는지 판단합니다. 그래서 무엇을 하는지뿐 아니라 언제 쓰는지도 함께 적어야 잘 불립니다.

tools는 쓸 수 있는 도구를 제한합니다. 위 예시는 읽기 관련 도구만 줬으니 이 서브에이전트는 파일을 고칠 수 없습니다. 검토만 시킬 거라면 애초에 손을 못 대게 막아두는 편이 안전합니다.

model은 작업에 쓸 AI 모델을 정합니다. 단순한 일은 더 싼 모델로 돌리면 그만큼 아낄 수 있습니다. 공식 문서도 비용 통제를 서브에이전트의 장점으로 꼽습니다.

파일을 만들면 재시작할 필요 없이 몇 초 안에 잡힙니다. 다만 세션을 시작할 때 ~/.claude/agents/ 폴더 자체가 없었다면 그때는 재시작이 필요합니다.

~/.claude/agents/에 두면 모든 프로젝트에서 쓸 수 있습니다. 지금 작업하는 프로젝트 폴더 안의 .claude/agents/에 두면 그 프로젝트에서만 씁니다.

경로를 찾고 파일을 직접 쓰는 일이 부담스러우신가요? Claude에게 "코드를 검토하는 서브에이전트를 만들어 줘"라고 요청하면 파일을 대신 써 줍니다. 예전에 있던 /agents 생성 마법사는 없어졌습니다.

에이전트 팀: 서로 대화하는 병렬 작업

병렬 작업은 한 일이 끝난 뒤 다음 일을 시작하는 대신 여러 일을 같은 시간에 진행하는 방식입니다. 병렬 에이전트를 검색해서 오셨다면 여기서부터 찾으시던 내용일 겁니다.

서브에이전트는 일을 마치면 결과만 보고합니다. 서브에이전트끼리는 대화하지 않습니다. 여러 도우미가 동시에 일하면서 서로 의견까지 주고받아야 한다면 에이전트 팀이 필요합니다.

활성화: 꺼져 있는 실험 기능

먼저 경고부터 봐야 합니다. 에이전트 팀은 실험 기능이고 기본적으로 꺼져 있습니다. 켜려면 설정에 이 값을 넣어야 합니다.

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

JSON은 중괄호 안에 설정 이름과 값을 적는 형식입니다. 위 코드는 대화창이 아니라 Claude Code 설정에 넣습니다. 설정 파일을 직접 다루기 어렵다면 Claude에게 에이전트 팀 실험 기능을 켜 달라고 요청하고, 위 값을 함께 보여 주시면 됩니다.

켜고 나면 평소 말하듯 시키면 됩니다. 예를 들면 이렇습니다.

이 문제를 세 가지 관점에서 살펴볼 팀원 세 명을 만들어 줘.
한 명은 사용자 경험, 한 명은 기술 구조, 한 명은 반대 입장을 맡아 줘.

핵심 효과: 반대 입장의 동시 검토

에이전트 팀의 값어치는 "반대 입장"에 있습니다. 조사를 순서대로 하면 먼저 나온 이론에 끌려가기 쉽습니다. 하나가 그럴듯해 보이면 뒤의 조사도 그 이론에 맞춰질 수 있습니다. 여러 조사자가 동시에 서로의 이론을 반박하면 이야기가 달라집니다. 반박을 견디고 살아남은 이론이 진짜일 확률이 높아집니다.

원인을 모르겠는 문제를 붙들고 있을 때 특히 쓸모가 있습니다.

비용과 제약: 토큰 일곱 배, 세션당 한 팀

다만 팀은 비쌉니다. 인스턴스는 독립적으로 돌아가는 Claude 하나를 뜻합니다. 팀원마다 별도 인스턴스가 움직이기 때문에 토큰이 인원수에 비례해 늘어납니다. 팀원이 계획 모드로 돌면 일반 세션의 약 일곱 배를 쓴다고 공식 문서는 밝힙니다.

유휴 상태는 팀원이 일을 맡지 않고 기다리는 상태입니다. 이때도 토큰을 계속 씁니다. 일이 끝나면 팀을 정리해야 하는 이유입니다.

권장 규모는 세 명에서 다섯 명입니다. 문서는 "집중한 세 명이 산만한 다섯 명을 이기는 경우가 많다"고 적고 있습니다.

실험 기능이라 아직 막히는 곳도 있습니다. 켜기 전에 아래 제약을 확인해 두세요.

• 세션을 재개하면 팀원이 돌아오지 않습니다. /resume이나 /rewind는 팀원을 복원하지 않습니다. 재개한 리더가 이미 없는 팀원에게 말을 걸려 하면 새로 만들라고 지시하면 됩니다.
• 팀은 세션당 하나입니다. 여러 팀을 만들거나 세션끼리 팀을 공유할 수 없습니다.
• 팀원은 자기 팀원을 만들지 못합니다. 팀 관리는 리더만 합니다.
• 작업 상태가 늦게 바뀔 수 있습니다. 팀원이 작업을 완료로 표시하지 않아 뒤 작업이 묶이기도 합니다. 막힌 것 같으면 실제로 끝났는지 확인하고 상태를 직접 고치면 됩니다.
• 팀원마다 창을 나눠 보려면 tmux나 iTerm2가 필요합니다. VS Code 통합 터미널, 윈도우 터미널, Ghostty에서는 분할 창을 쓸 수 없습니다. 기본값인 한 터미널 안에서 돌리는 방식은 어디서나 됩니다.

사용 판단: 대화에서 팀까지

세 가지 선택지를 나란히 놓으면 이렇습니다.

저라면 순서를 이렇게 잡겠습니다. 대부분은 그냥 대화로 충분합니다. 자료 조사처럼 뒤지는 양이 많아지면 서브에이전트를 씁니다. 에이전트 팀은 원인을 모르겠는 문제나 여러 관점의 검토가 필요할 때만 꺼냅니다. 일상적인 작업에 팀을 쓰는 것은 낭비입니다.

순서대로 해야 하는 일에는 팀이 맞지 않습니다. 여러 사람이 같은 파일을 고치는 일이나 앞 작업이 끝나야 다음 작업을 할 수 있는 일도 마찬가지입니다. 이런 일에는 단일 세션이나 서브에이전트가 낫다고 공식 문서도 안내합니다.

제가 서브에이전트를 쓰기 시작한 계기는 대기 시간이었습니다. 작업을 하나씩 순서대로 돌리니 하나가 끝날 때까지 기다리는 구간이 계속 생겼습니다. 그래서 자료를 받아오고 조사하는 일을 떼어 별도 에이전트에게 맡겼습니다. 글을 쓰는 쪽과 사실을 확인하는 쪽도 따로 두었습니다. 기다림이 겹쳐지니 전체 시간이 줄었습니다.

다만 팀까지 꺼낼 일은 생각보다 드물었습니다. 대부분은 서브에이전트 선에서 끝났습니다.

문제 해결: 호출, 중복, 표시

호출 문제: 설명과 재시작

만든 서브에이전트를 Claude가 안 부릅니다. 대개 description 문제입니다. 무엇을 하는지만 적고 언제 쓰는지를 안 적으면 매칭이 안 됩니다. "코드를 쓰거나 고친 뒤에 사용합니다"처럼 시점을 넣어 보세요.

새로 만든 파일이 안 잡힙니다. 세션을 시작할 때 ~/.claude/agents/ 폴더가 아예 없었다면 재시작해야 합니다. 폴더가 이미 있었다면 몇 초 안에 잡힙니다.

이름이 겹칩니다. 같은 폴더 안에서 name이 겹치면 하나만 로드됩니다. /doctor를 실행하면 겹치는 파일을 찾아 알려 줍니다.

팀 표시: 유휴 상태와 오류

팀원이 안 보입니다. 패널의 팀원이 전부 유휴 상태가 되면 30초 뒤에 그 줄들이 숨겨집니다. 한 명이라도 일하는 중이면 숨겨지지 않습니다. 없어진 것이 아니라 가려진 것입니다. 이름을 불러 메시지를 보내면 다시 나타납니다. 셋 넘게 쉬고 있으면 초과 인원은 "몇 명이 유휴 상태"라는 한 줄로 접힙니다.

팀원이 오류에서 멈췄습니다. 팀원을 선택해 화면을 열어 보고 직접 지시를 주거나, 다른 팀원을 새로 만들어 이어받게 하면 됩니다.