클로드 코드 서브에이전트 사용법 2026 — 언제 나눠 시켜야 하나

서브에이전트는 메인 대화와 별개의 컨텍스트를 가진 보조 클로드입니다. 공식 문서는 다시 볼 일 없는 검색 결과·로그·파일 내용으로 메인 대화가 넘칠 것 같을 때 쓰라고 안내하며, 서브에이전트가 그 작업을 자기 컨텍스트에서 하고 요약만 돌려준다고 설명합니다. 핵심은 요약만 돌아온다는 부분이며, 장황한 과정은 저쪽에 남습니다.

공식 문서가 드는 예는 테스트 실행, 문서 수집, 로그 처리입니다. 세 가지의 공통점은 출력이 길고 그 원문을 다시 볼 일이 없다는 것입니다. 반대로 계속 되물어야 하는 일, 중간에 판단이 끼는 일은 메인에서 하는 편이 낫습니다. 서브에이전트는 대화 기록을 물려받지 않기 때문입니다.

공식 문서에는 각 서브에이전트가 새롭고 격리된 컨텍스트로 시작하며 대화 기록을 보지 못한다고 적혀 있습니다. "아까 그거 이어서 해줘" 같은 지시는 서브에이전트에게 통하지 않는다는 뜻입니다. 서브에이전트는 대화를 못 보기 때문에 지시서에 적힌 것만 압니다.

파일 하나면 됩니다. 개인용은 사용자 폴더의 에이전트 폴더에, 프로젝트용은 저장소 안의 에이전트 폴더에 md 파일을 둡니다. 파일 맨 위에 이름과 설명을 적어야 하며, 이 둘이 필수입니다. 본문에는 그 에이전트가 어떤 관점으로 일해야 하는지를 적습니다. 공식 문서는 만드는 방법으로 클로드에게 만들어 달라고 요청하는 방식을 먼저 권하며, 직접 파일을 쓰는 방법도 함께 안내합니다. 예전에 있던 대화형 마법사는 현재 버전에서 그런 방식으로 열리지 않으므로, 인터넷의 오래된 안내와 다를 수 있는 지점입니다. 파일을 추가하거나 고치면 재시작 없이 곧바로 반영됩니다.

설명이 위임을 결정합니다. 스킬과 같은 원리로, 클로드는 설명을 보고 이 일을 넘길지 판단하므로 설명에는 무엇을 하는 에이전트인지와 언제 부를지가 같이 들어가야 합니다. 자연어로 이름을 말해도 대체로 위임되지만, 확실하게 부르고 싶다면 별도 지목 방식을 쓰는 것이 안전합니다.

도구와 모델도 제한할 수 있습니다. 도구 제한 항목에 허용할 도구만 적는데, 주의할 점은 반대로 동작한다는 것입니다. 이 항목을 생략하면 모든 도구를 물려받으므로, 제한하려면 명시해야 합니다. 모델 지정 항목으로는 어떤 등급의 모델을 쓸지 정할 수 있으며, 공식 문서는 저렴한 모델로 라우팅해 비용을 줄이는 것을 이점으로 듭니다.

공식 문서는 이 기능이 무료가 아니라는 점도 분명히 합니다. 에이전트 팀 기능은 일반 세션보다 약 7배 많은 토큰을 쓴다고 명시돼 있습니다. 지시서를 쓰고 결과를 검증하는 데 드는 시간이 그 일을 직접 하는 시간보다 크면 나누지 않는 편이 낫고, 작업이 열 건 미만이면 대체로 직접 하는 편이 빠릅니다. 나눠서 아끼려다 오히려 더 쓰는 경우는 대부분 검증 비용을 계산에 넣지 않았을 때 생깁니다.

서브에이전트를 여러 개 만들 때 가장 자주 하는 실수는 기획자·디자이너·마케터처럼 직함으로 역할을 쪼개는 것입니다. 이름만 다른 에이전트를 여럿 두면 각자의 전문성은 없고 지시서만 늘어납니다. 조사·제작·검수처럼 역할 단위로 나누고 필요할 때 하나씩 붙이는 편이 실제로는 더 잘 돌아갑니다. 그리고 무엇을 만들든 보내기 전에 꼭 확인해야 할 한 가지가 있습니다. 읽어야 할 문서의 경로를 지시서에 적었는가입니다. 서브에이전트는 대화 맥락을 전혀 모르므로, 이 한 줄이 빠지면 결과가 엉뚱한 방향으로 흘러갑니다.

서브에이전트가 또 서브에이전트를 부를 수 있나요?

공식 문서에 따르면 중첩은 기본 최대 3단계이고, 동시 실행은 기본 최대 20개입니다. 환경 변수로 조정할 수 있습니다.

이름을 말하면 무조건 그 에이전트가 실행되나요?

아닙니다. 공식 문서는 자연어로 이름을 언급하면 대체로 위임된다고만 설명합니다. 확실히 하려면 별도 지목 방식을 씁니다.

서브에이전트에도 권한을 따로 줄 수 있나요?

있습니다. 다만 모든 확인을 건너뛰는 설정도 있는데, 공식 문서가 특별히 주의를 당부하는 항목이므로 꼭 필요한 경우가 아니면 켜지 않는 편이 안전합니다.

서브에이전트가 실패하면 메인 대화에 영향이 가나요?

공식 문서 기준으로 서브에이전트는 자기 컨텍스트 안에서 실패를 처리하고 요약만 메인으로 돌려주므로, 장황한 오류 로그로 메인 대화가 채워지지는 않습니다.

서브에이전트는 다시 안 볼 긴 출력을 대신 처리하게 하는 도구입니다. 나누는 것이 항상 이득은 아니며, 보내기 전에 읽을 문서를 챙기는 것이 성패를 가릅니다. 최신 제한 수치와 옵션은 공식 문서에서 확인해야 합니다.

• Anthropic — Sub-agents (https://code.claude.com/docs/en/sub-agents, 확인일 2026-09-18)
• Anthropic — Managing Claude's context (https://code.claude.com/docs/en/context-window, 확인일 2026-09-18)