서브에이전트: 일을 나누면 정말 빨라지는가

서브에이전트 뜻: 한 줄 정의#

서브에이전트는 하네스가 제공하는 도구 자체가 아니라 하위 목표를 수행하는 별도 작업 주체입니다. Claude Code 서브에이전트 문서는 별도 대화, 병렬 작업과 도구 제한의 예를 설명합니다. 이는 해당 문서의 동작이며 모든 제품에 동일하게 적용된다는 뜻은 아닙니다. 확인일: 2026-11-02.

1. 결과가 서로 필요한지 확인하고 독립적인 하위 작업만 분리합니다.
2. 각 작업에 목표, 파일 범위, 금지 작업, 필요한 맥락과 보고 형식을 명시합니다.
3. 반환된 근거와 변경 사항을 검토하고 충돌을 해결한 뒤 전체 결과를 검증합니다.

Claude Code 서브에이전트 문서에 따르면 각 서브에이전트는 자기 컨텍스트 창, 사용자 지정 시스템 프롬프트, 제한된 도구 접근, 독립된 권한을 가집니다. 서브에이전트가 보내는 요청도 메인 대화와 같은 사용량 한도에 더해집니다(2026-11-03 확인).

새 서브에이전트는 메인 대화 기록, 이미 호출한 스킬, 이미 읽은 파일을 보지 못합니다. Claude가 쓴 위임 메시지와 자기 시스템 프롬프트에서 출발하고, 여기에 CLAUDE.md 파일, git 상태 스냅샷, 미리 불러온 스킬이 더해집니다. 예외는 부모 대화를 물려받는 포크입니다. Explore와 Plan은 CLAUDE.md와 git 상태 스냅샷을 빼고 시작해 탐색을 가볍게 유지합니다. 서브에이전트는 Claude Code 기본 시스템 프롬프트가 아니라 자기 프롬프트와 작업 디렉터리 같은 환경 정보만 받으며, 포크를 제외하고 출력 스타일도 적용되지 않습니다.

내장 유형은 셋입니다. Explore는 읽기 전용 도구만 쓰며 쓰기와 편집이 거부되고, Plan은 계획 모드에서 조사만 맡으며 역시 편집이 거부됩니다. general-purpose는 서브에이전트가 쓸 수 있는 모든 도구를 가집니다. 내장 서브에이전트는 메인 대화의 권한 규칙을 상속받고, 설정이 없으면 Claude가 메인 대화에서 띄운 서브에이전트는 백그라운드에서 실행됩니다. 백그라운드 서브에이전트는 내장 도구 집합이 더 좁고, 사용자에게 질문하는 AskUserQuestion 같은 도구는 서브에이전트에서 제거됩니다.

Explore를 부를 때 Claude는 조사 깊이를 quick(빠른 조회), medium(균형 잡힌 탐색), very thorough(포괄적 분석) 가운데 하나로 정합니다. Explore의 모델은 기본적으로 메인 대화 모델을 따르므로, 같은 이름의 정의 파일에 model: haiku를 적으면 탐색만 낮은 비용의 모델로 돌릴 수 있습니다. Plan은 계획 모드에서 메인 대화가 읽기 전용으로 남은 채 코드베이스 조사를 맡아, 탐색 결과가 별도 컨텍스트 창에 머물게 합니다. Claude는 description을 보고 위임 시점을 정하므로, 자동 위임을 기대한다면 description에 'use proactively' 같은 문구를 넣으라고 문서는 권합니다. 설명의 합계가 15,000 토큰을 넘으면 세션 시작 때 경고가 뜨므로 설명은 짧게 써야 합니다. 특정 내장 유형을 막으려면 permissions.deny에 그 유형을 적고, 위임 자체를 막으려면 Agent 도구를 거부합니다.

왜 중요한가: 한국 개발자 기준#

작업을 나누면 각자 조사한 내용이 상위 대화에 모두 쌓이지 않을 수 있지만, 중요한 제약도 자동으로 전달된다고 가정하면 안 됩니다. 추가 모델 호출과 결과 통합이 필요할 수 있으므로 속도와 비용의 이득은 실제 작업으로 확인하세요.

