서브에이전트

확인 날짜 안내

확인 날짜가 섞인 페이지다. 공식 문서 부분(확장 기능 개요·메모리·스킬·컨텍스트 창 문서와 Claude Code 서브에이전트)은 원본 날짜 미상이라 수집일(2026-10-18) 기준, 블로그 Steering Claude Code 부분은 2026-06-18, 컨텍스트 엔지니어링 글 부분은 2025-09-29 기준이다. "다른 도구에서" 절의 Antigravity 내용은 공식 서브에이전트 문서(Antigravity 서브에이전트 문서, 원본 날짜 미상, 수집 2026-10-21) 기준이다. 에이전트 설계 글 효과적인 에이전트 만들기(2024년 글)의 패턴 정의와 컨텍스트 엔지니어링 글의 설계 패턴·보고 결과는 날짜 계산에서 뺀다. 페이지 확인 날짜는 2026-06-18이다. 블로그 단독 사실(dynamic workflows 규모)과 Gemini CLI 저장소 공지 단독 사실(설치 때 에이전트 프로필 유지, 2026-06-18)이 남아 있기 때문이다. 필드별 세부는 서브에이전트 정의 파일 레퍼런스, 절차는 Claude Code 서브에이전트 만들기·운영, 증상별 점검은 Claude Code 서브에이전트 문제 해결.

정의#

자기 컨텍스트(용어 사전)에서 자기 루프를 돌고 요약만 돌려주는 격리된 작업자다. Claude Code의 확장 기능 중 하나다. Claude Code 확장 기능 개요

(2026-10-18 기준) 공식 서브에이전트 문서의 정의: 특정 종류의 작업을 맡는 전문 AI 어시스턴트다. 곁가지 작업이 다시 참고하지 않을 검색 결과·로그·파일 내용으로 메인 대화를 채울 때 쓰고, 서브에이전트는 그 일을 자기 컨텍스트에서 하고 요약만 돌려준다. 같은 지시로 같은 종류의 작업자를 계속 띄우게 되면 커스텀 서브에이전트를 정의한다. 각 서브에이전트는 자기 컨텍스트 창, 커스텀 시스템 프롬프트, 지정한 도구 접근, 독립된 권한으로 돌고, 자기 요청을 보내며 그 요청은 메인 대화와 같은 사용량 한도에 잡힌다. 서브에이전트는 한 세션 안에서 일하고, 여러 독립 세션의 병렬 실행·세션 간 메시지·에이전트 팀은 별도 기능이다(원본이 링크만 함). Claude Code 서브에이전트

원본이 드는 쓰임 다섯 가지: 탐색·구현을 메인 대화 밖에 두어 컨텍스트 보존, 쓸 수 있는 도구를 제한해 제약 강제, 사용자 레벨 서브에이전트로 여러 프로젝트에 재사용, 도메인별 집중 시스템 프롬프트로 동작 전문화, Haiku 같은 빠르고 싼 모델로 보내 비용 통제. Claude Code 서브에이전트

핵심 이점은 컨텍스트 격리다. 서브에이전트가 파일 수십 개를 읽거나 넓게 검색해도 메인 대화에는 요약만 들어온다. Claude Code 확장 기능 개요

(2026-10-18 기준) 공식 작동 방식 문서는 서브에이전트 생성을 Claude의 조율용 내장 도구 중 하나로 들고, 서브에이전트를 기본 에이전트 루프 위에 얹는 확장의 하나로 본다. 서브에이전트는 자기 컨텍스트 창에서 일하며, 포크가 아니면 새로 시작하고 포크는 지금까지 대화의 사본으로 시작한다. 어느 쪽이든 서브에이전트의 도구 호출은 메인 컨텍스트에 들어오지 않고, 끝나면 Claude가 요약을 받는다. Claude Code 작동 방식

(2026-10-18 기준) Anthropic의 직무별 플러그인 저장소 README는 플러그인 하나가 스킬, 커넥터, 슬래시 명령과 함께 서브에이전트도 묶는다고 말한다. 다만 같은 README의 공통 폴더 구조도에는 서브에이전트 폴더가 없다. Knowledge Work Plugins 저장소 → Knowledge Work Plugins

정의 파일과 로드 방식 (2026-10-18 기준, 블로그 문장은 2026-06-18)#

(2026-10-18 기준) 공식 서브에이전트 문서가 아래 블로그 사실을 대부분 확인한다: 위치 .claude/agents/, YAML frontmatter 뒤 본문이 시스템 프롬프트, 필수 name·description, 선택 model·tools 등. 공식 문서 기준 위치 5곳·필드 전체·건너뛰는 파일 규칙은 서브에이전트 정의 파일 레퍼런스. 다만 아래 "최대 5단계 중첩"은 v2.1.172~v2.1.216의 기본값이었고 지금(수집 2026-10-18) 기본은 3층이다(아래 "중첩과 동시 실행 한도"). Claude Code 서브에이전트

