🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 결론

Claude Subagents를 잘 만드는 핵심은 독립 컨텍스트, 정확한 호출 조건, 제한된 권한, 반복 튜닝을 조합해 메인 세션을 오케스트레이터로 남기는 것이다.

📌 핵심 요점

1. Claude Code의 서브에이전트는 메인 세션과 분리된 별도 세션에서 실행되며, 리서치·파일 읽기·버그 수정·리뷰 같은 작업을 맡아 메인 컨텍스트 오염을 줄인다.
2. 좋은 커스텀 서브에이전트는 단순 프롬프트가 아니라 이름, 설명, 모델, 색상, 도구 권한, 메모리 범위, 본문 지침이 포함된 마크다운 구성 파일에 가깝다.
3. YAML front matter의 이름과 설명은 progressive disclosure 구조에서 호출 여부를 판단하는 핵심 단서가 되므로, 너무 장황하기보다 실제 trigger와 사용 조건을 정확히 담아야 한다.
4. 서브에이전트의 품질은 한 번에 완성되지 않으며, 호출되지 않은 사례와 잘못 호출된 사례를 보고 description, trigger 문구, 도구 권한, 본문 지침을 반복적으로 수정해야 개선된다.
5. 서브에이전트가 적합한 경우는 대량 리서치, 다시 읽지 않을 출력 처리, 독립 병렬 작업, fresh review, 비용 절감을 위한 저렴한 모델 위임이며, 짧은 단일 작업이나 전체 대화 맥락이 필요한 작업에는 과도할 수 있다.

🧩 배경과 문제 정의

• 이 영상은 Claude Code의 서브에이전트를 어떻게 설계하고 운용해야 하는지 설명한다.
• Claude Code의 메인 세션은 사용자의 요청을 직접 받는 오케스트레이터로 작동하고, 여러 서브에이전트를 병렬로 실행해 서로 다른 관점과 전문성을 가진 작업 단위로 분산할 수 있다.
• 서브에이전트의 핵심 가치는 메인 컨텍스트를 오염시키지 않는 데 있다. 리서치, 파일 읽기, 버그 수정, 리뷰처럼 정보량이 많거나 독립적으로 처리할 수 있는 작업을 별도 세션에 맡기고, 메인 세션은 요약된 결과만 받는다.
• 좋은 서브에이전트는 단순한 프롬프트가 아니라 이름, 설명, 모델, 도구 권한, 호출 조건이 정교하게 정의된 마크다운 구성 파일에 가깝다.
• 특히 description은 서브에이전트가 언제 호출될지 결정하는 트리거 역할을 하므로, 너무 넓거나 모호하면 호출 실패나 오작동이 생긴다.
• 영상은 서브에이전트와 스킬의 차이, 프로젝트 레벨과 글로벌 레벨 배치 기준, 권한 제한, 비용 최적화, 병렬 실행의 장점과 위험까지 다루며, 서브에이전트를 무조건 많이 쓰는 것이 아니라 적절한 작업에만 써야 한다는 원칙으로 마무리된다.

🕒 시간순 섹션별 상세정리

1. 병렬 서브에이전트와 페르소나 기반 위임

• Claude Code는 메인 세션에서 다섯 개의 서브에이전트를 동시에 실행하고, 초보자·소프트웨어 엔지니어·비즈니스 오너·퍼블리셔처럼 서로 다른 관점으로 같은 작업을 나눠 처리한다 [00:02]
• 각 서브에이전트는 별도 세션에서 실행되며, 메인 세션에서 해당 세션으로 들어가면 실제로 전달된 프롬프트와 역할 설정을 확인할 수 있다 [00:21]

2. 메인 세션의 오케스트레이션과 컨텍스트 보호

• 메인 세션은 사용자와 직접 대화하는 오케스트레이터 역할을 맡고, 파일 읽기·리서치·버그 수정 같은 작업을 서브에이전트에 배정한 뒤 결과 보고만 받아 사용자에게 전달한다 [01:41]
• 긴 대화나 리서치가 이어지면 메인 컨텍스트 창에 정보가 계속 쌓이고, 약 48,000토큰처럼 누적량이 커질수록 불필요한 정보로 컨텍스트가 오염될 위험이 생긴다 [02:13]