위임 지시가 얇으면 작업이 겹칩니다. Anthropic은 자사 리서치 시스템을 설명하면서 리드 에이전트가 서브에이전트마다 목표, 출력 형식, 사용할 도구와 출처, 작업 경계를 함께 줘야 한다고 말합니다. '반도체 부족을 조사하라'처럼 짧게 지시했을 때는 한 서브에이전트가 2021년 자동차 칩 대란을 파고드는 동안, 다른 두 서브에이전트가 2025년 공급망을 중복 조사했다고 합니다(Anthropic 다중 에이전트 리서치 글, 2026-11-03 확인).

비용은 서브에이전트 수에 따라 늘어납니다. 같은 글은 리서치 시스템의 내부 데이터에서 에이전트가 채팅보다 약 4배, 다중 에이전트 시스템은 약 15배의 토큰을 쓴다고 보고합니다. 이 수치는 그 시스템의 데이터이므로 다른 작업에 그대로 곱할 수 없습니다. Claude Code 비용 문서도 서브에이전트의 요청이 메인 사용량에 더해진다고 적고, 단순한 조사 작업에는 model: haiku를 지정하라고 권합니다. Pro, Max, Ultra, Team, Enterprise 구독에서는 /usage 화면에 서브에이전트가 최근 사용량에서 차지한 비율이 표시됩니다.

코딩 작업은 리서치보다 병렬화의 이득이 작을 수 있습니다. 같은 글은 대부분의 코딩 작업에 리서치보다 진짜로 병렬화할 수 있는 부분이 적고, LLM 에이전트가 다른 에이전트를 실시간으로 조율하고 위임하는 능력도 아직 충분하지 않다고 말합니다.

Claude Code 문서는 메인 대화에서 처리하는 편이 나은 경우를 먼저 꼽습니다. 잦은 주고받기나 반복 수정이 필요할 때, 계획·구현·테스트처럼 여러 단계가 같은 맥락을 공유할 때, 작은 수정을 빠르게 할 때입니다. 반대로 실행 결과가 길어 메인 맥락에 둘 필요가 없을 때, 도구를 제한해야 할 때, 작업이 독립적이어서 요약만 돌아오면 될 때는 서브에이전트가 맞습니다. 이미 대화에 있는 내용을 묻는 경우라면 도구 없이 전체 맥락을 보는 /btw가 더 가볍습니다.

문서가 드는 공통 패턴은 세 가지입니다. 긴 출력을 격리하는 방식은 테스트를 돌리고 실패한 테스트와 오류 메시지만 보고받는 식입니다. 병렬 조사는 조사 경로가 서로 의존하지 않을 때 잘 맞으며, 결과가 길면 메인 맥락을 많이 차지할 수 있다고 경고합니다. 체인 방식은 앞 서브에이전트의 결과를 Claude가 받아 다음 서브에이전트에 넘기는 순차 흐름입니다.

예제: 코드나 터미널로 보기#

예를 들어 한 작업에는 인증 코드의 호출 경로를, 다른 작업에는 관련 테스트의 범위를 읽기 전용으로 조사하게 하고 두 보고서를 합칠 수 있습니다. 이후 수정은 조사 결과가 준비된 뒤 별도로 결정합니다. 이는 설계 예시이며 실제 실행이나 시간 측정 결과는 아닙니다.

아래 정의도 실행하지 않은 설계입니다. 호출 경로 조사용 서브에이전트에는 tools: Read, Grep, Glob만 허용하고, 테스트 범위 조사용에는 disallowedTools: Write, Edit를 둘 수 있습니다. 문서에 따르면 tools 목록에 맞는 도구가 하나도 없으면 Claude Code는 대개 실행을 거부하고, 필드 이름이 틀린 항목은 오류 없이 무시됩니다. 정의 파일을 만든 뒤에는 필드 이름부터 확인해야 하는 이유입니다.

정의 파일에는 maxTurns로 턴 수 한도를 둘 수 있습니다. 한도에 닿으면 서브에이전트는 멈추고 결과는 부분 결과로 표시되며, Claude가 같은 서브에이전트를 이어서 실행할 수 있습니다. skills 필드에 적은 스킬은 설명만이 아니라 전체 내용이 시작할 때 들어갑니다.

위임 메시지에는 목표, 출력 형식, 도구와 출처, 작업 경계를 적습니다. 목표는 인증 요청이 거치는 함수를 찾는 것, 출력 형식은 파일 경로와 줄 번호와 근거 문장, 도구와 출처는 인증 모듈 디렉터리와 관련 테스트 파일, 작업 경계는 파일 수정과 테스트 실행 금지입니다. 이 가운데 출처나 경계가 빠지면 두 서브에이전트가 같은 파일을 반복해서 읽는 식으로 작업이 겹칩니다.