• .claude/agents/의 마크다운 파일로, 특정 곁가지 작업용 격리된 어시스턴트를 정의한다. YAML frontmatter(name, description, 선택 필드로 model과 도구 접근) 뒤에 오는 본문이 그 서브에이전트의 시스템 프롬프트가 된다. Steering Claude Code
• 세션 시작 때는 이름, 설명, 도구 목록만 로드된다. 본문은 자동 호출되지 않고, Claude가 Agent 도구에 프롬프트 문자열을 넘겨 부를 때만 쓰인다. 본문은 부모 대화에 아예 들어가지 않는다. Steering Claude Code
• 서브에이전트는 새 컨텍스트 창에서 돌고, 메인 세션으로 돌아오는 것은 최종 메시지(흔히 여러 하위 작업을 모은 결과)와 메타데이터뿐이다. 그래서 컴팩션 동작도 "최종 메시지(요약과 메타데이터)만 메인 세션으로 돌아옴"이고, 부르기 전까지 메인 컨텍스트 비용은 0이다. Steering Claude Code → 컨텍스트 비용
• (2026-10-18 기준) 공식 컨텍스트 창 문서도 같은 모양을 보여 준다: 돌아오는 것은 서브에이전트의 최종 텍스트 응답과 토큰 수·소요 시간을 담은 작은 메타데이터뿐이다. 원본 시뮬레이션은 서브에이전트가 파일을 읽은 양과 돌려준 양을 비교해 이것을 "컨텍스트 절약"이라고 부른다(숫자는 원본이 밝힌 예시). Claude Code 컨텍스트 창
• 확장: 서브에이전트는 최대 5단계까지 중첩된다(블로그 2026-06-18. 공식 문서 기준 v2.1.172~v2.1.216의 동작, ‘원본끼리 달랐던 점’ 상자 참고). dynamic workflows는 서브에이전트 구조의 세부를 하나하나 정하지 않아도 수십~수백 개의 백그라운드 에이전트를 조율하며, 조율 계획과 중간 결과가 Claude의 컨텍스트 창이 아니라 스크립트 변수에 살아 지시 충실도를 잃지 않고 규모를 키운다. Steering Claude Code

내장 서브에이전트 (2026-10-18 기준)#

Claude Code는 Claude가 알맞을 때 자동으로 쓰는 내장 서브에이전트를 둔다. 모두 부모 대화의 권한 규칙을 물려받고, 대부분 좁은 도구 세트로 돈다. Claude Code 서브에이전트

• Explore·Plan은 일회용이라 재개할 수 없다. 사용자·프로젝트 레벨에 같은 이름(Explore)을 두면 내장을 덮어쓴다. 내장을 끄는 방법(permissions.deny의 Agent(이름), CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1, 비대화형·SDK의 CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1)은 Claude Code 서브에이전트에 있다.
• 자동 위임은 요청의 작업 설명, 각 서브에이전트의 description, 현재 맥락으로 정해진다. 설명은 시작 때 컨텍스트를 차지하므로 짧게 쓰고, 내장을 뺀 설명 합이 15,000토큰을 넘으면 시작 때 경고가 뜬다(그래도 모두 로드). Claude Code 서브에이전트 → 컨텍스트 비용

중첩과 동시 실행 한도 (2026-10-18 기준)#

• 중첩: 기본으로 서브에이전트는 자기 서브에이전트를 메인 대화 아래 세 층까지 띄운다. 한도에 닿은 서브에이전트에게서는 Agent 도구를 빼므로(포크는 목록에 남지만 호출하면 오류), 그 서브에이전트는 맡은 일을 직접 하고 요약 하나를 돌려준다. CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH로 층 수를 바꾸고 1이면 중첩이 꺼진다. 한 서브에이전트만 못 띄우게 하려면 tools에서 Agent를 빼거나 disallowedTools에 넣는다. Claude Code 서브에이전트
• 버전 이력(원본 Note): v2.1.172~v2.1.216은 기본으로 최대 5층(변경 불가), v2.1.217~v2.1.218은 기본 1층(높이지 않으면 서브에이전트가 자기 서브에이전트를 못 띄움), v2.1.219부터 기본 3층. Claude Code 서브에이전트
• 쓰임: 맡긴 작업이 다시 병렬 하위 작업으로 갈라질 때(원본 예: 발견마다 검증자를 띄우는 리뷰어 서브에이전트). 대화형 세션에서는 최상위 서브에이전트의 요약만 돌아오고, 백그라운드 서브에이전트를 띄운 서브에이전트는 그 결과를 기다린 뒤 끝난다. 비대화형 모드와 Agent SDK에서는 기다리지 않아, 띄운 쪽이 끝난 뒤 끝난 중첩 서브에이전트는 메인 대화에 보고한다. 터미널은 중첩을 트리로 보여 주고 자손이 있는 행에 (+N)을 붙인다. Claude Code 서브에이전트
• 동시 실행: 기본으로 서브에이전트 20개가 도는 중이면 Agent 도구의 새 생성이 Concurrent subagent limit reached로 실패하고 오류가 재시도하지 말라고 알린다(v2.1.217 이상, CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS로 변경, ultracode 세션은 면제). 세션 전체 총수 한도는 없다. /subtask 포크와 끝난 서브에이전트 재개는 한도 확인 없이 자리를 차지한다. Claude Code 서브에이전트

왜 효과가 있나: 컨텍스트 엔지니어링 관점 (2025-09-29 기준)#

Anthropic 엔지니어링 글(2025-09-29)은 서브에이전트 구조를 컨텍스트 창 한계를 넘는 장기 작업 기법 세 가지 중 하나로 든다. 효과적인 컨텍스트 엔지니어링 → 장기 작업 컨텍스트 관리

