클로드 코드 서브에이전트 완전정복 (총 9편) | 2편 서브에이전트 개념 이해 — 독립 컨텍스트와 역할 분리의 핵심

시리즈: 클로드 코드 서브에이전트 완전정복 (총 9편) | 2편

서브에이전트 개념 이해 — 독립 컨텍스트와 역할 분리의 핵심

Claude Code 서브에이전트가 뭔지 모호하게만 느껴지나요? 독립 컨텍스트와 역할 분리라는 두 가지 핵심 원리를 잡으면 한방에 이해돼요. 이 글에서 공식 정의부터 6가지 구성요소, 네스팅 금지 같은 안전장치까지 실무에 바로 쓸 수 있게 정리해 드릴게요.

Summary

• 서브에이전트는 "특정 유형의 작업을 처리하는 전문화된 AI 어시스턴트"로 공식 정의돼요
• 각 서브에이전트는 독립된 컨텍스트 창에서 자기만의 시스템 프롬프트로 실행돼요
• "서브"는 위계가 아니라 책임의 범위를 제한한다는 의미예요
• 네스팅 금지(서브가 서브를 못 부름) 같은 안전장치가 설계에 내장되어 있어요

이 글의 대상

• 1편을 읽고 Claude Code의 플랫폼 구조를 이해한 분
• 서브에이전트라는 단어는 들어봤지만 정확한 개념이 잡히지 않는 분
• 에이전트 기반 작업 분리를 실무에 적용하고 싶은 개발자

목차

• 서브에이전트 공식 정의
• 독립 컨텍스트가 왜 중요한지
• 서브에이전트의 구성요소 6가지
• Task 도구로 호출하고 결과 받기
• "서브"의 진짜 의미 — 위계가 아닌 책임 범위
• 네스팅 금지 — 왜 서브가 서브를 못 부를까
• 핵심 정리
• FAQ
• 참고 자료
• 다음 편 예고

---

서브에이전트 공식 정의

한 줄 요약: "특정 유형의 작업을 처리하는 전문화된 AI 어시스턴트"가 공식 정의예요.

Anthropic의 Claude Code 공식 문서에서는 서브에이전트를 이렇게 정의해요:

"specialized AI assistants that handle specific types of tasks"

쉽게 말하면, 메인 에이전트가 혼자 다 하는 게 아니라 "이 일은 네가 맡아"라고 전문가를 불러서 위임하는 구조예요. 회사에서 프로젝트 매니저가 디자이너, 개발자, QA 각각에게 일을 나눠주는 것과 비슷하죠.

핵심은 전문화예요. 아무 일이나 시키는 게 아니라, 특정 유형의 작업에 맞춰 역할이 정해진 에이전트를 만드는 거예요.

---

독립 컨텍스트가 왜 중요한지

한 줄 요약: 각 서브에이전트가 별도의 컨텍스트 창에서 실행되기 때문에 역할 간 정보가 섞이지 않아요.

이게 서브에이전트의 가장 중요한 특징이에요. 일반적으로 AI와 대화하면 하나의 대화 맥락(컨텍스트) 안에서 모든 게 공유되잖아요. 코드 리뷰 이야기하다가 문서 작성 이야기하면 앞의 맥락이 뒤에 영향을 줘요.

서브에이전트는 달라요. 각각 완전히 독립된 컨텍스트 창에서 돌아가거든요.

구분	공유 컨텍스트	독립 컨텍스트 (서브에이전트)
정보 범위	전체 대화 내용 공유	자기 작업에 필요한 것만
간섭 가능성	다른 작업 맥락이 섞일 수 있음	격리되어 있어 간섭 없음
집중도	맥락이 길어지면 분산	좁은 범위에 높은 집중
보안	모든 정보에 접근 가능	허용된 범위만 접근

이걸 왜 이렇게 만들었냐면, 실제로 사람도 그렇게 일하잖아요. 코드 리뷰어한테 "지금 작성 중인 마케팅 문서도 같이 봐줘"라고 하면 오히려 집중이 흐트러지잖아요. 각자 맡은 일에 집중하는 게 결과물이 더 좋은 것처럼, 서브에이전트도 독립 컨텍스트에서 자기 역할에만 집중하는 거예요.

---

서브에이전트의 구성요소 6가지

한 줄 요약: 시스템 프롬프트, 도구 설정, 권한, 모델, 턴 제한, 메모리 — 이 6가지로 서브에이전트의 행동이 결정돼요.

서브에이전트를 정의할 때 설정하는 핵심 구성요소를 살펴볼게요.

1. 시스템 프롬프트 (System Prompt)

서브에이전트의 역할과 행동 규칙을 정해주는 지침이에요. "너는 코드 리뷰 전문가야. 보안 취약점에 특히 집중해"처럼 역할을 명확히 부여하는 거죠.

2. tools / disallowedTools