모델은 Claude가 호출할 때 넘긴 model 값, 정의 파일의 model, CLAUDE_CODE_SUBAGENT_MODEL 환경 변수, 메인 대화의 모델 순서로 정해집니다. 조사용 서브에이전트에 낮은 비용의 모델을 고정하려면 정의 파일의 값만으로는 부족하고, 호출 쪽에서 model을 넘기지 않는지도 함께 확인하세요. 서브에이전트는 메인 대화의 작업 디렉터리에서 시작하지만, 서브에이전트 안에서 실행한 cd는 다음 Bash 호출에 이어지지 않습니다.

메인 대화가 받는 것은 요약뿐입니다. 서브에이전트의 전체 기록은 메인 대화와 별도 파일로 남아 있어, 요약이 의심스러우면 그 기록에서 실제 도구 호출을 확인할 수 있습니다. 메인 대화가 압축되어도 서브에이전트의 기록 파일은 영향을 받지 않습니다.

관련 용어#

에이전트 하네스는 모델과 도구를 잇는 실행 환경입니다. 워크트리는 별도 작업 디렉터리를 만드는 Git 기능으로, 서브에이전트나 안전한 통합을 자동으로 보장하지 않습니다.

포크(fork)는 부모 대화를 물려받는 서브에이전트입니다. 일반 서브에이전트가 새 컨텍스트에서 출발하는 것과 달리, 포크는 지금까지의 대화를 그대로 가지고 시작합니다. 에이전트 팀은 서브에이전트와 다른 기능입니다. 여러 Claude Code 인스턴스가 각자 컨텍스트 창을 갖고 함께 일하며, Claude가 띄우고 감독합니다. 비용 문서는 팀원이 계획 모드에서 돌면 표준 세션보다 약 7배의 토큰을 쓴다고 설명합니다. Anthropic은 리드 에이전트가 서브에이전트를 조율하는 구조를 오케스트레이터-워커 패턴이라고 부르며, 리드가 작업을 나눠 위임하고 워커의 결과를 모아 답을 만든다고 설명합니다.

같은 서브에이전트에 이어서 일을 맡기려면 새로 호출하지 말고 재개(resume)를 요청해야 합니다. 호출할 때마다 새 인스턴스가 만들어지고, 재개한 서브에이전트는 이전 도구 호출과 결과까지 포함한 대화 기록을 유지합니다. Claude는 재개할 때 SendMessage 도구에 에이전트 ID나 이름을 넘깁니다. 내장 Explore와 Plan은 한 번 쓰고 끝나는 구조여서 재개할 수 없습니다.

서브에이전트는 한 세션 안에서만 작동합니다. 독립된 세션을 여러 개 병렬로 띄우고 한 화면에서 지켜보려면 백그라운드 에이전트를, 세션끼리 메시지를 주고받으려면 세션 간 메시지 기능을 씁니다.

조사와 통합의 의존 관계 도식#

앞의 인증 오류 사례를 작업 관계로 표시하면 아래와 같습니다. 실제 병렬 실행이나 시간 측정 결과가 아닌 설계 예시입니다.

같은 기준 상태와 승인 범위
        ├─ 호출 경로 조사 ─┐
        └─ 테스트 범위 조사 ┤
                          ↓
                 근거 대조와 계약 결정
                          ↓
                 승인된 작은 구현
                          ↓
                 통합 diff와 실제 검사

두 조사는 함께 시작할 수 있어도 계약 결정 이후의 구현은 앞선 결과를 기다립니다. 도식을 실제 작업에 적용하려면 파일과 공유 자원의 소유 범위도 따로 정하세요.

동시 실행과 중첩 깊이에도 제한이 있습니다. 서브에이전트 문서에 따르면 한 세션에서 동시에 도는 서브에이전트는 기본 20개로 제한되고, 한도를 넘으면 새 호출이 Concurrent subagent limit reached 오류로 실패합니다. 서브에이전트가 다시 서브에이전트를 띄울 수 있는 깊이는 메인 대화 아래 세 단계가 기본입니다. 두 값은 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS와 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH로 바꿀 수 있고, 전체 생성 횟수에는 제한이 없습니다. 대화형 세션에서 중첩된 서브에이전트가 있으면 사용자에게는 최상위 서브에이전트의 요약만 돌아옵니다.