3. 내장 에이전트와 커스텀 에이전트의 차이

• Claude Code에는 자동으로 호출될 수 있는 내장 리서치 에이전트가 있고, 사용자가 직접 만든 커스텀 서브에이전트와 구분된다 [03:30]
• 초보자·엔터프라이즈 임원 같은 앞선 예시는 실제 커스텀 에이전트가 아니라, 범용 내장 에이전트에 서로 다른 프롬프트를 붙여 실행한 형태다 [03:46]

4. YAML front matter와 progressive disclosure

• 커스텀 에이전트가 실행되면 화면에 general purpose가 아니라 지정된 에이전트 이름이 표시되고, 색상 설정은 실행 중인 에이전트를 시각적으로 구분하는 역할을 한다 [05:20]
• YAML front matter는 progressive disclosure를 가능하게 하며, Claude Code는 전체 지침을 모두 읽기 전에 이름과 설명만 보고 현재 요청에 맞는 서브에이전트인지 판단한다 [05:40]

5. 정확한 호출을 위한 설명·도구 권한·반복 튜닝

• 이름은 참조 가능성을 만들고, 설명은 호출 트리거 역할을 하며, 설명이 정밀할수록 원하는 상황에서 호출되고 원치 않는 상황에서 오작동할 가능성이 줄어든다 [06:32]
• misfire는 호출되어야 할 서브에이전트가 호출되지 않거나, 호출되면 안 되는 상황에서 호출되는 문제를 뜻하며, 실제 사용 중 실패 사례를 보며 설명을 조정해야 줄어든다 [06:52]

6. 스킬과 서브에이전트의 역할 차이, 프로젝트·글로벌 배치

• 스킬과 서브에이전트는 둘 다 순서·프롬프트·페르소나를 정의할 수 있지만, 서브에이전트는 독립 컨텍스트와 병렬 실행, 다른 모델 사용 가능성이 핵심 차이다 [08:40]
• 스킬은 주로 메인 세션 안에서 반복 호출되는 절차에 가깝고, 서브에이전트는 깨끗한 컨텍스트를 가진 별도 세션에서 스킬을 활용하며 병렬 작업을 맡을 수 있다 [08:52]

7. 프로젝트 레벨 sub-agent 생성과 실행 권한 설정

• 간결한 설명만으로도 agent 파일이 생성되지만, 실제 use case가 강할수록 description에는 더 많은 맥락과 nuance가 필요하다 [12:01]
• project level을 선택하면 .claude 안의 agents 폴더에 agent markdown 파일이 생기며, agent 이름은 description을 바탕으로 자동 생성된다 [12:13]

8. 과도한 description 정리와 첫 호출 실험

• Claude가 만든 agent description은 trigger 문구와 사용 의도를 넓게 추정하느라 길어지기 쉽고, progressive disclosure 관점에서는 front matter를 더 짧게 다듬는 편이 낫다 [13:33]
• plan roaster는 adversarial critique, idea, plan, strategy 같은 핵심 trigger만 남기고 tools, model, color, memory, name 같은 설정은 유지한다 [13:59]

9. 호출 실패 원인 추적과 YAML front matter 개선

• plan roaster가 실행되지 않은 뒤 .claude/agents 폴더의 plan-roaster.md description과 실제 prompt를 비교하면 trigger가 빗나간 이유를 좁힐 수 있다 [15:19]
• sub-agent와 skill description은 실행되지 않은 이유와 원치 않게 실행된 이유를 기준으로 반복 수정해야 하며, trigger 문구와 의도 범위가 핵심 조정 대상이다 [15:47]

10. 명시적 sub-agent 실행과 context 격리 효과