• 에이전트 하나가 프로젝트 전체 상태를 붙드는 대신, 전문 서브에이전트가 깨끗한 컨텍스트 창에서 초점 있는 작업을 맡는다. 메인 에이전트는 상위 계획을 들고 조율한다. 효과적인 컨텍스트 엔지니어링
• 서브에이전트가 수만 토큰 이상을 쓰며 탐색해도 돌려주는 것은 압축된 요약이다(보통 1,000~2,000 토큰). 효과적인 컨텍스트 엔지니어링
• 관심사가 분리된다. 세부 검색 맥락은 서브에이전트 안에 갇히고, 리드 에이전트는 결과 종합과 분석에 집중한다. 효과적인 컨텍스트 엔지니어링
• Anthropic의 멀티에이전트 리서치 시스템에서 이 패턴은 복잡한 리서치 과제에서 단일 에이전트보다 상당한 개선을 보였다. 원본은 병렬 탐색이 효과를 내는 복잡한 리서치·분석에 멀티에이전트 구조가 맞다고 본다. 효과적인 컨텍스트 엔지니어링

패턴 관점: 오케스트레이터-워커와 병렬화 (2024년 글)#

Anthropic의 에이전트 설계 글은 Claude Code 서브에이전트를 말하지 않는다. 다만 같은 모양의 워크플로 패턴 두 가지를 정의한다. 효과적인 에이전트 만들기 → 에이전트 시스템 패턴 고르기

• 오케스트레이터-워커: 중앙 LLM이 작업을 동적으로 나눠 워커 LLM들에게 맡기고 결과를 종합한다. 필요한 하위 작업을 예측할 수 없는 복잡한 작업(예: 바꿀 파일 수와 변경 성격이 작업마다 다른 코딩, 여러 출처에서 정보를 모아 분석하는 검색)에 잘 맞는다. 효과적인 에이전트 만들기
• 병렬화: 독립적인 하위 작업을 병렬로 돌리거나(분할), 같은 작업을 여러 번 돌려 다양한 출력을 얻는다(투표). 원본은 오케스트레이터-워커와 모양은 비슷하지만, 오케스트레이터-워커는 하위 작업이 미리 정해지지 않고 입력에 따라 오케스트레이터가 정한다는 유연성이 핵심 차이라고 말한다. 효과적인 에이전트 만들기
• 원본은 고려 사항이 여럿인 복잡한 작업에서 각 고려 사항을 별도 LLM 호출이 맡아 하나하나에 집중할 때 LLM이 대체로 더 잘한다고 본다. 효과적인 에이전트 만들기

편집자 해석: 리드 에이전트가 서브에이전트에 일을 맡기고 요약을 받아 종합하는 구조(위 "왜 효과가 있나")는 원본의 오케스트레이터-워커와 같은 모양으로 볼 수 있다. 근거는 오케스트레이터-워커 정의("중앙 LLM이 작업을 동적으로 나눠 워커 LLM에 맡기고 결과를 종합")다. 원본은 동시에 가장 단순한 해법에서 시작해 결과를 입증 가능하게 개선할 때만 복잡도를 더하라고 권한다. 효과적인 에이전트 만들기 → 워크플로와 에이전트

언제 쓰는가#

• 컨텍스트 격리가 필요할 때, 또는 컨텍스트 창이 차 가고 있을 때. Claude Code 확장 기능 개요
• 많은 파일을 읽는 작업, 병렬 작업, 전문 작업자. 원본 예: 많은 파일을 읽지만 핵심 발견만 돌려주는 조사 작업. Claude Code 확장 기능 개요
• 중간 과정이 보일 필요가 없을 때. Claude Code 확장 기능 개요
• 빠르고 초점 있는 작업: 질문 조사, 주장 검증, 파일 리뷰. Claude Code 확장 기능 개요
• (2026-06-18 기준) 스킬 대신 서브에이전트를 고르는 주된 이유가 격리다. 깊은 검색, 로그 분석, 의존성 감사처럼 다시 참고하지 않을 중간 결과로 메인 대화를 어지럽힐 곁가지 작업이면 서브에이전트, 절차가 메인 스레드에서 진행돼 단계마다 보고 조종하고 싶으면 스킬이다. Steering Claude Code
• 셋업 계기: 다시 볼 일 없는 출력으로 대화가 넘치는 곁가지 작업은 서브에이전트로 돌린다. Claude Code 확장 기능 개요 → Claude Code 셋업 점진적으로 키우기

시작할 때 무엇이 로드되는가#

(2026-10-18 기준) 공식 서브에이전트 문서의 목록: 포크가 아닌 서브에이전트는 새로 격리된 컨텍스트로 시작해 대화 기록, 이미 부른 스킬, Claude가 이미 읽은 파일을 보지 못한다. 처음 컨텍스트에 드는 것은 다음과 같다. Claude Code 서브에이전트

• 메인 대화는 결과를 읽을 때 전체 CLAUDE.md를 갖고 있으므로 대부분의 규칙은 서브에이전트에 닿을 필요가 없다고 원본은 말한다. 꼭 닿아야 하는 규칙(원본 예: "ignore the vendor/ directory")은 위임할 때 프롬프트에 다시 적는다. Explore·Plan·omitClaudeMd 서브에이전트도 하위 디렉터리 CLAUDE.md와 경로별 규칙은 그 디렉터리 파일을 다룰 때 로드된다. Claude Code 서브에이전트 → 메모리(CLAUDE.md)
• 포크가 아닌 서브에이전트에 닿지 않는 메인 상태: 출력 스타일(자기 시스템 프롬프트로 돌아서), 메인의 자동 메모리(Auto memory)(대신 memory 필드), 컨텍스트 창 크기(서브에이전트 모델 기준이라 창이 작은 모델에 맡기면 창도 작다). Claude Code 서브에이전트
• extended thinking은 v2.1.198부터 메인 설정을 그대로 물려받는다. 서브에이전트는 메인 대화의 현재 디렉터리에서 시작하고, 안에서 한 cd는 도구 호출 사이에 유지되지 않는다. Claude Code 서브에이전트

