# Claude Code에서 중첩 하위 에이전트로 대규모 작업을 위임하는 방법

> Claude Code v2.1.172에서는 하위 에이전트가 최대 5단계 깊이까지 자체 하위 에이전트를 생성할 수 있습니다. 대규모 작업을 위임하는 방법을 안내합니다.

Source: https://ailoot.ai/blog/ko/claude-code-nested-subagents/
Canonical: https://ailoot.ai/blog/ko/claude-code-nested-subagents/
Language: ko
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-232
Revision: sha256-9226c575461bac934a81bd31ffe1e702684a40a9b784d7345d1a6a55c9b77d15


<div class="aside" data-semantic="editorial-reference" role="note" aria-label="Ailoot 문서">

[Ailoot 문서](https://ailoot.ai/docs/) — 서비스 사용에 관한 참고 자료입니다.

</div>

## Claude Code v2.1.172에서 무엇이 바뀌었나요?

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="이 섹션의 핵심 요점">

핵심 요점

Anthropic은 Claude Code v2.1.172를 출시하고, 변경 로그 한 줄로 2년 된 규칙을 없앴습니다. 이제 하위 에이전트가 최대 5단계 깊이까지 자체 하위 에이전트를 생성할 수 있습니다. 이 기능의 목적은 속도나 CPU 추가가 아닙니다. 핵심은 시끄러운 준비 작업이 메인 컨텍스트를 어지럽히지 않도록 하는 것입니다.

</div>

지난 몇 달 동안 Claude Code의 AI 에이전트에 관한 글을 하나라도 읽었다면 같은 문구를 접했을 겁니다. 공식 문서에도, 제가 쓴 [하위 에이전트 가이드](https://ailoot.ai/blog/ko/claude-code-subagents/)에도, 경쟁사 분석에도 빠짐없이 등장합니다. 문구는 이렇습니다. “하위 에이전트는 또 다른 하위 에이전트를 생성할 수 없다.” 2026년 6월 11일 현재, `code.claude.com/docs/en/sub-agents`의 세 곳에 이 문구가 여전히 남아 있습니다. Anthropic이 아직 업데이트하지 않았을 뿐입니다.

6월 10일 20:44 UTC, Claude Code v2.1.172가 GitHub Releases에 올라왔습니다. 주요 변경 로그 항목은 한 줄이었습니다.

<figure>
<blockquote>
이제 하위 에이전트가 최대 5단계 깊이까지 자체 하위 에이전트를 생성할 수 있습니다.
</blockquote>
<figcaption>— Claude Code 변경 로그, https://github.com/anthropics/claude-code/releases/tag/v2.1.172</figcaption>
</figure>

같은 릴리스에서는 중첩이 아니면 발생할 수 없는 버그도 수정했습니다. 백그라운드 하위 에이전트가 실행한 중첩 하위 에이전트가 이미 중지된 뒤에도 에이전트 패널에서 활성 상태로 계속 강조 표시되는 버그였습니다.

공식 문서와 출시된 빌드가 여전히 모순되는 드문 사례입니다. 다음으로 중첩이 병렬 하위 에이전트와 어떻게 다른지, “깊이 5”가 무슨 뜻인지, 그리고 오늘날 실제로 유용한 세 가지 시나리오를 설명하겠습니다.

## 중첩 하위 에이전트는 병렬 및 순차 하위 에이전트와 어떻게 다른가요?

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="이 섹션의 핵심 요점">

핵심 요점

헷갈린다면 여러분만 그런 게 아닙니다. 병렬화, 연결, 중첩은 서로 직교하는 세 가지 토폴로지입니다. 병렬화는 속도에 관한 것이고, 연결은 실행 순서를 정하는 것이며, 중첩은 전혀 다른 목적을 가집니다. 메인 창에서 시끄러운 작업을 숨기는 것입니다. 이들을 혼동하면 몇 시간 만에 토큰을 낭비하고 오류가 어디서 났는지 찾지 못하게 됩니다.

</div>

이 세 가지 방식을 직접 시험하느라 오랜 시간을 보냈고, 제가 이해한 방식은 이렇습니다. 위임에는 폭, 길이, 깊이라는 세 가지 차원이 있습니다. 각각 다른 문제를 해결합니다.

**폭—병렬 하위 에이전트.** 메인 채팅이 같은 수준의 독립적인 하위 에이전트 N개를 실행합니다. 각 에이전트는 범위가 좁은 작업을 받아 독립된 창에서 작업하고 결과만 반환합니다. 폭은 속도 문제를 해결합니다. 하위 에이전트 5개가 병렬로 작업하면 하나가 같은 일을 순차적으로 처리할 시간에 끝납니다. 이 모델은 제가 쓴 [worktree를 이용한 병렬 하위 에이전트 가이드](https://ailoot.ai/blog/ko/claude-code-parallel-worktree-agents/)에서 다뤘습니다.

**길이—하위 에이전트 체인.** A가 작업한 뒤 결과를 B에게 전달하고, B가 작업한 뒤 C에게 전달합니다. 각 에이전트는 이전 단계의 입력을 확인합니다. 길이는 순서를 정합니다. B는 A의 데이터를 받을 때까지 시작할 수 없습니다. 전형적인 예는 조사 하위 에이전트가 먼저 자료를 모으고, 편집 하위 에이전트가 그 자료를 바탕으로 글을 쓴 다음, 팩트체크 하위 에이전트가 글을 확인하는 것입니다. 평면적인 순서이며 메인 채팅이 전체 이야기를 유지합니다.

**깊이—중첩 하위 에이전트.** A가 B를 실행하고, B가 C를 실행하며, C가 D를 실행합니다. 각 자식은 부모 내부의 독립된 창에서 작업하고 **결과만** 부모에게 반환합니다. 메인 채팅은 자식, 손자, 증손자에게서 무슨 일이 일어나는지 전혀 보지 못합니다. v2.1.172의 새로운 기능이 바로 이것입니다.

가장 큰 혼란은 깊이 5를 “하위 에이전트 5개를 동시에 실행할 수 있다”는 의미로 생각하는 것입니다. 그렇지 않습니다. 깊이는 트리의 세로 단계이지, 동시에 실행되는 자식 수가 아닙니다. 각 단계에는 하위 에이전트가 하나만 있을 수도, 100개 있을 수도 있습니다. 깊이 5는 위임 체인이 5단계 내려갈 수 있다는 뜻입니다. 메인 채팅 → 손자-1 → 손자-2 → 손자-3 → 손자-4 → 손자-5. 그리고 각 단계에서 가지가 뻗을 수 있습니다.





Version 2.1.172 removed the rule that a subagent couldn't spawn another subagent.

속도를 원한다면 폭이 필요합니다. 엄격한 실행 순서가 있다면 길이가 필요합니다. 깊이가 유용한 경우는 딱 하나입니다. 작업 중 하나에 **시끄러운 하위 작업**(웹 요청 15회, 로그 탐색, 파일 12개 읽기)이 포함되어 있고, 그 소음이 메인 창을 가득 채우지 않길 바랄 때입니다.

## “깊이 5단계”는 실제로 어떤 의미인가요?

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="이 섹션의 핵심 요점">

핵심 요점

5단계는 메인 채팅에서 가장 먼 증손자까지의 세로 거리의 최댓값입니다. 서버 측 제한이라 플래그로 높이거나 낮추거나 끌 수 없습니다. 그리고 공식 출처는 메인 채팅 자체가 이 5단계에 포함되는지 아직 밝히지 않았습니다.

</div>

정직하게 짚고 넘어가야 할 점이 있습니다. Anthropic이 정확한 정의를 내놓지 않았다는 사실을 확인하기 위해 문서와 커뮤니티 분석을 반나절 동안 살펴봤습니다. 알아야 할 내용은 다음과 같습니다.

**설정값이 아니라 상한입니다.**



이 제한은 서버 측에 내장되어 있습니다. 클라이언트 v2.1.172를 리버스 엔지니어링한 결과 `MAX_DEPTH` 상수는 발견되지 않았습니다. 이는 검사가 로컬 컴퓨터가 아니라 Anthropic API 어딘가에서 이뤄진다는 뜻입니다. `--max-depth 7`을 설정해 트리를 더 깊게 만들 수 없습니다. 더 낮고 안전한 상한을 설정하려고 `--max-depth 2`를 쓸 수도 없습니다. 사용자가 제어할 수 있는 유일한 항목은 frontmatter의 `Agent(agent_type)` 허용 목록뿐이지만, 이는 깊이가 아니라 자식 에이전트의 **유형**을 제한합니다.

**Anthropic은 “5”를 정확히 정의하지 않았습니다.** 두 번째로 중요한 점입니다.

<figure>
<blockquote>
공식 출처는 depth=5가 루트 아래 다섯 단계인지, 아니면 루트까지 포함해 에이전트 총 다섯 개인지 명시하지 않습니다.
</blockquote>
</figure>

현재 서드파티 통합 기능들은 이를 서로 다르게 해석합니다. `ruvnet/ruflo` 프로젝트의 ADR-147은 “루트 아래 자식 단계 5개 = 체인에 에이전트 6개”라고 가정합니다. 저도 실험에서 같은 규칙을 사용합니다. 메인 채팅은 0단계, 직접 자식은 1단계, 이런 식으로 5단계까지 올라갑니다. 하지만 이 규칙은 공개 문서에 기록되어 있지 않습니다.

**플래그 없이 이미 활성화되어 있습니다.** 따로 켤 필요가 없습니다. Claude Code를 v2.1.172로 업데이트한 다음 자식 에이전트의 `tools`에 `Agent`를 추가하면 또 다른 하위 에이전트를 실행할 수 있습니다. 핵심은 부모 에이전트가 이를 허용해야 한다는 것입니다(`tools: Agent(...)`).

## 현재 여러분의 위임은 어디에서 이뤄지나요? 폭, 길이, 깊이 중 무엇인가요?

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="이 섹션의 핵심 요점">

핵심 요점

실제 바이브 코딩 프로젝트에서는 폭을 거의 항상 볼 수 있고, 가끔 길이를 봅니다. 깊이는 사람들이 수동으로 하는 작업입니다. 새 창을 열고, 프롬프트를 복사하고, 결과를 받아 돌아오는 식입니다. 6월 9일 전에는 이 기능이 내장되어 있지 않았습니다. 그래서 대부분은 자신에게 이 기능이 없다는 사실조차 모릅니다.

</div>

최근 프롬프트 5개를 살펴보세요. 이런 일이 얼마나 자주 있었나요? 작업을 시작하고 Claude가 파일을 grep하고, 웹 요청을 10번 보내고, 로그를 한가득 컨텍스트에 쏟아붓습니다. 그러다 20분 뒤 창이 가득 찬 것을 깨닫습니다. 컨텍스트의 70%가 중간 덤프에 쓰여서 최종 답변은 얼마 남지 않은 토큰 예산으로 작성되고 있습니다.

이런 경우에 필요한 것은 **깊이**입니다. 병렬화도, 체인도 아닌 깊이입니다. 메인 채팅은 “조사”를 하위 에이전트 하나에 위임하고, 그 에이전트가 내부에서 특정 웹 검색, 파일 읽기, grep을 위한 자식들을 실행해야 합니다. 자식은 정리된 판단만 반환합니다. 손자는 부모에게 “찾았고 확인했습니다” 또는 “찾지 못했습니다. 이유는 X입니다”라고 알려줍니다. 부모는 이를 하나의 요약으로 모아 여러분에게 반환합니다. 메인 채팅은 깔끔하게 유지됩니다.

6월 9일 전에는 제가 이 과정을 직접 흉내 냈습니다. Claude Code를 두 번째로 실행하고 “이것을 조사해”라는 프롬프트를 복사해 실행한 뒤, 결과를 수동으로 메인 창에 옮겼습니다. 이 구성을 여러 AI 에이전트에 코딩을 위임하는 방법에 관한 가이드에서 자세히 설명했습니다. v2.1.172에서는 오케스트레이터의 시스템 프롬프트에 이 과정을 바로 적을 수 있고 Claude가 직접 트리를 구성합니다.



## 중첩 하위 에이전트가 실제로 유용한 세 가지 시나리오는 무엇인가요?

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="이 섹션의 핵심 요점">

핵심 요점

모든 작업에 적합한 것은 아닙니다. 메인 창에 넣고 싶지 않은 시끄러운 하위 작업이 위임된 작업에 포함되어 있을 때 깊이를 사용하는 것이 타당합니다. 바이브 코더들 사이에서 자주 등장하는 대표적인 세 가지 시나리오를 다루겠습니다. 팩트체크를 포함한 심층 조사, 대규모 저장소 분석, 스키마나 계약 변경에 따른 종단 간 의존성 감사입니다.

</div>

### 시나리오 1. 팩트체크를 포함한 심층 조사

글이나 영업 제안서에 넣을 자료를 모은다고 가정해 봅시다. 먼저 공개 출처에서 주장 5~10개를 뽑고, 각 주장을 검증해야 합니다. 원 출처를 찾고 인용문이 정확한지 확인한 뒤 실제 수치를 계산합니다.

v2.1.172 이전에는 두 가지 선택지가 있었습니다. 하위 에이전트 하나에 전부 맡겨 웹 요청 30회를 처리하면서 컨텍스트를 온갖 내용으로 채우거나, 수동으로 나누는 것입니다. 주장을 추출하는 프롬프트를 하나 만들고, 주장마다 별도의 하위 에이전트를 실행하는 반복 작업을 해야 했습니다. 메인 채팅은 중간 목록이 한가득 쌓여 가득 찼을 겁니다.

아래 방식에서는 메인 채팅이 `research-orchestrator`(1단계)에 위임합니다. 오케스트레이터가 직접 주장을 추출해 각각 `fact-verifier`(2단계)에 보내고 검증자가 집중 검색을 `web-deep-search`(3단계)에 맡깁니다. 메인 채팅은 출처와 함께 검증된 주장 배열만 받습니다. 나머지는 모두 자식 창에 남아 컨텍스트에 들어오지 않습니다.

### 시나리오 2. 대규모 저장소 분석

파일 200개로 이뤄진 프로젝트를 받았습니다. 아키텍처를 이해하고, 주요 모듈을 찾고, 기술 부채를 평가해야 합니다. 직접 `Glob`에 `Read` 호출 12개를 더하면 10분 만에 창이 가득 찹니다.

깊이를 활용하면 다음과 같이 해결할 수 있습니다. 메인 채팅이 “architect” 하위 에이전트를 실행합니다. architect는 내부적으로 자식 세 개를 실행합니다. 첫 번째는 디렉터리 구조를 살피고(`Glob` 실행 및 요약), 두 번째는 주요 설정 파일 5개를 읽으며, 세 번째는 핵심 패턴을 grep합니다. 각 자식은 간결한 요약을 architect에 반환합니다. architect는 전체 상황을 정리해 화면 절반 분량의 최종 보고서를 메인 채팅에 제공합니다. 모든 파일의 `cat` 출력이 벽처럼 컨텍스트를 채우지 않고 프로젝트의 지도를 얻을 수 있습니다.

### 시나리오 3. 종단 간 의존성 분석

데이터베이스 스키마, API 계약 또는 공유 설정 파일을 변경한다고 가정해 봅시다. 변경의 영향이 어디에 나타날지 파악해야 합니다. 의존성이 많고 각 의존성을 소스에서 확인해야 하기 때문에 이 작업은 컨텍스트를 가장 빠르게 소모합니다.

깊이를 이용하면 메인 채팅이 “impact-analyzer”(1단계)를 실행합니다. 이 에이전트는 영향을 받는 파일마다 `dependency-tracer`를 하나씩 실행합니다(2단계). 각 tracer는 내부에서 `consumer-finder`(3단계)를 실행해 코드베이스에서 해당 의존성의 사용처를 grep합니다. 각 에이전트는 “이 세 곳이 깨집니다”라는 요점만 반환합니다. 메인 채팅은 grep 결과를 알지 못한 채 “영향받는 파일 → 영향” 표를 작성합니다.





## 10분 만에 중첩 하위 에이전트를 설정하는 방법

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="이 섹션의 핵심 요점">

핵심 요점

플래그나 설정 업데이트가 필요 없습니다. 자식 에이전트의 `tools`에 `Agent`를 추가하면 자체 하위 에이전트를 실행할 수 있습니다. 트리가 카지노처럼 변하지 않도록 `Agent(name1, name2)` 허용 목록을 사용하세요. 이제 복사해서 쓸 수 있는 3단계 오케스트레이터 템플릿을 소개하겠습니다.

</div>

**1단계. v2.1.172 이상을 사용 중인지 확인하세요.**

```bash
claude --version
```

버전이 더 낮다면 업데이트하세요. 릴리스의 주요 기능은 변경 로그 한 줄로 설명됩니다. “이제 하위 에이전트가 최대 5단계 깊이까지 자체 하위 에이전트를 생성할 수 있습니다” ([전문](https://github.com/anthropics/claude-code/releases/tag/v2.1.172)).

**2단계. 자식을 생성할 수 있는 부모 에이전트를 만드세요.**

파일 `.claude/agents/research-orchestrator.md`:

```markdown
---
name: research-orchestrator
description: 심층 팩트체크를 포함한 조사를 위임합니다
tools: Agent(fact-verifier), Read, WebFetch
model: opus
---

너는 조사 오케스트레이터다. 주제를 받으면:
1. 제공된 자료를 읽거나 제공된 공개 출처 URL을 가져온다.
   구체적인 주장 최대 5개를 직접 추출한다. 각 주장 문구, 출처 URL이나 파일,
   정확한 근거 구절을 기록한다. 출처가 없으면 위임 전에 요청한다.
2. 각 주장에 대해 fact-verifier를 호출한다. fact-verifier는 웹 검색과 대조를 위해
   자체 자식 하위 에이전트를 생성한다.
3. fact-verifier는 최종 판정만 돌려준다.
   중간 덤프를 네 컨텍스트에 불러오지 마라.

최종 보고서는 { claim, sources[], confidence } 배열만 포함한다.
```

`tools` 행은 `fact-verifier` 유형만 허용합니다. 주장 추출은 오케스트레이터의 첫 작업이므로 정의되지 않은 claim-extractor 파일이 필요 없습니다. 유형 허용 목록은 호출 가능한 자식 종류를 제한할 뿐 호출 횟수를 제한하지 않습니다. 추출 주장을 최대 다섯 개로 제한하세요.

**3단계. 손자를 직접 생성할 수 있는 자식 에이전트를 만드세요.**

파일 `.claude/agents/fact-verifier.md`:

```markdown
---
name: fact-verifier
description: 자식 웹 검색으로 주장을 검증합니다
tools: Agent(web-deep-search), Read
model: sonnet
---

너는 팩트체커다. 주장을 받으면:
1. 검색어 2-3개를 작성한다.
2. 각 검색어에 대해 web-deep-search를 실행한다. 이 에이전트는 직접
   WebSearch와 WebFetch를 수행하고 검증된 스니펫을 반환한다.
3. 하나의 verdict로 정리한다: { claim, sources[], confidence }.
```

주요 부분을 확인하세요. 여기서도 `tools`는 `Agent(web-deep-search)`라고 지정합니다. 따라서 트리의 2단계인 fact-verifier가 직접 다른 하위 에이전트(3단계)를 실행할 수 있습니다. 예전에는 이 행이 효과가 없었습니다. 문서에는 아직 다음 문구가 남아 있습니다.

<figure>
<blockquote>
하위 에이전트는 다른 하위 에이전트를 생성할 수 없으므로 Agent(agent_type)은 하위 에이전트 정의에서 작동하지 않습니다.
</blockquote>
<figcaption>— Claude Code 문서, https://code.claude.com/docs/en/sub-agents</figcaption>
</figure>

v2.1.172에서는 이 문구가 오래된 정보입니다. 구문은 동일하지만 이제 트리의 어느 깊이에서도 작동합니다.

**4단계. 손자를 만드세요.**

파일 `.claude/agents/web-deep-search.md`:

```markdown
---
name: web-deep-search
description: 웹 검색을 수행하고 스니펫을 반환합니다
tools: WebSearch, WebFetch
model: haiku
---

검색어를 전달받았습니다. WebSearch를 수행하고 관련성 높은 URL 상위 3개를 고른 다음,
WebFetch로 주장에 대한 직접적인 근거를 가져오세요.
{ url, snippet, supports_claim: yes|no } 배열을 반환하세요.
```

손자의 `tools`에 `Agent`가 없으므로 트리를 더 아래로 확장하지 않습니다.

**5단계. 오케스트레이터를 실행하세요.**

```bash
claude --agent research-orchestrator
```

채팅에 원문이나 공개 출처 URL을 제공하세요. “이 출처에서 구체적인 주장 최대 5개를 추출·검증하고 주장, 출처, 신뢰도를 반환하세요.” `--agent research-orchestrator`에서는 세션 자체가 오케스트레이터이고 검증·검색 자식은 그 아래 두 단계입니다. 일반 메인 세션에서 오케스트레이터에 위임하면 메인 아래 세 단계가 됩니다.

## 토큰을 낭비하고 관찰 가능성을 떨어뜨리는 안티패턴 5가지는 무엇인가요?

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="이 섹션의 핵심 요점">

핵심 요점

깊이에는 비용이 듭니다. 단계가 하나 내려갈 때마다 토큰이 늘고, 이 증가는 누적됩니다. 중첩이 해가 되는 다섯 가지 시나리오를 살펴보겠습니다. 이를 따라 하지 마세요. 한 시간 만에 하루 예산을 소진하고 트리의 네 번째 층에서 발생한 오류를 찾지 못하게 됩니다.

</div>

**안티패턴 1. 작업 하나가 한 창에 들어갑니다.**



하위 에이전트 하나로 충분히 처리할 수 있다면 중첩은 불필요한 비용과 지연만 더합니다.

**안티패턴 2. 격리가 아니라 속도를 원합니다.**

속도가 필요하다면 깊이가 아니라 **병렬화**가 필요합니다. 체인을 만드는 대신 하위 에이전트 5개를 같은 단계에서 나란히 실행하세요. 깊이는 시끄러운 준비 작업을 자식 창으로 옮기기 위한 것이지, 작업 속도를 높이기 위한 것이 아닙니다.

**안티패턴 3. 작업의 본질이 얕습니다.**

“이 파일을 찾아 보여 줘”는 **2단계 요청**이므로 3단계 계층은 필요하지 않습니다. 중첩은 작업에 시끄러운 하위 작업이 포함될 때 가치가 있습니다. 소음이 없다면 하위 에이전트를 추가하지 마세요.

**안티패턴 4. 첫 단계의 프롬프트가 모호합니다.**

가장 위험한 시나리오입니다. 1단계 오케스트레이터에게 모호한 프롬프트를 주면 모호함이 증폭됩니다. 모호한 1단계 프롬프트 하나는 2단계에서 모호한 프롬프트 4개, 3단계에서 16개가 됩니다. 손자들이 작업을 시작할 무렵에는 무엇을 찾는지도 모릅니다.

**안티패턴 5. 기하급수적인 비용 증가.**

주요 경제적 논거입니다.

중첩은 토큰 사용량을 늘리고, 깊이가 깊어질수록 증가량이 누적됩니다.

대략 계산해 보면 각 단계에서 3개로 분기하는 깊이 3 체인은 하위 에이전트 27개를 뜻합니다. 간단한 요청보다 토큰을 최소 27배 더 쓰는 셈입니다. Claude Pro 요금제에서는 이 계산대로라면 몇 시간 만에 하루 한도를 소진합니다. Max 요금제라면 일주일치 허용량을 하루 만에 소진하게 됩니다.

**보너스 안티패턴(제 경험): “쓸데없는 일을 하는 에이전트 50개.”**

다른 사람들의 프로젝트를 보면 이런 말을 자주 듣습니다. “에이전트 50개가 작업 중이에요.” 무슨 일을 하는지 물어보면 그 50개 에이전트는 **쓸데없는 일을 하고 있습니다**. 불필요한 출력, 원시 요약, 중복 내용, 로그 뭉치를 쏟아냅니다. 각자 “대체로 유용한” 일을 하고, 그 결과 컨텍스트는 넘쳐나고 토큰 비용은 작은 회사의 비용만큼 커집니다. 깊이 5는 이 문제를 해결하지 않습니다. **더 악화합니다**. 1단계에서 누가 무슨 일을 하는지조차 불분명하다면, 깊이 5는 혼란을 다섯 단계로 늘립니다.

하위 에이전트를 실행하기 전에 30초 안에 네 가지 질문에 답할 수 있는지 확인하세요.

- 정확히 무슨 일을 하나요(한 문장으로)?
- 어떤 파일을 다루나요?
- 부모에게 무엇을 반환하나요?
- 누가 확인하나요?

30초 안에 답할 수 없다면 그 하위 에이전트는 만들지 않아야 합니다. 이 규칙은 [병렬 하위 에이전트 가이드](https://ailoot.ai/blog/ko/claude-code-parallel-worktree-agents/)에서 별도로 설명했습니다.

## 컨텍스트 엔지니어링 없이 중첩하면 왜 환각이 5단계로 이어지나요?

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="이 섹션의 핵심 요점">

핵심 요점

깊은 위임의 주요 함정은 작업 맥락 누락입니다. 자식은 부모의 전체 대화나 읽은 모든 파일을 자동으로 받지 않습니다. 사용자 하위 에이전트는 제외 설정이 없으면 보통 해당 CLAUDE.md를 로드하지만 참조한 업무 파일 전체를 자동 로드하지는 않습니다. 매 인계마다 정확한 자료, 경로, 결과 계약을 전달하세요. 프로젝트의 컨텍스트 구조가 제대로 잡혀 있지 않다면 트리가 깊어질수록 손자들이 더 많은 상상을 하게 됩니다. 단계마다 하나씩, 환각이 다섯 층으로 쌓입니다.

</div>

여기서 사람들이 자주 묻습니다. “Claude Code를 업데이트하고 tools에 Agent도 추가했어요. 트리는 만들어지는데 최종 답변은 여전히 엉뚱해요. 왜 그런가요?”

답은 간단합니다. Claude Code의 모든 하위 에이전트는 **처음부터 시작합니다**. 공식 문서의 설명입니다.

<figure>
<blockquote>
각 하위 에이전트는 새로 만들어진 격리 창에서 시작합니다. 대화 기록, 이미 호출한 스킬, Claude가 이미 읽은 파일을 볼 수 없습니다.
</blockquote>
<figcaption>— Claude Code 문서, https://code.claude.com/docs/en/sub-agents</figcaption>
</figure>

1단계에서는 관리할 수 있습니다. 오케스트레이터가 자식에게 짧은 작업 설명을 전달하기 때문입니다. 하지만 3단계에서는 손자가 부모에게서 위임 메시지를 받는데, 그 부모도 위임 메시지만 받은 상태입니다. 각 단계에서 전달되는 정보는 조금씩 줄어듭니다. 5단계에 이르면 창에 “주장 X 확인”이라는 문구만 있고 다른 내용은 없는 하위 에이전트가 생깁니다. 어느 프로젝트에서 작업하는지, 어떤 문제를 해결하는지, 무엇에 집중해야 하는지 알지 못합니다.

[CLAUDE.md](https://ailoot.ai/blog/ko/claude-md-template/)가 없다면 5단계 손자는 평생 처음 사무실에 출근했는데 아무런 안내도 받지 못한 직원과 같습니다. 작업을 받았으니 뭔가 하기는 하겠지만, 프로젝트에 필요한 일을 하지는 않을 것입니다.

**그래서 구성이 필수입니다.** 제대로 설정된 `CLAUDE.md`, `business/`, 스킬 파이프라인 없이 깊이 5를 쓰는 것은 카지노와 같습니다. 이들이 있으면 도구가 됩니다.

## 중첩 외에 v2.1.172에서 달라진 점은 무엇인가요?

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="이 섹션의 핵심 요점">

핵심 요점

이 릴리스는 하위 에이전트에 관한 것입니다. 주요 기능과 함께 위임 인프라 수정 4건도 포함되어 있습니다. 그중 하나는 중첩에서만 발생할 수 있는 버그를 수정합니다.

</div>

v2.1.172 변경 로그 전문을 열어 보면 릴리스 전체가 하위 에이전트에 관한 내용임을 알 수 있습니다.

**수정 1.** 중첩 하위 에이전트가 중지된 뒤 백그라운드 하위 에이전트가 에이전트 패널에서 “멈춘” 활성 상태로 남아 있지 않습니다. 중첩에서만 발생할 수 있는 버그입니다.

**수정 2.** `availableModels` 제한이 하위 에이전트에도 적용됩니다. 이전에는 팀에서 사용할 수 있는 모델을 제한해도(예: 비용 절감을 위해 opus 금지) 하위 에이전트가 자체 설정의 재정의 옵션으로 규칙을 우회할 수 있었습니다. v2.1.172부터는 어디에서나 규칙이 적용됩니다.

**수정 3.** 프롬프트 기록에서 위쪽 화살표를 누르면 이제 메인 에이전트의 탭이 아니라 하위 에이전트의 **현재** 탭에 있는 프롬프트가 표시됩니다. 관찰 가능성 개선입니다.

**수정 4.** 유휴 상태의 CPU 사용량이 감소했습니다. 유휴 상태일 때 `/goal` 표시기가 더 이상 초당 5회 터미널을 다시 그리지 않으며, 병렬 하위 에이전트 작업 중 UI도 덜 자주 다시 그려집니다.

네 가지 수정 모두 하위 에이전트와 관련이 있다는 점을 짚고 싶습니다. 이는 Anthropic이 변경 로그 한 줄만이 아니라 중첩 인프라 전체 스택을 출시했다는 뜻입니다. 중첩은 공개되기 전부터 한동안 Anthropic 내부에서 사용되고 있었습니다.

## 체크리스트: 중첩이 도움이 될 때와 방해가 될 때

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="이 섹션의 핵심 요점">

핵심 요점

새 하위 에이전트를 실행하기 전에 작업을 6가지 기준으로 확인하세요. 답변이 3개 이상 “예, 깊이를 사용”이라면 그렇게 하세요. 그보다 적으면 병렬화나 하위 에이전트 하나만 사용하세요. 이렇게 하면 토큰과 신경을 아끼고, 중첩 실행 27개로 이뤄진 체인이 대체 무슨 일을 하는지 알아내느라 몇 시간을 허비하지 않을 수 있습니다.

</div>

다음과 같은 경우 중첩을 사용하세요.

- 작업에 웹 요청, grep 또는 파일 읽기가 많은 하위 작업이 포함되어 있습니다.
- 하위 작업을 잃어도 괜찮습니다(손자가 “찾지 못했습니다”라고 반환해도 오케스트레이터가 계속 진행할 수 있습니다).
- 메인 창에서 중간 결과를 볼 **필요가 없습니다**.
- 하위 에이전트가 활용할 수 있는 `CLAUDE.md`와 정리된 프로젝트 컨텍스트가 있습니다.
- 각 단계가 반환할 내용(입력, 출력, 형식)을 명확하게 설명할 수 있습니다.
- Max 요금제를 사용하거나 ×27 토큰을 감당할 여유가 있습니다.

다음과 같은 경우 중첩을 사용하지 마세요.

- 하위 에이전트 하나가 소음 없이 작업을 해결할 수 있습니다.
- 메인 창에서 중간 결과를 봐야 합니다(이는 병렬화를 원한다는 뜻입니다).
- 프로젝트에 CLAUDE.md가 없거나 비즈니스 컨텍스트가 거의 없습니다.
- 1단계 프롬프트가 모호합니다(그 모호함이 트리 아래로 기하급수적으로 증폭됩니다).
- 속도가 필요합니다. 동일한 결과를 얻기에는 깊이보다 병렬화가 빠릅니다.
- Pro 요금제를 사용하면서 온종일 작업합니다. 몇 시간 만에 한도를 소진하게 됩니다.

<div class="section" role="doc-bibliography" aria-label="출처">

### 출처

- [Claude Code Release v2.1.172 - GitHub Releases](https://github.com/anthropics/claude-code/releases/tag/v2.1.172)
- [사용자 지정 하위 에이전트 만들기 - Claude Code 문서](https://code.claude.com/docs/en/sub-agents)

</div>





더 많은 자료는 [Ailoot](https://ailoot.ai/)에서 확인할 수 있습니다.

## Claude Code에서 중첩 하위 에이전트로 대규모 작업을 위임하는 방법: 자주 묻는 질문

### 이 예시를 복사하려면 claim-extractor도 만들어야 하나요?

아닙니다. 수정된 research-orchestrator가 제공 자료에서 최대 다섯 주장을 직접 추출합니다. 표시된 research-orchestrator, fact-verifier, web-deep-search 세 파일을 만들고 원문이나 URL을 주세요.

### fact-verifier만 허용하면 자식 실행 수도 제한되나요?

아닙니다. 에이전트 유형 허용 목록은 호출 종류만 제한합니다. 예시는 최초 추출을 별도로 다섯 주장으로 제한합니다. 실제 호출과 토큰 사용량을 관찰하세요.


## Ailoot · 회사와 그 프로젝트 포트폴리오

Ailoot는 축적된 운영 경험, 폭넓은 고객 기반, 안정적인 서비스, 지속적인 KPI 관리를 바탕으로 합니다.

회사와 그 프로젝트 포트폴리오: 수백만 고객, 매월 수십억 규모의 매출.

Ailoot는 이러한 운영 경험을 고객의 제품, 에이전트, 애플리케이션, 자동화에서 AI 기능을 이용할 수 있는 API 접근에 활용합니다.