Claude Code 서브에이전트 가이드 — Explore가 read-only인 이유와 전환 메커니즘 - Insights | Molayo

본 기사의 위치: 【필독】 Claude 멀티 에이전트의 초기 설정은 Agent Teams(여러 Claude Code 인스턴스를 팀으로서 동작시키는 기능)를 다루는 멀티 에이전트 편이었습니다. 본 기사는 그 자매 기사로서, Agent Teams보다 한 단계 낮은 레이어인 서브에이전트(Sub-agent, 메인 에이전트가 위임하는 단일 작업자)에 초점을 맞춥니다.

왜 "Explore는 read-only였습니다. general-purpose로 전환하여 재시작합니다"라고 나오는가?

어느 날 서브에이전트를 사용해 작업하던 중, 메인 에이전트로부터 다음과 같은 메시지가 돌아왔습니다.

Explore는 read-only였습니다. general-purpose로 전환하여 재시작합니다.

"재시작"이라는 말을 들으면 에러나 장애를 연상하지만, 이는 서브에이전트의 권한 차이에 의한 정상적인 궤도 수정입니다. 본 기사에서는,

Claude Code의 서브에이전트에는 어떤 타입이 있는지
각각의 툴 권한(Tool permission)의 차이 - 왜 "처음부터 general-purpose로 하지 않는가"
전환이 일어나지 않도록 하는 호출 방법

을 실례를 바탕으로 정리합니다.

서브에이전트(Sub-agent)란?

메인 Claude Code 에이전트가 특정 태스크(Task)를 별도의 인스턴스에 위임하여 실행시키는 구조입니다. Agent 툴(구칭 Task)로부터 호출됩니다.

목적: 조사·병렬 처리·긴 검색 결과의 격리 등, 메인 컨텍스트(Context)를 더럽히지 않고 처리를 진행하고 싶은 상황에서 사용
특징: 위임받은 서브에이전트는 독립된 문맥에서 움직이며, 최종 결과만을 메인에 반환
Agent Teams와의 차이: Agent Teams는 여러 Claude Code 인스턴스가 서로 통신하는 협조 모델입니다. 서브에이전트는 메인에 결과만을 반환하는 심플한 위임 모델입니다. 자세한 내용은 멀티 에이전트 편의 비교표를 참조하십시오.

【2026-06 추가】 서브에이전트가 자신의 서브에이전트를 생성 가능하게 됨 (v2.1.172 · 최대 5계층)

2026년 6월 10일(PT) / 11일(JST)의 Claude Code v2.1.172에서 서브에이전트 구조에 큰 확장이 이루어졌습니다.

Sub-agents can now spawn their own sub-agents (up to 5 levels deep) (공식 changelog)

지금까지 서브에이전트는 "메인이 위임한 단일 작업자"였으며, 자신의 아래에 추가적인 서브에이전트를 가질 수 없었습니다. v2.1.172 이후부터는, 서브에이전트 스스로가 Agent 툴을 통해 더 하위의 서브에이전트를 호출할 수 있게 되어, 위임 계층을 최대 5계층까지 깊게 만들 수 있습니다.

v2.1.172 이전	v2.1.172 이후
위임 깊이	메인 → 서브 (1단계만)
적합한 용도	단발성 조사·처리

Dynamic Workflows와의 관계 (가로 병렬 × 세로 계층)

혼동하기 쉬운 것이 Dynamic Workflows의 "최대 1,000개의 서브에이전트를 병렬 팬아웃(Fan-out)"이라는 숫자와의 관계입니다. 두 가지는 별개의 축을 가리킵니다.

Dynamic Workflows의 최대 1,000: 1회의 워크플로우에서 가로 방향으로 동시 기동할 수 있는 총수의 상한 (넓고 얕게)
v2.1.172의 최대 5계층: 세로 방향의 중첩(재귀 위임) 깊이의 상한 (깊게)

즉, "가로(병렬 수) × 세로(계층의 깊이)"의 2축으로 파악하면 정리할 수 있습니다. 깊은 계층에서 재귀적으로 태스크를 분할하면서, 각 단계에서 병렬로 확장하는 구성이 가능해졌습니다.

단, 주의사항도 늘어납니다. 메인을 Fable 5로 설정했더니 자식 서브에이전트가 전부 Fable 5로 구동된 사례처럼, 계층이 깊어지고 병렬이 넓어질수록 토큰(Token)과 레이트 리밋(Rate limit) 소비는 급증합니다. 각 서브에이전트의 모델을 명시적으로 지정하여 한 단계 낮추는(기계적인 대량 처리는 Sonnet 등으로) 등의 비용 설계가 이전보다 더욱 중요해집니다.

서브에이전트의 타입과 권한 차이

서브에이전트는 여러 가지 **타입(Type)**을 가지며, 타입별로 사용할 수 있는 도구가 정의되어 있습니다. Claude Code에서 기본적으로 제공되는 주요 타입은 다음과 같습니다.

타입	주요 용도	사용 가능 도구	쓰기 계열 (Edit / Write / NotebookEdit)
Explore	빠른 읽기 전용 검색 (파일 탐색, grep, WebFetch)	Glob, Grep, Read, WebFetch, WebSearch 외	❌
general-purpose	범용, 다단계 태스크 전반	거의 모든 도구 (쓰기 계열 포함)	✅
Plan	구현 플랜 작성 및 아키텍처 검토	읽기 계열 + 분석, 쓰기 계열은 제외	❌
claude (이름 없는 기본값)	무엇이든	모든 도구	✅
statusline-setup	상태 표시줄(Status Line) 설정 편집	Read, Edit만 가능	✅ (제한적)