이전 수집분(원본별 정리):

• Claude Code 시스템 프롬프트가 아니라 에이전트 자신의 시스템 프롬프트. Claude Code 확장 기능 개요
• skills: 필드에 적힌 스킬의 전체 내용. Claude Code 확장 기능 개요
• 메모리(CLAUDE.md)와 git status. 예외: 내장 Explore·Plan 에이전트는 둘 다 없이 시작하고, 정의에 omitClaudeMd를 둔 에이전트는 user·project·local CLAUDE.md 없이 시작한다. Claude Code 확장 기능 개요
• 리드 에이전트가 프롬프트로 넘겨준 맥락. Claude Code 확장 기능 개요
• 메인 대화의 자동 메모리(Auto memory)는 로드되지 않는다. 서브에이전트는 정의의 memory 필드로 자기 자동 메모리(별도 디렉터리)를 가질 수 있다. Claude Code 메모리
• AGENTS.md를 프로젝트 지시로 읽는 저장소에서, 프로젝트 지시 없이 시작하는 서브에이전트는 AGENTS.md 없이 시작한다. Claude Code 메모리
• (2026-10-18 기준) 공식 컨텍스트 창 문서의 정리: 서브에이전트는 메인보다 짧은 자기 시스템 프롬프트를 받는다(general-purpose 에이전트는 짧은 프롬프트와 환경 정보). CLAUDE.md는 같은 파일을 자기 컨텍스트에 따로 로드하므로 비용이 메인이 아니라 서브에이전트 쪽에 든다(내장 Explore·Plan은 생략). 같은 MCP 서버와 스킬을 쓸 수 있다. 사용자 프롬프트 대신 Claude가 써 준 작업 프롬프트를 받고, 대화 기록은 받지 않는다. 커스텀 에이전트 frontmatter에 memory:가 있으면 메인의 자동 메모리 대신 자기 MEMORY.md를 싣는다. Claude Code 컨텍스트 창
• (2026-10-18 기준) 도구: 부모 도구 대부분을 받되, 중첩 맥락에 맞지 않는 몇 가지는 빠진다. 원본이 든 예는 plan 모드 제어, 백그라운드 작업 도구, 그리고 재귀를 막기 위해 기본으로 빠지는 Agent 도구 자체다. Claude Code 컨텍스트 창

원본끼리 달랐던 점(정리됨)서브에이전트 중첩 한도

• Steering Claude Code (2026-06-18): "subagents can nest up to five levels deep"(서브에이전트는 최대 5단계까지 중첩된다).
• Claude Code 컨텍스트 창 (원본 날짜 미상, 수집 2026-10-18): 서브에이전트는 "by default the Agent tool itself to prevent recursion"(기본으로 Agent 도구 자체를 받지 않는다, 재귀 방지).
• 편집자 해석: 공식 문서가 "기본으로(by default)"라고 한정하므로 설정으로 중첩을 켤 수 있다는 뜻일 수 있지만, 켜는 방법과 5단계 한도는 이 원본에 없다. 수집 대기 중인 공식 서브에이전트 문서로 확인한다. (당시 메모. 아래 해소 근거로 확인됨)
• 2026-10-19 수집: 공식 작동 방식 문서(Claude Code 작동 방식, 수집 2026-10-18)는 중첩을 다루지 않아 이 상충은 그대로다.
• 해소 근거 (2026-10-19 수집): 공식 서브에이전트 문서(Claude Code 서브에이전트, 원본 날짜 미상, 수집 2026-10-18)는 "By default, a subagent can spawn subagents of its own, up to three layers below the main conversation"이라 쓰고, 버전 이력 Note에서 "v2.1.172 through v2.1.216: subagents could nest by default, up to five layers deep, and the limit couldn't be changed", "v2.1.217 through v2.1.218: the limit defaulted to one ... v2.1.219 raised the default to three"라고 밝힌다. 블로그(2026-06-18)의 5단계는 v2.1.172~v2.1.216 시기의 기본값과 맞는다. Agent 도구가 빠지는 것은 이 문서 기준 "깊이 한도에 닿은 서브에이전트"이고, 한도는 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH로 바꾼다.
• 해소로 닫는다. 근거는 공식 서브에이전트 문서의 버전 이력이다: v2.1.172~v2.1.216 최대 5층 고정, v2.1.217~v2.1.218 기본 1층, v2.1.219부터 기본 3층. 블로그의 5단계는 앞 시기의 기본값이다. 자료에 옮길 때는 "기본 3층(v2.1.219부터), CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH로 변경, 1이면 끔"으로 쓴다.
• 남는 표현 차이: 컨텍스트 창 문서는 여전히 "by default the Agent tool itself"가 빠진다고 써 서브에이전트 문서의 지금 기본값(3층)과 표현이 다르다.