이 서브에이전트가 쓸 수 있는 도구와 쓸 수 없는 도구를 지정해요. 코드 리뷰 서브에이전트에게 파일 삭제 권한을 안 주는 식으로 안전하게 관리할 수 있어요.

3. permissionMode

권한 수준을 설정해요. 얼마나 자율적으로 행동할 수 있는지를 결정하는 거예요.

4. model

어떤 AI 모델을 사용할지 지정할 수 있어요. 간단한 작업엔 가벼운 모델을, 복잡한 판단이 필요한 작업엔 강력한 모델을 배정할 수 있죠.

5. maxTurns

서브에이전트가 최대 몇 번의 턴(행동 단계)을 거칠 수 있는지 제한해요. 무한 루프에 빠지는 걸 방지하는 안전장치 역할도 해요.

6. memory (user / project / local)

서브에이전트가 접근할 수 있는 메모리 범위를 설정해요. 사용자 수준, 프로젝트 수준, 로컬 수준으로 나뉘는데, 필요한 범위만 열어주는 게 원칙이에요.

구성요소	역할	예시
시스템 프롬프트	역할·행동 규칙 정의	"보안 리뷰 전문가로 동작해"
tools	사용 가능 도구 지정	Read, Grep만 허용
disallowedTools	사용 금지 도구 지정	Write, Bash 금지
permissionMode	자율성 수준	읽기만 가능 / 쓰기도 가능
model	사용 모델	claude-opus-4-6 / claude-sonnet-4
maxTurns	최대 행동 횟수	10턴으로 제한

---

Task 도구로 호출하고 결과 받기

한 줄 요약: 메인 에이전트가 Task 도구를 통해 서브에이전트를 호출하고, 작업 결과를 돌려받는 구조예요.

서브에이전트를 부르는 방식은 간단해요. 메인 에이전트가 Task 도구를 사용해서 호출하면 돼요.

흐름을 보면:

메인 에이전트
    │
    ├── Task 도구 호출 ("이 코드를 리뷰해줘")
    │       │
    │       └── 서브에이전트 실행 (독립 컨텍스트)
    │               │
    │               ├── 파일 읽기
    │               ├── 분석
    │               └── 결과 생성
    │       │
    │       └── 결과 반환
    │
    └── 결과를 받아서 다음 작업 진행

중요한 건, 서브에이전트의 작업 결과만 메인으로 돌아온다는 거예요. 서브에이전트가 내부적으로 어떤 파일을 읽었는지, 몇 번의 시도를 했는지 같은 과정은 메인 컨텍스트를 오염시키지 않아요. 깔끔하죠.

---

"서브"의 진짜 의미 — 위계가 아닌 책임 범위

한 줄 요약: "서브"에이전트의 "서브"는 하위 직급이 아니라 책임의 범위를 좁혔다는 뜻이에요.

이름 때문에 오해하기 쉬운데요, "서브"가 "하위"를 뜻하는 게 아니에요. 서브에이전트가 메인 에이전트보다 덜 똑똑하거나 급이 낮은 게 아니라는 거죠.

"서브"의 진짜 의미는 책임 범위의 제한이에요.

비유를 들어볼게요. 병원에서 외과 전문의, 마취 전문의, 간호사가 팀을 이루잖아요. 외과의가 "메인"이라고 해서 마취의가 "하위"인 건 아니에요. 각자 전문 영역이 다르고, 책임 범위가 다른 거죠. 마취의는 마취에 대해서만 전문적으로 책임지는 거예요.

서브에이전트도 마찬가지예요:

• 메인 에이전트: 전체 작업 흐름을 조율하고 최종 결과를 책임져요
• 서브에이전트: 맡은 특정 영역에서 전문적으로 판단하고 결과를 내놔요

이 "범위 제한"이 오히려 장점이에요. 범위가 좁으니까 더 깊이 집중할 수 있거든요.

---

네스팅 금지 — 왜 서브가 서브를 못 부를까

한 줄 요약: 서브에이전트가 또 다른 서브에이전트를 호출하는 건 금지되어 있어요 — 복잡성 폭발과 통제 상실을 막기 위한 설계 결정이에요.

Claude Code에는 중요한 제약이 하나 있어요. 서브에이전트는 다른 서브에이전트를 호출할 수 없어요. 이걸 "네스팅(nesting) 금지"라고 해요.

왜 이런 제약을 뒀을까요?

문제	네스팅 허용 시	네스팅 금지 시
복잡성	호출 체인이 기하급수적으로 복잡해짐	항상 메인 → 서브 1단계로 단순
디버깅	어디서 문제가 생겼는지 추적 어려움	문제 위치를 바로 파악 가능
비용	예측 불가능한 토큰/비용 소모	비용 예측과 통제 가능
통제권	메인이 전체를 파악하기 어려움	메인이 항상 전체를 통제
무한 루프	서브 → 서브 → 서브... 위험	구조적으로 불가능