핵심은, Explore와 Plan은 의도적으로 read-only(읽기 전용)로 설계되었다는 점입니다. Edit / Write / NotebookEdit와 같은 파일 쓰기 계열 도구는 애초에 사용할 수 없도록 되어 있습니다.

에피소드: 실제로 전환이 일어난 순간의 해독

서두의 메시지를 다시 한번 살펴보겠습니다.

Explore는 read-only 상태였습니다. 이를 general-purpose로 전환하여 재시작합니다.

이 메시지는 메인 에이전트 내부에서 발생한 다음의 흐름을 언어화한 것입니다.

1. 메인이 "이것은 조사 태스크"라고 판단
↓
2. Agent 도구를 통해 Explore에 위임
...

즉, 메인이 위임 대상을 선정할 때 약간의 오판이 있었기 때문에 궤도를 수정하고 있는 것입니다. 이는 에러나 장애가 아닙니다.

왜 "처음부터 general-purpose"로 하지 않는가?

"번거로우니 전부 general-purpose로 하면 되지 않느냐"라고 생각할 수 있지만, Explore가 독립적으로 존재하는 데에는 이유가 있습니다.

컨텍스트 보호 (Context Protection): Explore는 "결과의 발췌본만 반환"하도록 설계되었기 때문에, 검색된 행을 대량으로 메인에 가져오지 않습니다. 이를 통해 문맥(Context)을 절약할 수 있습니다.
잘못된 변경 방지: 조사 태스크를 수행하는 도중에 멋대로 파일을 수정해 버리면 곤란합니다. read-only로 설정함으로써 사고를 물리적으로 방지합니다.
판단 속도 향상: Explore는 읽기 전용에 특화되어 있어 사고의 분기가 적고 짧은 시간 내에 결과가 반환됩니다.

트레이드오프(Trade-off)는 명확합니다. "쓰기가 정말 필요한 상황인데 Explore로 던져버린" 경우에 전환 비용이 발생합니다.

전환이 일어나면 얼마나 낭비되는가?

주요 낭비 요소는 다음 두 가지입니다.

종류	내용
토큰 소비	Explore에 전달한 시스템 프롬프트 + 중간까지 진행된 조사 결과가 통째로 낭비됨
시간	별도의 에이전트로 재시작하기 때문에 기동 오버헤드(Overhead)가 추가로 발생함

전환이 일어나면 Explore에서 얻은 지식은 그대로 이어지지 않는다는 점에 주의하세요. general-purpose는 처음부터 다시 시작합니다.

빈번하게 발생한다면: 동일한 패턴으로 전환이 계속 일어난다면, 메인 에이전트가 위임 시의 판단력을 학습하도록 두는 것보다 사용자가 명시적으로 지시하는 것이 더 확실합니다 (후술).

전환 방지: 처음부터 올바른 타입을 지정하기

메인 에이전트의 위임 대상 선정은 태스크 기술(Description)로부터 추측됩니다. 모호한 지시는 Explore로 배정되기 쉽기 때문에, 쓰기가 발생할 수 있는 태스크에서는 타입을 명시하는 것이 효과적입니다.

NG 예시 (Explore로 배정되기 쉬움)

"코드베이스에서 ◯◯ 부분을 찾아서 고쳐줘"

"찾아서"라는 표현 때문에 Explore 쪽으로 판단될 리스크가 있습니다.

OK 예시 (general-purpose를 명시)

"코드베이스에서 ◯◯ 부분을 찾아서 고쳐줘. 쓰기가 필요하므로 general-purpose로 진행해줘"

명시함으로써 메인은 처음부터 general-purpose로 위임하게 됩니다.

순수 조사만 할 때는 Explore를 명시

반대로, 정말로 읽기만 수행할 것임을 보장하고 싶은 태스크에서는 Explore를 명시하여 실수로 파일이 수정되는 사고를 방지할 수 있습니다.

"설정 파일들을 read-only로 전부 탐색해서 설정 키 목록을 반환해줘. Explore로."

서브에이전트 (Sub-agent) vs Agent Teams: 무엇을 사용해야 할까?

자매 글인 멀티 에이전트 편에서 다루는 Agent Teams와 본 기사의 서브에이전트는 서로 다른 상황에서 구분하여 사용합니다.

관점	서브에이전트 (Sub-agent)	Agent Teams
통신 모델	메인에 결과만 반환	멤버 간 양방향 통신
특징	집중형 단발 태스크 (조사·특정 처리)	토론·협업이 필요한 복잡한 태스크
주요 전환 패턴	Explore ↔ general-purpose	리더 (Leader) ↔ 팀원 (Teammate)
설정 필요성	불필요 (표준 기능)	`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`로 활성화

경험칙으로서, "메인이 컨텍스트 (Context)를 오염시키지 않고 조사·처리를 끝내고 싶다"는 목적이라면 서브에이전트만으로 충분합니다. 여러 관점에서의 토론·병렬 협업이 필요할 때 Agent Teams로 넘어가는 순서를 추천합니다.

요약

"Explore는 read-only였습니다. general-purpose로 전환하여 재시작합니다"는 에러가 아니라 궤도 수정입니다.
서브에이전트에는 **읽기 전용 계열 (Explore / Plan)**과 **쓰기 가능 계열 (general-purpose / claude)**이 있습니다.
권한 분리는 컨텍스트 보호와 사고 방지를 위한 의도적인 설계입니다.
전환을 방지하려면 쓰기가 필요할 때는 general-purpose를 명시하고, 순수한 조사 시에는 Explore를 명시하세요.
여러 에이전트가 협업하는 상황이 필요해지면 멀티 에이전트 편의 Agent Teams로 단계적으로 나아가세요.

Claude Code 서브에이전트 가이드 — Explore가 read-only인 이유와 전환 메커니즘

요약

핵심 포인트