• 포크(fork)는 다르다. 부모의 지금까지 대화, 시스템 프롬프트, 도구를 그대로 싣는다(아래 "포크" 절). Claude Code 확장 기능 개요 메인 대화의 자동 메모리를 서브에이전트에 싣지 않는 규칙에서도 포크는 예외다. Claude Code 메모리
• (2026-10-18 기준) 출력 스타일도 같다. 스타일은 메인 대화와, 부모의 대화 전체와 시스템 프롬프트를 물려받는 포크에 적용된다. 다른 서브에이전트는 자기 시스템 프롬프트로 돌아 스타일이 응답을 바꾸지 않는다. Claude Code 출력 스타일

포크: 대화를 물려받는 서브에이전트 (2026-10-18 기준)#

포크는 새로 시작하지 않고 지금까지의 대화 전체를 물려받는 서브에이전트다. 서브에이전트가 주는 입력 격리를 포기하는 대신, 같은 시스템 프롬프트·도구·모델·메시지 기록을 보므로 상황을 다시 설명하지 않고 곁가지 작업을 맡긴다. 포크의 도구 호출은 여전히 메인 대화 밖에 남고 최종 결과만 돌아온다. 원본은 다른 서브에이전트로는 배경 설명이 너무 많이 필요할 때, 같은 출발점에서 여러 접근을 병렬로 시험할 때 쓰라고 한다. Claude Code 서브에이전트

• 시스템 프롬프트와 도구 정의가 부모와 같아 첫 요청이 부모의 프롬프트 캐시를 재사용하고, 그래서 같은 맥락이 필요한 일에서는 새 서브에이전트보다 싸다. 포크는 다시 포크를 띄우지 못한다. Claude Code 서브에이전트 → 컨텍스트 비용
• 직접 띄우기: /subtask <작업>(v2.1.212 이상, v2.1.161~v2.1.211은 /fork). agent view를 끄면 /subtask가 없고 /fork가 포크를 띄운다. 켜져 있으면 /fork는 세션 전체를 새 백그라운드 세션으로 복사한다. 이 /fork는 Claude Code 세션·체크포인트 다루기의 --fork-session·/branch(기록을 새 세션 ID로 복사)와 다른 기능이다. Claude Code 서브에이전트
• 포크 모드: 대화형 세션은 기본으로 켜져 있고(v2.1.232 이상) -p·Agent SDK는 꺼져 있다. 켜져 있으면 Claude가 fork 종류로 포크를 띄울 수 있고, 종류를 지정하지 않으면 general-purpose를 받으며, Claude가 띄우는 서브에이전트가 모두 백그라운드에서 돈다(run_in_background 인자가 사라짐). 단 인프로세스 에이전트 팀 팀원이 띄운 서브에이전트와 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1일 때는 포그라운드이고, context: fork 스킬은 스킬 쪽 규칙을 따른다. CLAUDE_CODE_FORK_SUBAGENT의 1·0으로 바꾸고, 포크만 막으려면 Agent(fork) 거부 규칙을 둔다. Claude Code 서브에이전트
• 포크가 아닌 서브에이전트에는 출력 스타일과 메인 자동 메모리가 닿지 않는다는 규칙에서 포크는 예외다(앞 절). Claude Code 서브에이전트, Claude Code 메모리

스킬을 서브에이전트에서 돌리기: context: fork (2026-10-18 기준)#

스킬 frontmatter에 context: fork를 두면 Claude Code가 agent 필드에 적은 유형의 새 서브에이전트를 띄우고 스킬 내용을 그 프롬프트로 준다. Claude Code 스킬

• 서브에이전트는 대화 기록을 보지 않으므로 스킬 지시만으로 일이 끝나야 한다. 이름과 달리 지금까지의 대화를 넘겨주는 대화 포크가 아니다. 작업이 대화 기록에 의존하면 context: fork 대신 대화를 포크한다. Claude Code 스킬
• agent에는 내장 에이전트(Explore, Plan, general-purpose)나 .claude/agents/의 커스텀 서브에이전트를 쓴다. 생략하면 general-purpose다. agent가 실행 환경(모델, 도구, 권한)을 정한다. Claude Code 스킬
• 내장 Explore·Plan은 CLAUDE.md와 git status 없이 시작하므로, agent: Explore로 포크한 스킬은 스킬 내용과 에이전트 자신의 시스템 프롬프트만 갖는다. 필요한 것은 모두 SKILL.md에 넣는다. Claude Code 스킬
• 포크된 스킬은 기본적으로 백그라운드에서 돌고, 끝나면 결과가 대화에 도착한다. 그 턴에서 결과를 기다리려면 background: false(v2.1.218 이상). -p·Agent SDK 같은 비대화형 모드, 같은 스킬의 이전 호출이 아직 도는 중, 예약 작업에서는 설정과 상관없이 기다린다. Claude Code 스킬
• 백그라운드 포크는 백그라운드 서브에이전트용의 좁은 도구 세트로 돈다. 단계가 그 밖의 도구에 의존하면 background: false로 전체 도구 세트를 유지한다. 또 백그라운드 포크의 편집은 세션 체크포인트 밖에서 일어난다. 그 뒤 /rewind는 대화에서 Claude가 이미 편집한 파일만 복원하고, 스킬이 그 밖의 파일에 한 편집은 남으니 git으로 되돌린다. Claude Code 스킬

근거: Claude Code 스킬. 스킬의 disable-model-invocation: true는 그 스킬이 서브에이전트에 미리 로드되는 것도 막는다. Claude Code 스킬

다른 기능과의 관계#