결과가 돌아오는 방식도 통합 비용을 바꿉니다. 전경 서브에이전트는 끝날 때까지 메인 대화를 멈추고 권한 질문도 그대로 넘깁니다. 백그라운드 서브에이전트의 권한 질문은 메인 세션에 뜨면서 묻는 서브에이전트의 이름이 표시되고, Esc를 누르면 그 호출 하나만 거부되며 서브에이전트는 계속 돕니다. 백그라운드 결과는 나중 턴에 완료 알림으로 도착하고, 그 전에 진행 상황을 물으면 아직 실행 중이라는 답을 받습니다. 백그라운드 서브에이전트의 권한 질문에 세션 동안 유지되는 허용을 고르면, 그 답은 메인 대화를 포함한 세션 전체에 적용됩니다. 백그라운드에서 시작한 Bash 명령은 서브에이전트의 턴이 끝난 뒤에도 돌 수 있으며, 끝나면 Claude Code가 서브에이전트에 알림을 보냅니다.

Claude Code는 서브에이전트의 최종 보고를 Claude가 읽기 전에 한 번 훑습니다. 서브에이전트는 사용자가 검토하지 않은 파일, 웹 페이지, 명령 출력을 읽었을 수 있고, 그 안의 문장에 메인 대화를 향한 지시가 섞였을 수 있기 때문입니다. 이 검사는 내용을 지우거나 바꾸지 않고 표시만 붙이며, 보고가 지시한 도구 호출도 권한 검사와 샌드박스를 그대로 거칩니다.

권한 측면에서도 서브에이전트는 메시지로 승인을 얻을 수 없습니다. 어떤 에이전트의 메시지도 대기 중인 권한 질문의 승인으로 간주되지 않고, 서브에이전트의 권한 설정, CLAUDE.md, 구성은 메시지로 바꿀 수 없습니다. 승인은 권한 체계나 사용자 자신의 메시지로만 가능합니다.

Anthropic의 리서치 시스템은 리드 에이전트가 서브에이전트 묶음이 끝날 때까지 기다리는 동기 실행을 씁니다. 리드가 실행 중인 서브에이전트를 조정하기 어렵고, 한 서브에이전트가 느리면 전체가 멈출 수 있다고 그 글은 적습니다. 같은 글은 중간 결과를 파일로 남기고 참조만 넘겨 중계 과정에서 정보가 빠지는 일을 줄이는 방식을 소개합니다.

병렬 편집이 서로 겹치는 문제는 정의 파일에 isolation: worktree를 적어 줄일 수 있습니다. 워크트리 문서에 따르면 이 서브에이전트는 임시 Git 워크트리에서 실행되며, 변경이 없으면 자동으로 정리되고 변경이 있으면 정리 주기 전까지 디스크에 남습니다.

서브에이전트에 일을 나눌 때는 어떤 작업이 독립적으로 끝나는지, 어떤 작업이 다른 작업의 결과나 공유 파일을 필요로 하는지 먼저 구분합니다. 의존이 없는 작업은 병렬로, 순서가 있는 작업은 단계별로 나누는 것이 실행 범위를 예측하기 쉽습니다. 같은 모델이라도 서브에이전트별 허용 도구와 작업 모드, 최대 턴 수가 다르면 같은 작업도 결과가 달라질 수 있으니, 이 글에서 확인하지 않은 지원 여부와 성능은 실제 실행으로 확인하세요.

다음에 읽을 것#

서브에이전트의 사용 가능 여부와 권한 상속, 병렬 실행 방식은 제품과 설정마다 다릅니다. Mirr Code의 서브에이전트 지원 여부와 실제 병렬 성능은 이 글에서 아직 확인하지 않았습니다.

정의 파일에 쓸 수 있는 필드(tools, disallowedTools, model, permissionMode, maxTurns, isolation 등)와 허용되는 값은 서브에이전트 문서의 필드 표에서 확인할 수 있습니다. 서브에이전트마다 워크트리를 따로 주는 방식은 워크트리 글에서 이어 살펴보세요.

편집 메모 (2026-11-02): 의존 작업·공유 파일·통합 비용의 FAQ를 보충했습니다. 실제 분할 도식과 순차·병렬 소요 시간, Mirr 지원 근거는 아직 필요합니다.