Claude Code 서브에이전트: 언제 쓰고 어떻게 설정할까
업데이트 2026-11
TL;DR: Claude Code 서브에이전트는 메인 세션에서 작업을 떼어 맡는 전문가 AI입니다. 각자 자신의 컨텍스트, 지시, 도구를 갖고 요약만 돌려줍니다. 독립적인 작업을 병렬로 진행할 때 빛을 발하며, 설계안을 서브에이전트끼리 양동이 릴레이처럼 넘기는 방식은 피하세요.

Claude Code 공식 문서 서브에이전트 페이지 스크린샷.
Claude Code 서브에이전트란?
Claude Code 서브에이전트는 한 종류의 작업을 맡는 전문가로 일하는 AI입니다. 2026년 11월 기준 공식 문서에 따르면 각 서브에이전트는 자신의 컨텍스트 창에서 실행되고, 별도의 시스템 프롬프트와 특정 도구 권한을 가집니다. 메인 대화를 깨끗하게 유지하고 끝나면 요약만 돌려주기 때문에, 1개의 긴 대화가 모든 것을 떠안을 필요가 없습니다.
AI에 이런저런 기능을 넣다 보면 프롬프트가 너무 커져서 동작이 불안정해질 수 있습니다. 원인이 뭘까요?
그건 AI 하나에 설계도 개발도 테스트도 전부 하라고 너무 많이 밀어 넣었기 때문이야. 사람도 혼자서 전부 완벽하게 해내는 건 무리잖아. 중요한 건 서브에이전트라는 개념으로 역할을 나누는 거야.
그러니까 특정 작업에 특화된 전문가 팀을 만드는 느낌이네요.
처리의 정확성과 유지보수성이 극적으로 올라가.
각 AI가 자기 임무에 집중할 수 있으니, 그럴듯한 거짓말을 하는 환각도 줄어들어. 바로 업무를 잘게 나누는 거지.
서브에이전트가 도움이 되는 3가지 경우
서브에이전트가 도움이 되는 경우는 에이전트 하나에 맡기면 헷갈리기 쉬운 작업입니다. 2026년 11월의 한 해설 영상은 두 가지를 꼽았습니다. 독립적인 작업을 병렬로 진행하고 싶을 때, 그리고 MCP 도구나 스킬, 지시가 너무 많아 에이전트 하나가 고르기 어려울 때입니다. 각 단계가 앞 단계에 의존하는 작업은 맞지 않습니다.
세 번째는 단일 에이전트로는 도구 선택이나 지시의 충돌을 해결하기 어려울 때입니다.
써야 할 MCP 도구, 서브에이전트, 스킬 같은 항목이 많을 때 단일 에이전트로는 그것들을 적절히 골라 쓰거나 호출하기가 어렵습니다. 그럴 때는 책임을 나눠서 그 작업을 서브에이전트에게 맡깁니다.
어쨌든 핵심은 두 번째입니다. 독립적인 작업을 병렬로 진행하고 싶을 때 쓰는 게 좋습니다.
다만 주의할 점은, 설계 계획을 세우는 독립적인 작업이라도 서브에이전트끼리 양동이 릴레이처럼 넘기는 방식은 피해야 한다는 것입니다.
서브에이전트 만드는 법
서브에이전트를 만든다는 것은 Markdown 파일 하나를 쓰는 것입니다. 2026년 11월 기준 공식 문서에서는 위쪽에 YAML 설정(name, description, tools, model), 아래쪽에 시스템 프롬프트를 쓰고, 프로젝트용은 .claude/agents/에, 모든 프로젝트용은 ~/.claude/agents/에 저장합니다. Claude에게 대신 써 달라고 한 뒤 프로젝트에 맞게 고쳐도 됩니다.
각 에이전트에게 명확한 역할과 완료 조건을 주면 복잡한 프로젝트도 순조롭게 끝낼 수 있어.
기술력보다 중요한 건 사람의 업무 흐름을 얼마나 구체적으로 말로 표현할 수 있느냐야.
먼저 업무를 눈에 보이게 정리하고, 어느 부분을 서브에이전트에게 맡길지 정하세요. 작은 성공을 쌓는 마음으로, 우선 간단한 2개 구성부터 시작해 보세요.
서브에이전트 병렬로 돌리기
오케스트레이터-워커 패턴은 메인 에이전트가 계획을 세우고, 작업을 여러 서브에이전트에게 나눠 병렬로 진행하는 방식입니다. 2026년 11월의 해설에서는 작업 시간을 줄이면서 다루는 범위를 넓히는 방법으로 소개했습니다. 특별한 문법 없이 자연어로 부탁하기만 하면 시작할 수 있습니다.
거기서 서브에이전트를 팬아웃해서 병렬로 띄우고, 여러 관점에서 병렬로 작업하게 합니다.
그렇게 하면 작업 시간을 줄이면서 작업 범위를 넓힐 수 있습니다. 또 메인 에이전트는 실제 작업보다 설계나 상류 단계에 집중하게 할 수 있습니다.
서브에이전트에게 맡길 일을 입력창에 자기 말로 그대로 쓰면 됩니다.
"이 30개 작업을 서브에이전트 30개로 해"라고 하면 해 줍니다. 여러분이 대화하는 에이전트는 부모 에이전트입니다. 서브에이전트는 부모가 낳아서 일을 시키는 아이 같은 느낌입니다.