• vs 스킬: 스킬은 어느 컨텍스트에든 싣는 재사용 콘텐츠(메인 창에 더해짐), 서브에이전트는 별도 창(자체 입력·출력 토큰)을 쓰는 작업자다. 커스텀 서브에이전트는 자기 지시를 갖고 스킬을 미리 실을 수 있다. Claude Code 확장 기능 개요
• vs Dynamic workflow: 서브에이전트는 Claude가 턴마다 다음에 무엇을 돌릴지 정하고, 워크플로는 Claude가 쓴 스크립트가 정한다. 작업이 서브에이전트 몇 개로 감당하기 어려워지거나 결과를 보기 전에 교차 검증하고 싶을 때(코드베이스 전체 감사, 대규모 마이그레이션) 워크플로를 쓴다. Claude Code 확장 기능 개요
• 스폰할 때 Claude가 이름을 붙인 서브에이전트끼리는 서로 메시지를 보낼 수도 있다. Claude Code 확장 기능 개요
• vs 훅 (2026-10-18 기준): 서브에이전트 frontmatter에 훅을 정의하면 그 서브에이전트가 도는 동안만 유효하다. SubagentStart·SubagentStop 이벤트는 에이전트 종류(general-purpose, Explore, Plan, 커스텀 이름)로 거른다. type: "agent" 훅은 파일 읽기·코드 검색 등 도구로 조건을 확인하는 서브에이전트를 띄운다(실험 기능, 기본 타임아웃 60초·도구 사용 최대 50턴). Claude Code 훅 가이드 → Claude Code 훅 설정 레시피
  • (2026-10-18 기준) 공식 훅 레퍼런스가 더하는 것: settings 파일·managed 정책·플러그인의 훅은 서브에이전트 안의 도구 호출에도 같은 PreToolUse·PostToolUse 훅으로 돌고, 입력의 agent_id·agent_type으로 어느 서브에이전트인지 안다. 서브에이전트 frontmatter의 Stop 훅은 SubagentStop으로 바뀐다. 프로젝트 서브에이전트 frontmatter 훅은 그 폴더의 작업 공간 신뢰를 수락한 뒤에만 돌고 -p 세션은 수락으로 치지 않는다(v2.1.218 이상). Claude Code 훅 레퍼런스
  • (2026-10-18 기준) 공식 서브에이전트 문서도 SubagentStart·SubagentStop의 matcher가 프로젝트·사용자 서브에이전트는 frontmatter name, 플러그인 서브에이전트는 my-plugin:db-agent 같은 범위 이름이며 콜론 때문에 고정되지 않은 정규식으로 평가되니 ^my-plugin:db-agent$처럼 고정하라고 확인한다. 원본 예(특정 서브에이전트 시작 때 준비, 모든 서브에이전트 종료 때 정리)는 Claude Code 서브에이전트 만들기·운영에 옮겼다. Claude Code 서브에이전트
  • SubagentStart 훅은 생성을 막지 못하지만 additionalContext를 서브에이전트 대화 시작에 넣는다(같은 사본이 이미 있으면 다시 넣지 않아 프롬프트 캐시를 지키고, 자동 컴팩션이 사본을 버린 뒤에는 다시 넣음). SubagentStop은 decision: "block"과 reason으로 서브에이전트를 계속 일하게 하고, 입력의 last_assistant_message·agent_transcript_path로 결과를 본다. 서브에이전트가 돌아온 뒤 부모 세션에 컨텍스트를 넣으려면 Agent 도구의 PostToolUse를 쓰라고 원본이 말한다. Claude Code 훅 레퍼런스
  • 포그라운드 Agent 호출의 PostToolUse 입력 tool_response에는 status, agentId, content, resolvedModel, totalTokens, totalDurationMs, totalToolUseCount, usage가 온다. totalTokens·usage는 마지막 API 요청만이라 원본은 서브에이전트 전체 비용 집계에 원격 측정 카운터(query_source "subagent")를 쓰라고 한다. 서브에이전트는 기본이 백그라운드라 status: "async_launched"면 사용량 필드가 없다. Claude Code 훅 레퍼런스 → 훅 이벤트 레퍼런스

보안·통제: 무엇이 지켜지고 무엇이 아닌가 (2026-10-18 기준)#

공식 서브에이전트 문서의 통제 수단과 그 조건이다. 문서나 발표에서 "서브에이전트로 권한을 좁힌다"고 말할 때 아래 조건을 함께 쓴다. Claude Code 서브에이전트 → 서브에이전트 정의 파일 레퍼런스