이건 단순히 기술적 제약이 아니라 운영 안전장치예요. 메인 에이전트가 항상 전체 흐름을 통제할 수 있도록 의도적으로 설계한 거예요.

만약 작업이 복잡해서 여러 단계가 필요하다면? 메인 에이전트가 서브에이전트 A를 부르고, 그 결과를 바탕으로 서브에이전트 B를 부르는 식으로 메인이 중간에서 조율하면 돼요. 서브끼리 직접 소통하는 게 아니라 항상 메인을 거치는 거죠. 이게 훨씬 안전하고 예측 가능해요.

---

핵심 정리

1. 서브에이전트 = 특정 유형의 작업을 처리하는 전문화된 AI 어시스턴트
2. 독립 컨텍스트 = 역할 간 정보 격리, 집중도 향상, 보안 강화
3. 6대 구성요소: 시스템 프롬프트, tools, disallowedTools, permissionMode, model, maxTurns
4. "서브" = 위계가 아닌 책임 범위의 제한. 전문성에 집중하라는 뜻
5. 네스팅 금지 = 복잡성 폭발과 통제 상실을 막는 운영 안전장치

---

FAQ

Q. 서브에이전트 없이도 Claude Code로 복잡한 작업을 할 수 있지 않아요?

A. 가능하긴 해요. 하지만 하나의 컨텍스트에서 여러 역할을 동시에 수행하면 맥락이 길어지고, 역할이 섞이면서 결과물 품질이 떨어져요. 서브에이전트로 역할을 분리하면 각 작업의 정확도와 일관성이 눈에 띄게 좋아져요.

Q. 서브에이전트를 몇 개까지 만들 수 있어요?

A. 기술적으로 수에 제한은 없어요. 하지만 실무적으로는 3~5개 정도가 적당해요. 너무 많으면 메인 에이전트가 조율하는 것 자체가 복잡해지거든요.

Q. 서브에이전트마다 다른 AI 모델을 쓸 수 있다고 했는데, 왜 그래야 하죠?

A. 비용과 속도 최적화 때문이에요. 단순한 포맷 검사는 가벼운 모델로 빠르게 처리하고, 복잡한 보안 분석은 강력한 모델로 정확하게 처리하면 전체적으로 효율적이죠.

Q. 독립 컨텍스트면 서브에이전트끼리 정보를 공유할 수 없는 건가요?

A. 직접 공유는 안 돼요. 하지만 메인 에이전트가 중간 다리 역할을 해요. 서브에이전트 A의 결과를 메인이 받아서, 필요한 부분만 서브에이전트 B에게 전달하는 거죠. 이렇게 하면 필요한 정보만 선택적으로 공유할 수 있어서 오히려 더 좋아요.

Q. maxTurns를 너무 적게 설정하면 작업이 미완성으로 끝나지 않아요?

A. 그럴 수 있어요. 처음에는 넉넉하게 설정하고 실제 작업에서 몇 턴이 소요되는지 관찰한 다음, 적절한 값으로 조정하는 게 좋아요. 보통 간단한 리뷰는 510턴, 복잡한 분석은 1520턴 정도를 기준으로 잡아요.

Q. 네스팅이 금지되면 정말 복잡한 작업은 어떻게 처리해요?

A. 메인 에이전트가 오케스트레이터(지휘자) 역할을 해요. 복잡한 작업을 여러 단계로 쪼개서, 각 단계마다 적절한 서브에이전트를 순차적 또는 병렬적으로 호출하면 돼요. 4편 설계 원리에서 이 패턴을 자세히 다룰 거예요.

Q. 서브에이전트의 메모리(memory) 설정은 왜 3단계로 나뉘어 있어요?

A. 최소 권한 원칙 때문이에요. user 메모리는 사용자 개인 설정, project 메모리는 프로젝트 공통 지식, local 메모리는 현재 작업 디렉토리 정보를 담아요. 서브에이전트마다 필요한 수준의 메모리만 열어줘서 불필요한 정보 노출을 막는 거예요.

---

참고 자료 (References)

데이터 출처

출처	설명	링크
Claude Code 서브에이전트 문서	서브에이전트 개념, 구성요소, 제약 사항 공식 가이드	공식 문서
Claude Code Overview	Claude Code 플랫폼 전체 구조와 기능 소개	공식 문서
Anthropic 자율 에이전트 블로그	Claude Code 자율 에이전트 운영 관련 블로그	블로그 포스트

핵심 인용

"Sub-agents are specialized AI assistants that handle specific types of tasks, each running in their own independent context window with custom system prompts."
— Claude Code 공식 문서

---

다음 편 예고

[3편] 서브에이전트 vs 도구 호출 vs 워크플로 — 헷갈리는 개념 완벽 정리

• 서브에이전트, 도구 호출, 워크플로, Agent Teams의 핵심 차이를 비교해요
• 한눈에 보는 전체 비교 표로 개념을 정리해요
• 각각 언제 쓰는 게 맞는지 상황별 선택 가이드를 세워봐요