• 더 구체적인 prompt를 쓰자 pink plan roaster sub-agent가 초기화되며, skill 대신 의도한 sub-agent가 실행된다 [17:16]
• 별도 terminal에서는 sub-agent로 전달된 실제 prompt를 확인할 수 있고, 냉장고 부재와 20달러 가격 같은 결함을 강하게 비판하라는 내용이 그대로 포함된다 [17:23]

11. 전문 agent 설계와 외부 전문성 재사용

• 하나의 거대한 personal assistant가 모든 일을 맡기보다, main agent는 skills로 범용성을 갖고 sub-agent는 security auditor, test writer, docs writer, database expert처럼 전문 역할을 맡는 구조가 더 적합하다 [18:10]
• 여러 sub-agent를 assembly line이나 parallel work처럼 silo화하면 각 agent가 한 가지 일을 깊게 처리하고, main session은 결과를 조율하는 역할에 집중한다 [18:47]

12. 권한·비용·턴 제한과 sub-agent 사용 기준

• read-only sub-agent는 tool restriction으로 구현해야 하며, “하지 말라”는 prompt instruction보다 허용 tool과 MCP service를 명시하는 permission layer가 더 강한 경계가 된다 [20:38]
• 300페이지 연구 보고서에서 요약이나 몇 가지 fact만 뽑는 작업은 Opus나 Sonnet보다 Haiku sub-agent에 맡기고, main session에는 작은 summary만 돌려받는 편이 비용과 속도 면에서 유리하다 [21:12]

13. 동적 워크플로의 병렬 실행과 세션 한도 리스크

• 메인 채팅은 오케스트레이터 역할을 맡고, 큰 프로젝트에서 동적 워크플로가 선택되면 3개든 40개든 여러 서브에이전트가 동시에 생성되어 작업을 나눠 맡는다 [24:00]
• 실제 예시에서는 41개 서브에이전트가 동시에 실행됐고, 별도 테스트에서는 210개까지 한꺼번에 생성되면서 병렬 처리 규모가 크게 커졌다 [24:20]

14. 서브에이전트 사용 원칙과 재사용 리소스

• 한 번에 끝나는 짧은 작업에는 서브에이전트가 필요하지 않고, 기능이 좋다는 이유만으로 과도하게 쓰면 더 나쁜 결과가 나올 수 있다 [25:06]
• 팀과 공유할 서브에이전트는 프로젝트나 리포지토리에 두고, 개인이 여러 프로젝트에서 쓸 서브에이전트는 홈 폴더에 둬서 전역·개인용으로 관리한다 [25:22]

🧾 결론

• 이 영상의 핵심 메시지는 “서브에이전트를 많이 만드는 것”이 아니라 “메인 세션을 깨끗하게 유지하면서 필요한 작업만 정확히 위임하는 구조를 설계하는 것”이다.
• 커스텀 서브에이전트 설계에서 가장 중요한 지점은 description이다. description은 사람이 읽는 설명이면서 동시에 Claude Code가 어떤 상황에서 해당 에이전트를 호출할지 판단하는 trigger 역할을 한다.
• 권한 설정은 프롬프트 지시보다 강한 안전장치로 제시된다. read-only 에이전트를 만들고 싶다면 “수정하지 말라”고 쓰는 것보다 실제 허용 도구와 MCP 접근 범위를 제한하는 편이 더 적합하다.
• 프로젝트 레벨과 글로벌 레벨의 배치는 협업 방식에 영향을 준다. 팀과 공유할 에이전트는 프로젝트 폴더에 두고, 개인이 여러 프로젝트에서 재사용할 에이전트는 글로벌 위치에 두는 식으로 구분할 수 있다.
• 동적 워크플로처럼 다수의 서브에이전트를 병렬 실행하는 방식은 강력하지만, 영상에서는 세션 한도와 비용을 빠르게 소모할 수 있는 리스크도 함께 강조된다.

📈 투자·시사 포인트