• 도구 제한: tools·disallowedTools로 좁힌다. 단 disallowedTools의 지정자(Bash(git push *))는 도구 전체를 빼고, 명령 단위로 막으려면 permissions.deny를 쓴다. memory 필드를 켜면 Read·Write·Edit가 자동으로 켜진다.
• 권한 모드: 정의의 permissionMode는 메인 대화가 bypassPermissions·acceptEdits·auto면 무시되고, 서브에이전트가 bypassPermissions로 도는 것은 메인도 그 모드일 때뿐이다(v2.1.267 이상). → 권한 모드
• 플러그인 서브에이전트: 보안상 hooks·mcpServers·permissionMode를 무시한다.
• 특정 서브에이전트 끄기 (2026-10-21 기준): permissions.deny의 Agent(AgentName) 규칙이나 --disallowedTools로 끈다(예: "deny": ["Agent(Explore)"]). deny·ask에는 Agent(model:opus), Agent(isolation:worktree)처럼 입력 파라미터 규칙도 쓸 수 있다(값은 Claude가 보낸 글자 그대로, 생략한 파라미터는 맞지 않음). Claude Code 권한 설정 → Claude Code 권한 규칙 문법
• 신뢰: 프로젝트 서브에이전트의 frontmatter 훅(v2.1.218 이상)과 인라인 MCP 서버(v2.1.238 이상)는 그 폴더의 작업 공간 신뢰를 수락한 뒤에만 돈다. 신뢰 전에는 서브에이전트가 훅·서버 없이 그대로 돈다. 상위 폴더 신뢰와 -p 세션은 신뢰로 치지 않는다. ~/.claude/agents/와 --agents는 이 확인을 받지 않는다. 공식 권한 문서(2026-10-21)의 신뢰 전 실행 표도 프로젝트 서브에이전트 frontmatter 훅과 저장소·--add-dir 디렉터리의 인라인 mcpServers를 상위 폴더 신뢰·-p·SDK 모두에서 "Not used"로 적는다. → 작업 공간 신뢰
• worktree 격리: isolation: worktree 서브에이전트의 Bash·PowerShell 명령이 메인 체크아웃으로 가면 실패하고, Bash는 git을 메인 체크아웃으로 돌리는 명령과 git이 worktree 안에 머무는지 텍스트로 확인할 수 없는 명령을 거부한다. PowerShell은 작업 디렉터리 검사만 받는다. v2.1.210 이전에는 검사 범위가 실행 디렉터리 자체뿐이었다. 예외: 에이전트 팀이 켜진 대화형 세션에서 메인이 name을 붙여 띄운 서브에이전트는 팀원으로 뜨고(포크이거나 호출 자체에 isolation을 넘긴 경우는 제외), 이때 frontmatter의 isolation은 이를 막지 못해 팀원은 메인 세션의 작업 디렉터리에서 돈다. Claude는 묻지 않고 name을 붙일 수 있다.
• 샌드박스 (2026-10-21 기준): 서브에이전트는 부모 세션과 같은 프로세스에서 같은 샌드박스 구성으로 돈다. 부모 세션에서 샌드박스가 켜져 있으면 서브에이전트의 Bash 명령도 샌드박스 안에서 돈다. 백그라운드 세션은 자기 프로세스에서 돌고 그 세션 설정이 샌드박스를 켤 때만 샌드박스에 들어간다. Claude Code 샌드박스 → 샌드박스
• 백그라운드 승인: 백그라운드 서브에이전트의 권한 확인은 메인 세션에 뜨고, 그 한 번을 넘어 지속되는 승인은 메인 대화를 포함한 세션 전체에 적용된다.
• 에이전트 메시지: 서브에이전트는 띄운 에이전트의 메시지를 작업 지시로 따르되, 어떤 에이전트의 메시지도 대기 중인 권한 확인의 승인이 되지 않고 권한 설정·CLAUDE.md·구성을 바꿀 수 없다.
• 출력 검사(v2.1.210 이상): Claude가 읽기 전에 최종 보고서에서 Claude Code 출력을 흉내 낸 텍스트에 백슬래시를 넣고, 그런 태그나 권한 설정 언급이 있으면 표시 줄을 붙인다. 보고서는 서브에이전트의 말이고 사용자 권한이 없다는 머리글과 함께 도착한다. 원본은 이 검사가 악의 여부를 판단하지 않고, 아무것도 지우거나 고쳐 쓰지 않고 백슬래시 삽입과 표시 줄 추가 두 가지만 하며, 보고서가 이끄는 도구 호출은 여전히 권한 검사·샌드박스를 거치고, 서브에이전트가 닿는 범위를 제한하는 것을 대신하지 않는다고 밝힌다.

자동 모드에서의 검사 (2026-10-18 기준)#

권한 모드의 자동 모드 분류기는 서브에이전트를 세 지점에서 본다. Claude Code 권한 모드

1. 시작 전: 위임한 작업 설명을 평가해, 위험해 보이는 작업은 스폰 때 막는다.
2. 실행 중: 서브에이전트의 각 동작이 부모 세션과 같은 판정 순서·차단·허용 규칙을 거친다. 서브에이전트 frontmatter의 permissionMode는 무시된다.
3. 끝난 뒤: 부모가 보고서를 읽기 전에 작업과 최종 보고서를 검토한다. 문제가 보이면 보고서는 그대로 전달되되 앞에 보안 경고가 붙고, 분류기를 쓸 수 없으면 행동 전에 작업을 확인하라는 메모가 붙는다.

또한 분류기는 Claude가 SendMessage로 다른 에이전트에게 보내는 메시지를 전달 전에 검토한다(v2.1.222 이상). 같은 멀티 에이전트 세션 안에서 함께 일하는 에이전트끼리의 메시지는 기본 허용이다. Claude Code 권한 모드

다른 도구에서#

Claude Cowork도 복잡한 작업에서는 서브에이전트 여러 개를 병렬로 띄울 수 있다. 사용자가 직접 정의하는지는 원본(입문 가이드)에 나오지 않는다. Claude Cowork 시작하기

Antigravity CLI (2026-10-21 기준, 표시한 문장은 해당 날짜)#

(2026-05-19 공지) Google은 Gemini CLI의 노력을 Antigravity CLI로 모은 이유로, 사용자에게 여러 에이전트가 서로 소통하며 일을 나눠 복잡한 문제를 푸는 방식이 필요해졌다는 점을 든다. 공지는 Antigravity CLI가 Gemini CLI의 핵심 기능 가운데 Subagents를 유지한다고 말한다. Gemini CLI의 Antigravity CLI 전환 공지 (2026-06-18) Gemini CLI 저장소 공지는 Antigravity CLI를 설치할 때 기존 에이전트 프로필과 구성이 그대로 남는다고 말한다. Gemini CLI 개인 계정 요청 처리 중단 공지

