서브에이전트(subagent)는 독립된 컨텍스트 윈도우에서 하위 작업을 수행하고 요약된 결과만 부모에게 돌려주는 실행 단위입니다. 이 수업에서는 컨텍스트 격리의 이점, 서브에이전트에 무엇을 넘겨야 하는지, 병렬 실행 시 주의점을 다룹니다.
컨텍스트 격리가 해결하는 문제
단일 에이전트로 큰 작업을 처리하면 컨텍스트 윈도우가 중간 산출물로 가득 찹니다. 파일 100개를 검색한 기록, 실패한 시도의 로그, 장황한 도구 출력이 모두 쌓이면 정작 중요한 판단에 쓸 공간이 줄고, 모델이 오래전 맥락을 놓치기 시작합니다.
서브에이전트는 이 문제를 **격리(isolation)**로 풉니다. 부모 에이전트가 하위 작업을 서브에이전트에 위임하면, 서브에이전트는 자기만의 깨끗한 컨텍스트 윈도우에서 작업합니다. 탐색 과정의 방대한 중간 결과는 서브에이전트의 컨텍스트에서 소비되고, 부모에게는 최종 요약만 돌아갑니다.
Claude Code의 Task 도구가 대표적인 구현입니다. "이 리포지토리에서 인증 로직이 어디 있는지 찾아라"를 서브에이전트에 맡기면, 수십 번의 grep과 파일 읽기는 서브에이전트 안에서 일어나고 부모는 "src/auth/session.ts의 validateSession()이 핵심"이라는 결론만 받습니다.
부모 컨텍스트에 남는 것:
Task("인증 로직 위치 찾기") → "src/auth/session.ts:42 validateSession()이 진입점"
서브에이전트 컨텍스트에서 소비된 것 (부모에게 보이지 않음):
Grep "auth" → 87개 파일 매칭
Read src/auth/... (12개 파일, 수천 줄)
실패한 탐색 경로들
핵심 트레이드오프도 있습니다. 서브에이전트는 부모의 대화 맥락을 (별도로 전달하지 않는 한) 모릅니다. 격리는 컨텍스트 절약인 동시에 정보 차단이므로, 무엇을 넘기고 무엇을 돌려받을지 명시적으로 설계해야 합니다.
서브에이전트 프롬프트에 넘겨야 할 것
서브에이전트 실패의 대부분은 모델 능력이 아니라 불충분한 작업 지시 때문입니다. Anthropic의 멀티 에이전트 리서치 시스템 구축기는 서브에이전트에게 "목표, 출력 형식, 사용할 도구와 출처에 대한 지침, 명확한 작업 경계"를 줘야 한다고 정리합니다. 부모의 머릿속에 있는 맥락은 서브에이전트에게 자동으로 전달되지 않습니다.
체크리스트로 정리하면:
- 목표 — 무엇을 알아내거나 만들어야 하는가. "인증 관련 코드를 봐라"(모호) 대신 "세션 만료 버그의 원인 후보 파일을 3개 이내로 특정하라"(명확).
- 출력 형식 — 돌려줄 결과의 구조. 파일 경로 목록인지, 요약문인지, JSON인지.
- 경계 — 하지 말아야 할 것. "파일을 수정하지 마라", "src/legacy/는 무시하라".
- 판단 기준 — 모호한 상황에서의 우선순위. "여러 후보가 있으면 최근 수정된 쪽을 우선하라".
# Agent SDK로 서브에이전트를 정의하는 예 (agents 옵션)
options = ClaudeAgentOptions(
agents={
"code-searcher": {
"description": "코드베이스에서 특정 로직의 위치를 찾는 읽기 전용 탐색자",
"prompt": "파일을 수정하지 말 것. 결과는 경로:줄번호 목록과 "
"한 문단 요약으로 보고할 것.",
"tools": ["Read", "Grep", "Glob"], # 편집 도구 제외
}
}
)
도구 목록 제한은 지시의 일부입니다. 탐색 전용 서브에이전트에서 편집 도구를 빼면 "수정하지 마라"는 지시를 구조적으로 강제할 수 있습니다. 시험에서는 "서브에이전트는 부모의 대화 이력을 자동으로 상속한다"는 오답이 자주 나옵니다. 기본적으로 상속하지 않으며, 필요한 맥락은 프롬프트에 담아 명시적으로 넘겨야 합니다.
병렬 서브에이전트와 결과 종합
서로 독립적인 하위 작업이라면 서브에이전트를 병렬로 띄울 수 있습니다. Anthropic의 리서치 시스템은 리드 에이전트가 조사 계획을 세운 뒤 3~5개의 서브에이전트를 동시에 실행해 서로 다른 측면을 조사하게 했고, 이것이 순차 실행 대비 조사 시간을 크게 줄였다고 보고합니다.
병렬화 시 설계 포인트는 세 가지입니다.
첫째, 작업이 정말 독립적인지 확인합니다. 서브에이전트 A의 결과가 B의 입력이 되어야 한다면 병렬이 아니라 순차입니다. 또 두 서브에이전트가 같은 파일을 동시에 수정하면 충돌합니다. 쓰기 작업을 병렬화할 때는 파일 단위로 소유권을 나누거나 워크트리(worktree) 같은 격리 수단을 씁니다.
둘째, 중복 조사를 막기 위해 경계를 명시합니다. "A는 백엔드 라우팅만, B는 프런트엔드 상태 관리만"처럼 담당 영역을 프롬프트에 못 박지 않으면 여러 서브에이전트가 같은 곳을 파며 토큰을 낭비합니다.
셋째, 종합 단계를 설계합니다. 병렬 결과는 자동으로 합쳐지지 않습니다. 부모가 결과들을 받아 모순을 해소하고 우선순위를 정하는 종합 턴이 필요합니다.
results = await asyncio.gather(
run_subagent("보안 관점에서 diff 리뷰", diff),
run_subagent("성능 관점에서 diff 리뷰", diff),
run_subagent("테스트 누락 관점에서 diff 리뷰", diff),
)
final = await lead_agent(f"세 리뷰를 종합해 중복을 제거하고 심각도순으로 정렬:\n{results}")
비용 감각도 시험 범위입니다. 멀티 에이전트 구조는 단일 대화보다 토큰을 몇 배 이상 쓰는 것이 보통입니다. 병렬 서브에이전트는 작업 가치가 토큰 비용을 정당화할 때 쓰는 도구이지 기본값이 아닙니다.
시험 함정
- 서브에이전트가 부모의 대화 이력을 자동 상속한다는 오답 — 필요한 맥락은 프롬프트로 명시적으로 전달해야 합니다.
- 서브에이전트의 모든 중간 결과가 부모 컨텍스트에 쌓인다는 오답 — 부모에게는 최종 보고만 돌아오는 것이 격리의 핵심입니다.
- 의존 관계가 있는 작업을 병렬 서브에이전트로 처리하는 선택지 — A의 출력이 B의 입력이면 순차 실행해야 합니다.
- 탐색 전용 서브에이전트에 편집 도구를 포함한 구성을 정답처럼 제시하는 함정 — 도구 제한은 역할 강제의 수단입니다.
- 멀티 에이전트가 항상 비용 효율적이라는 오답 — 일반적으로 단일 대화보다 토큰을 훨씬 많이 씁니다.
실습 시나리오
실제 시험과 같은 형식의 시나리오 문제입니다.
리드 에이전트가 대규모 리포지토리 감사를 위해 서브에이전트 4개를 병렬 실행하려 합니다. 각 서브에이전트 프롬프트에 반드시 포함해야 할 요소의 조합으로 가장 적절한 것은?
빌드 연습 · 탐색 서브에이전트로 코드베이스 감사하기
약 45분1.감사 관점 정의
보안·성능·의존성 세 관점의 감사 범위를 각각 한 문단으로 정의합니다.
기대 결과 · 세 관점의 담당 영역이 겹치지 않게 문서화되어 있습니다.
2.서브에이전트 프롬프트 작성
각 관점에 목표·출력 형식·경계·도구 제한을 담은 프롬프트를 작성합니다.
기대 결과 · 세 프롬프트 모두 '파일 수정 금지'와 보고 형식(경로:줄번호 + 심각도)이 명시되어 있습니다.
3.병렬 실행
Claude Code의 Task 도구 또는 Agent SDK의 agents 옵션으로 세 서브에이전트를 동시에 실행합니다.
기대 결과 · 세 작업이 동시에 시작되고 각각 독립적으로 완료됩니다.
4.종합 턴 구현
세 보고서를 받아 중복 제거·심각도 정렬을 수행하는 종합 프롬프트를 실행합니다.
기대 결과 · 최종 보고서에 중복 항목이 없고 심각도순으로 정렬되어 있습니다.
5.비용 비교
같은 감사를 단일 대화로 수행했을 때와 토큰 사용량을 비교합니다.
기대 결과 · 멀티 에이전트 구성의 토큰 배수가 수치로 기록됩니다.