전용 서브에이전트에게 일을 맡기는 방법을 설명한 영상 화면.
서브에이전트와 어드바이저의 차이
어드바이저는 Claude가 작업 중 중요한 순간에 더 강한 모델에게 조언을 구하는 기능입니다. 2026년 11월 기준 공식 문서에서는 실험적 기능으로 표시돼 있고 /advisor 명령으로 설정합니다. 서브에이전트와 자주 헷갈리지만, 보는 것도 하는 일도 다르다는 점을 아래 영상이 잘 설명합니다.
어드바이저는 대화를 전부 읽어. 하지만 손은 대지 않아. 돌려주는 건 조언뿐이야.
자주 조언을 구하는 순간은 3가지입니다. 방법을 정하기 전, 같은 오류가 계속될 때, 끝났다고 말하기 전. 언제 물어볼지는 Claude가 정합니다.
어드바이저는 대화 전체를, 서브에이전트는 의뢰 내용만 봐.
또 다른 차이는 하는 일입니다. 어드바이저는 말만 하고, 서브에이전트는 일을 통째로 맡습니다. 긴 작업일수록 대화를 기억하는 어드바이저가 효과적입니다. 조사는 서브에이전트에게, 고민되는 결정은 어드바이저에게 맡기세요.
Pachat으로 다른 시각 더하기
Pachat은 pachat.ai에서 쓰는 웹 제품으로, 공식 사이트에서는 "Different personal AI agents, in one group chat."라고 소개합니다. 서브에이전트가 한 도구 안에서 일을 나눈다면, Pachat은 서로 다른 AI에게 같은 질문을 던지는 곳입니다.
- 서브에이전트 설계안이나 작업 분할 계획을 적어 둡니다.
- pachat.ai를 열고 Claude, Grok Bot, Muse, ChatGPT 점들을 하나의 그룹 채팅에 넣습니다.
- 계획을 붙여 넣고 나누는 방식이 합리적인지 묻습니다. 서로의 사실을 확인하고 끝까지 토론한 뒤, 결정은 여러분이 내립니다.
더 읽을거리: Claude Code 사용법, Claude Code 에이전트 팀, Claude Code 원격 제어.
자주 묻는 질문
서브에이전트와 에이전트 팀은 무엇이 다른가요?
서브에이전트는 하나의 세션 안에서 일하고, 끝나면 메인 대화에 요약만 돌려줍니다. 2026년 11월 기준 공식 문서는 서로 대화하며 협력하는 여러 세션이 필요하면 에이전트 팀을, 서로 독립적인 병렬 세션이 필요하면 백그라운드 에이전트를 쓰라고 안내합니다.
Claude Code 서브에이전트는 어디에 저장되나요?
Markdown 파일입니다. 현재 프로젝트용은 .claude/agents/에, 모든 프로젝트용은 ~/.claude/agents/에 둡니다. 2026년 11월 기준 Claude Code가 이 폴더들을 지켜보고 있어서, 수정하면 몇 초 안에 재시작 없이 반영됩니다. 팀에서 쓴다면 프로젝트 폴더를 버전 관리에 올려 모두가 같은 서브에이전트를 쓰게 하세요.
/agents 명령은 아직 쓸 수 있나요?
2026년 11월 기준 문서에 따르면 v2.1.197 이하에서는 /agents가 대화형 생성 화면을 열고, 새 버전에서는 Claude에게 부탁하거나 .claude/agents/를 직접 편집하라는 안내를 보여줍니다. 가장 쉬운 방법은 Claude에게 "읽기 전용 코드 리뷰 서브에이전트를 만들어 줘"라고 부탁하는 것입니다.
서브에이전트가 쓸 수 있는 도구를 제한할 수 있나요?
네. YAML의 tools 항목에 Read, Grep, Glob처럼 허용할 도구만 적으면 읽기 전용 서브에이전트가 됩니다. 공식 문서에는 빠른 읽기 전용 검색용 Explore, 계획용 Plan, 여러 단계 작업용 General-purpose라는 3가지 기본 서브에이전트도 있습니다. 2026년 기준 Explore가 읽기 전용입니다.
서브에이전트는 동시에 몇 개까지 돌릴 수 있나요?
작업을 독립적인 단위로 나누면 여러 개를 병렬로 돌릴 수 있습니다. 2026년 10월의 한 영상은 "이 30개 작업을 서브에이전트 30개로 해"라고 자연어로 부탁하는 예를 보여줬습니다. 다만 병렬 작업은 서로 독립적이어야 하고, 앞 결과를 기다리는 릴레이 방식은 피하세요.
Pachat이 서브에이전트 설계에 도움이 되나요?
네. Pachat은 pachat.ai에서 쓰는 웹 제품으로, Claude, Grok Bot, Muse, ChatGPT 점들을 하나의 그룹 채팅에 넣을 수 있습니다. 서브에이전트 역할 분담 계획을 붙여 넣고 3개 이상의 AI에게 빠진 부분이나 겹치는 부분을 찾아 달라고 하세요. 서로의 사실을 확인하고 끝까지 토론한 뒤, 결정은 여러분이 내립니다.
서로 다른 AI를 하나의 그룹 채팅에 넣어볼까요? pachat.ai에서 시작하세요.
References
- Claude Code Docs, "Create custom subagents," fetched 2026-11-18: https://code.claude.com/docs/en/sub-agents
- Claude Code Docs, "Escalate hard decisions with the advisor tool," fetched 2026-11-18: https://code.claude.com/docs/en/advisor
- @kee11nig, 2025-07-30: https://x.com/kee11nig/status/1950352602660520410
- @akalink_soma, 2026-04-27: https://x.com/akalink_soma/status/2048561651532837346
- @papaneco_life, 2026-10-01: https://x.com/papaneco_life/status/2105642379437060530
- @starriver0513, 2026-10-29: https://x.com/starriver0513/status/2115763904882032831
- @msyn_ai, 2026-11-07: https://x.com/msyn_ai/status/2119091969737855382
- @msyn_ai, 2026-11-12: https://x.com/msyn_ai/status/2120762814990340136