• Claude Code 사용성이 고도화될수록 단일 AI 채팅보다 “메인 오케스트레이터 + 전문 서브에이전트” 구조가 더 중요한 사용 패턴으로 부각될 수 있다.
• 비용 측면에서는 메인 세션에 고성능 모델을 두고, 대량 읽기·요약·검토 같은 작업은 더 저렴한 모델의 서브에이전트에 맡기는 방식이 실용적인 운영 전략으로 제시된다.
• 팀 단위 활용에서는 서브에이전트 파일을 프로젝트 저장소에 포함해 공유할 수 있다는 점이 중요하다. 이는 반복 업무의 표준화, 리뷰 품질 개선, 역할별 자동화 확장에 영향을 줄 수 있다.
• 공개 서브에이전트 저장소나 템플릿을 재사용할 때는 prompt injection이나 악성 지침을 확인해야 한다. 영상에서는 외부 마크다운 파일을 그대로 시스템에 넣기 전에 read-only 검증 에이전트로 검사하는 접근을 언급한다.
• [검증 필요] 영상에서 언급된 대규모 병렬 서브에이전트 실행 사례가 실제 업무 환경에서 어느 정도 비용 효율과 품질 향상을 만드는지는 사용자의 세션 한도, 모델 가격, 작업 유형에 따라 별도 검증이 필요하다.

⚠️ 불확실하거나 확인이 필요한 부분

• 영상에서는 Claude Code의 서브에이전트 설정이 이름, 설명, 모델, 색상, 메모리, 도구 권한, MCP 접근 권한 등으로 구성된다고 설명하지만, 실제 지원 필드와 동작 방식은 Claude Code 버전과 환경에 따라 달라질 수 있으므로 최신 공식 문서 확인이 필요하다.
• 41개 또는 210개 서브에이전트를 동시에 실행한 사례가 언급되지만, 이는 특정 실험 환경의 결과일 수 있으며 일반 사용자 계정, 세션 한도, 요금제, 모델 제한에서도 동일하게 가능한지는 별도 검증이 필요하다.
• “Opus가 메인 오케스트레이터, Haiku가 저렴한 작업자”처럼 비용 최적화 전략이 제시되지만, 실제 비용 절감 폭은 작업 길이, 모델 가격, 호출 횟수, 실패 재시도 빈도에 따라 달라질 수 있다.
• 자막 기반 정리: 타임스탬프가 있는 자막을 기준으로 정리했으며, 고유명사·수치·인용은 원문 확인 필요 시 별도 검증한다.
• 영상 속 주장: 발표자의 해석·전망·비교는 확인된 외부 사실이 아니라 영상 속 주장으로 분리해 읽는다.
• 검증 필요: 수치, 기업 실적, 정책·시장 전망은 발행 전 최신 자료로 별도 검증이 필요하다.

✅ 액션 아이템

• 자주 반복되는 작업을 “스킬로 충분한 작업”, “독립 컨텍스트가 필요한 서브에이전트 작업”, “대규모 병렬 처리가 필요한 동적 워크플로 작업”으로 분류한다.
• 새 서브에이전트를 만들 때 description을 길게 쓰기보다 실제 호출되어야 하는 상황과 호출되면 안 되는 상황을 기준으로 짧고 명확하게 작성한다.
• 리서치, 리뷰, 외부 파일 검토용 서브에이전트는 prompt instruction만 믿지 말고 read-only 도구 권한과 MCP 접근 제한을 함께 설정한다.
• 서브에이전트 생성 후 “호출되어야 하는 프롬프트”와 “호출되면 안 되는 프롬프트”를 각각 테스트해 misfire 여부를 확인한다.

❓ 열린 질문

• 우리 팀이나 프로젝트에서는 어떤 작업을 프로젝트 레벨 서브에이전트로 공유하고, 어떤 작업을 개인용 글로벌 서브에이전트로 유지하는 것이 적절한가?
• 현재 사용 중인 Claude Code 환경에서 YAML front matter의 모델, 메모리, 색상, 도구 제한, MCP 접근 제어가 정확히 어디까지 지원되는가?
• 특정 작업에서 스킬과 서브에이전트가 동시에 호출 후보가 될 때, 어떤 설계가 더 안정적인가: description 분리, 명시적 이름 호출, 또는 스킬 내부에서 서브에이전트를 호출하는 방식인가?