서브에이전트를 나눠야 할 시점은 비교적 명확합니다. 작업이 단일 컨텍스트 윈도우를 초과하거나, 의존성 없는 작업을 병렬로 실행해 처리 시간을 실질적으로 단축할 수 있는 경우입니다. Claude Code 서브에이전트 구조를 이해하면, 분리가 이득인 상황과 복잡도만 높아지는 상황을 구분해 적용할 수 있습니다.
분리 기준
서브에이전트가 필요한 상황은 언제인가?
Claude Code 공식 문서 기준, 서브에이전트는 Task 도구를 통해 생성합니다. 오케스트레이터가 전체 워크플로를 계획하고, 개별 태스크를 하위 에이전트에 위임하는 방식입니다.
분리를 검토할 조건은 두 가지입니다. 단일 처리 흐름이 200K 토큰 컨텍스트 한도를 초과할 것으로 예상될 때, 또는 서로 의존성이 없는 작업을 동시에 실행해 처리 시간을 단축할 수 있을 때입니다.
반대로, 이런 경우에는 분리가 역효과입니다. 작업 간 결과를 빈번하게 주고받아야 한다면 에이전트 간 통신 오버헤드가 커집니다. 단순한 순차 작업에 서브에이전트를 붙이면 디버깅 포인트만 늘어납니다.
구조 이해
Claude Code 5계층 구조는 어떻게 구성되나?
다중 에이전트 환경은 다음 5계층으로 구분할 수 있습니다.
1계층 — 오케스트레이터: 사용자 지시를 받는 메인 Claude 인스턴스입니다. 전체 워크플로를 계획하고 하위 에이전트에 태스크를 위임합니다.
2계층 — 서브에이전트: Task 도구로 생성된 하위 인스턴스입니다. 각각 독립적인 컨텍스트를 가지며, 할당된 태스크만 처리합니다.
3계층 — MCP 서버: Model Context Protocol을 통해 에이전트에 추가 도구를 공급하는 계층입니다. 파일 시스템 접근, 외부 API 호출, 데이터베이스 연결 등을 확장합니다.
4계층 — Hooks: 에이전트 실행 중 특정 이벤트(PreToolUse, PostToolUse, Stop 등)에 개입하는 계층입니다. 승인 흐름 삽입이나 실행 로그 기록에 활용합니다.
5계층 — 컨텍스트/메모리: CLAUDE.md 파일, 메모리 파일, 세션 상태가 여기에 해당합니다. 각 에이전트가 참조하는 공유 지식 기반입니다.
MCP·Hooks 설정
MCP 연동과 Hooks는 어떻게 설정하나?
Claude Code 공식 문서에 따르면 MCP 서버는 .claude/settings.json 의 mcpServers 항목에 등록합니다. 서버 이름과 실행 명령어 경로를 JSON으로 정의하면 Claude Code 시작 시점에 자동으로 로드됩니다. 글로벌 적용이 필요하면 ~/.claude/settings.json 에 동일하게 등록합니다.
Hooks는 같은 설정 파일의 hooks 섹션에서 이벤트와 실행 명령어를 매핑하는 방식으로 동작합니다. PreToolUse 훅으로 특정 도구 호출 전에 확인 절차를 삽입하거나, PostToolUse 훅으로 결과를 외부 시스템에 기록할 수 있습니다. 훅 스크립트가 비정상 종료 코드를 반환하면 해당 도구 호출 자체를 차단하는 것도 가능합니다.
Hooks는 비교적 최근에 추가된 기능입니다. 프로덕션 워크플로에 연결하기 전에 현재 릴리스 노트를 먼저 확인하는 것이 안전합니다.
한계·트레이드오프
계층이 많아질수록 어떤 문제가 생기나?
서브에이전트 계층이 깊어질수록 오류 전파 경로가 늘어납니다. 오케스트레이터가 잘못된 지시를 내리면 하위 에이전트 전체가 동일한 방향으로 처리를 진행합니다. 추적 로그 없이는 어느 계층에서 문제가 발생했는지 파악하기 어렵습니다.
비용 측면도 고려해야 합니다. 각 서브에이전트는 독립적인 API 호출을 소비합니다. 작업 단위가 작고 빈번하다면, 단일 에이전트로 순차 처리하는 방식이 더 경제적일 수 있습니다.
컨텍스트 공유도 제한적입니다. 서브에이전트는 오케스트레이터로부터 위임받은 정보만 참조하며, 다른 서브에이전트의 작업 결과에 직접 접근하지 못합니다. 공유 상태가 필요하면 파일이나 외부 저장소를 경유해야 합니다.
적용 기준
어떤 작업에 서브에이전트를 쓰고, 어떤 작업에는 안 쓰는가?
적합한 시나리오: – 대규모 코드베이스 분석 — 여러 모듈을 독립적으로 분석하고 결과를 취합하는 경우 – 병렬 테스트 실행 — 서로 의존성 없는 테스트 스위트를 동시에 처리하는 경우 – 멀티 파일 리팩토링 — 파일 단위로 작업을 분산해 컨텍스트 한도를 회피하는 경우
부적합한 시나리오: – 단계별 결과가 다음 단계 입력이 되는 순차 파이프라인 — 에이전트 간 통신 오버헤드가 커짐 – 단일 파일 소규모 수정 — 오케스트레이터 하나로 충분하며, 서브에이전트 생성 비용이 낭비 – 실시간 상태 공유가 필요한 작업 — 컨텍스트 격리 특성상 직접 공유가 불가능
Claude Code 공식 문서는 “네트워크 연결된 자율 에이전트 환경에서는 권한을 신중하게 부여하라”고 명시합니다. 서브에이전트에 부여하는 도구 권한은 필요 최소한으로 제한하는 것이 기본 원칙입니다.
자주 묻는 질문
Q. 서브에이전트는 몇 계층까지 중첩할 수 있나요?
A. 공식 문서에 최대 깊이 제한은 없습니다. 계층이 깊어질수록 비용과 디버깅 복잡도가 비례해 늘어납니다.
Q. 서브에이전트와 오케스트레이터는 컨텍스트를 공유하나요?
A. 직접 공유하지 않습니다. Task 도구로 넘긴 프롬프트 내용만 서브에이전트의 컨텍스트가 됩니다.
Q. MCP 서버 연동에 별도 비용이 드나요?
A. MCP 프로토콜 자체는 오픈소스 무료입니다. 연결하는 외부 서비스(GitHub, Notion 등)는 각 서비스 요금 정책을 따릅니다.
Q. Hooks 설정이 잘못되면 에이전트 실행이 멈추나요?
A. 훅 스크립트가 비정상 종료 코드를 반환하면 해당 도구 호출을 차단할 수 있습니다. 프로덕션 연결 전 테스트 환경 검증이 필요합니다.
Q. 서브에이전트를 많이 쓰면 요금이 늘어나나요?
A. 서브에이전트가 늘어날수록 API 호출량이 비례해 늘어납니다. Anthropic 공식 요금 페이지에서 모델별 토큰 단가를 확인하는 것이 필요합니다.
공식 근거로 확인한 핵심과 한계만 정리합니다. Claude Code 서브에이전트 구조는 컨텍스트 한도를 넘는 대규모 작업이나 병렬 처리에서 실용적입니다. 하지만 계층이 늘어날수록 API 비용과 디버깅 복잡도도 함께 높아집니다. Task 도구로 분리하기 전에, 그 분리가 실제로 이득인지를 먼저 따져보고, 서브에이전트에 부여하는 권한은 최소 범위로 유지하는 것이 공식 문서의 기본 권고입니다.
Leave a Reply