Antigravity 공식 서브에이전트 문서(원본 날짜 미상, 수집 2026-10-21)가 정의 방법과 동작을 적는다. 아래는 이 문서 기준이다. Antigravity 서브에이전트 문서

• 비동기 백그라운드: CLI는 오래 걸리는 빌드, 큰 코드베이스 검색, 여러 파일 편집을 병렬 서브에이전트나 백그라운드 작업에 넘겨 터미널 세션을 막지 않는다. 공지(2026-05-19)의 "터미널 세션을 막지 않고 여러 에이전트를 백그라운드로 조율한다"는 설명을 공식 문서가 확인한다.
• 띄우는 방식: 부모 에이전트가 invoke_subagent 도구로 역할과 첫 프롬프트를 정해 동시 세션을 띄운다. 작업공간은 부모와 같은 곳(inherit), 격리된 Git worktree(branch), 디렉터리 저장소 공유(share) 중 하나다. 서브에이전트는 부모의 대화 기록을 물려받지 않고 새로 시작한다.
• 내장 서브에이전트: research(코드베이스 조사), browser(샌드박스 브라우저 테스트, /browser로만 호출), self(부르는 에이전트의 복제).
• 사용자 정의: YAML frontmatter와 본문(시스템 프롬프트)으로 된 Markdown 파일. 워크스페이스 .agents/agents/<name>.md 또는 .agents/agents/<name>/agent.md, 전역 ~/.gemini/config/agents/(CLI 절 기준). 원본 앞쪽 App 절의 위치 표는 플러그인 plugins/<plugin_name>/agents/도 든다. 필수 필드는 name·description이고, tools, model(inherit·flash·pro), commandExecutionPolicy(기본 sandbox), mcpServers, skills·plugins, mainAgent·subagent를 둔다. 세션 중에는 define_subagent 도구로 임시 서브에이전트를 만든다. 필드 표는 Antigravity CLI의 "서브에이전트" 절.
• 상태와 소통: Running·Idle·Killed. Idle 서브에이전트는 메시지를 받으면 이전 맥락을 유지한 채 다시 깨어난다. 에이전트끼리 대화 ID로 메시지를 주고받고 서로의 대화 기록을 읽을 수 있다. Killed되면 임시 worktree는 자동으로 정리된다.
• 확인: CLI에서 /agents로 Agent Manager 패널을 열어 상태·현재 단계를 보고, Enter로 상세 보기(추론 기록·도구 호출·출력)에 들어간다. Alt+J는 승인을 기다리는 다음 서브에이전트로 이동, Ctrl+K는 대기 동작을 바로 승인한다.

보안·통제의 조건(원본 기준): 서브에이전트는 부모의 허용된 터미널 명령 접두사, 파일 읽기·쓰기 범위, 샌드박스 설정을 물려받고, 사용자 승인이 필요한 도구 실행은 메인 화면이나 서브에이전트 패널로 올라온다. 반대로 부모는 서브에이전트의 작업공간(격리된 worktree 포함)에 전부 접근할 수 있다. 중첩은 메인 에이전트 아래 최대 10단계로 강제된다("strictly enforced"). 원본이 말하지 않는 것도 있다. frontmatter commandExecutionPolicy와 물려받은 샌드박스 설정이 다를 때 어느 쪽이 이기는지, 같은 이름의 정의가 여러 곳에 있을 때의 우선순위는 없다. 또 원본은 알려진 문제로, tools에 없는 도구 이름이나 오타를 쓰면 서브에이전트가 실행 중 멈출 수 있다고 적는다. Antigravity 서브에이전트 문서

편집자 해석: 정의 방식(YAML frontmatter + 본문이 시스템 프롬프트, name·description 필수, tools·model·mcpServers·skills 필드)은 위 Claude Code 서브에이전트 정의 파일과 구성이 비슷하다고 볼 수 있다. 다만 Antigravity 문서는 Claude Code를 언급하지 않고, 위치(.agents/agents/ 대 .claude/agents/), model 값, 중첩 한도(Antigravity 10단계, Claude Code 기본 3층)가 각 원본에서 다르다. 그래서 같은 파일을 두 도구에서 그대로 쓸 수 있다고 볼 근거는 없다. Antigravity 서브에이전트 문서, Claude Code 서브에이전트

레벨이 겹칠 때#

같은 이름의 서브에이전트가 여러 레벨에 있으면 우선순위로 하나만 이긴다: managed > CLI 플래그 > project > user > plugin. Claude Code 확장 기능 개요 공식 서브에이전트 문서(2026-10-18 기준)도 같은 순서를 확인하고, 중첩된 프로젝트 디렉터리끼리는 작업 디렉터리에 가장 가까운 것이 이기며, 같은 디렉터리 트리 안의 이름 중복은 파일 시스템 읽기 순서로 하나만 로드된다고 더한다(/doctor가 보고). Claude Code 서브에이전트 → 서브에이전트 정의 파일 레퍼런스

조직 통제(2026-10-18 기준): managed disableSideloadFlags는 시작 때 --agents 플래그를 거부하고(v2.1.193 이상), strictPluginOnlyCustomization은 user·project 출처의 에이전트를 막을 수 있다. Claude Code managed settings 배포 → managed settings