서브에이전트란? AI가 일을 나눠 맡기는 원리와 토큰 비용 주의점

AI에게 “이 프로젝트에서 오류를 찾아서 수정 방법까지 알려 줘”라고 요청하면 어떤 일이 일어날까요? AI는 여러 파일을 읽고, 관련 코드를 찾고, 오류 가능성을 비교한 뒤 답을 정리해야 합니다. 이 과정에서 검색 결과와 긴 로그가 대화창에 쌓일 수 있죠. 때로는 사람이 하고 싶은 핵심 질문보다 중간 조사 내용이 더 많아집니다. 이럴 때 사용할 수 있는 개념이 서브에이전트(Subagent)입니다. 서브에이전트란 주된 AI 에이전트가 전체 작업 중 일부를 맡기는 보조 AI 작업자입니다. 예를 들어 메인 AI가 웹사이트 개발을 총괄하면서 다른 AI에게 “오류가 있는 파일만 찾아서 근거를 요약해 줘”라고 맡기는 방식입니다. 핵심은 모든 정보를 메인 대화에 길게 쌓지 않고 필요한 결과만 다시 가져올 수 있다는 점입니다. 하지만 서브에이전트를 사용한다고 전체 토큰 비용이 자동으로 줄거나, 파일이 자동으로 안전하게 분리되는 것은 아닙니다. 이번 글은 AI를 잘 모르는 사람도 이해할 수 있도록 비유와 예시로 설명하고, Claude Code를 기준으로 설정·권한·비용 문제까지 살펴보겠습니다. 이 글의 기술 설명은 2026년 10월 공개된 Anthropic과 OpenAI 공식 문서를 참고했습니다. 실제 계정에서 서브에이전트를 실행하거나 비용을 측정한 후기는 아닙니다.

서브에이전트란 · 핵심 흐름서브에이전트란의 핵심 흐름을 네 단계로 정리한 자체 제작 개념도.서브에이전트란 · 핵심 흐름1큰 요청메인 에이전트가 목표를 정합니다2하위 작업별도 맥락에 조사 등을 맡깁니다3결과 회수근거와 한계를 확인합니다4통합 검토권한·비용·중복을 점검합니다개념을 이해하기 위한 요약입니다. 실제 기능과 조건은 본문 및 공식 문서를 확인하세요.EMFLS AI · 자체 도식
자체 제작 개념도 · EMFLS AI

이 글의 순서

1. 서브에이전트는 '작업을 맡기는 보조 AI'입니다

회사에 프로젝트를 총괄하는 담당자가 있고, 그 아래서 특정 일을 처리하는 동료가 있다고 가정해 보겠습니다. 프로젝트 담당자는 “우리 웹사이트의 버튼이 왜 작동하지 않는지 알아보자”라고 결정합니다. 하지만 모든 관련 문서와 오류 로그를 직접 읽는 대신, 동료에게 “버튼 관련 코드만 조사해 원인을 세 가지로 요약해 줘”라고 업무를 맡길 수 있습니다. AI 시스템에서도 비슷한 구조를 만들 수 있습니다.

  • 메인 에이전트: 전체 목표를 이해하고 어떤 업무를 나눌지 결정합니다.
  • 서브에이전트: 넘겨받은 범위에서 자료를 조사하거나 필요한 작업을 수행합니다.
  • 결과 전달: 서브에이전트가 완료 내용을 주된 AI에게 돌려줍니다.
  • 최종 판단: 메인 에이전트 또는 사람이 결과를 검토해 다음 행동을 정합니다. 이 관계를 그림으로 생각하면 간단합니다. ~~~text 사람: 웹사이트 오류 원인을 찾아 줘 │ ▼ 메인 AI 에이전트 │ ├── 서브에이전트: 오류 로그 조사 │ └── 발견 사항 요약 │ └── 서브에이전트: 관련 코드 검토 └── 개선 제안 │ ▼ 메인 AI가 결과 정리 │ ▼ 사람이 검토·승인 ~~~ 실제 AI 서비스에 따라 여러 에이전트가 동시에 실행되기도 하고 순서대로 실행되기도 합니다. 모든 플랫폼에서 자동 병렬 실행이 보장되는 것은 아닙니다.

2. 일반 AI 에이전트와 무엇이 다를까요?

AI 에이전트는 보통 지침과 도구를 바탕으로 목표 달성을 위한 작업을 수행하는 AI 시스템을 뜻합니다. 서브에이전트는 그중에서도 다른 에이전트의 요청을 받아 특정 하위 작업을 담당하는 역할을 강조한 표현입니다.

구분 일반 AI 에이전트 서브에이전트
중심 역할 주어진 목표 수행 큰 목표의 일부를 맡음
작업 지시 사용자·시스템에서 받음 메인 에이전트나 상위 흐름에서 받음
결과 전달 사용자 또는 상위 시스템 메인 에이전트 등 호출한 쪽
대화 맥락 구성에 따라 다름 별도 맥락을 쓰도록 설계할 수 있음
대표 예시 웹사이트 만들기 총괄 관련 파일 검색·코드 리뷰

여기서 서브에이전트가 무조건 성능이 낮은 모델이라는 뜻은 아닙니다. 특정 작업을 잘 수행할 전문가 역할일 수 있고, 상위 모델과 같은 모델을 사용할 수도 있습니다. 따라서 '서브'는 똑똑한 정도의 등급이라기보다는 작업 관계와 책임 범위를 가리킵니다.

3. '별도 맥락'이란 무엇인가요?

이 개념에서 가장 중요한 표현은 별도 맥락(Separate context)입니다. AI가 대화를 처리할 때 참고할 수 있는 메시지·파일·도구 결과를 묶어서 컨텍스트(Context)라고 부릅니다. 메인 AI가 수십 개의 파일 내용을 하나하나 읽으면 대화에 많은 정보가 쌓일 수 있습니다. Claude Code의 공식 설명에 따르면 서브에이전트는 자체적인 컨텍스트 윈도우에서 작업하고 요약 결과를 주된 대화에 돌려줄 수 있습니다. 예를 들어 보겠습니다. 서브에이전트 없이

메인 AI가 오류 로그 30개를 직접 읽음 → 코드 파일 15개를 직접 읽음 → 대화 내 중간 정보가 길어짐 → 원인 정리. 서브에이전트를 사용하면 별도 조사 담당이 오류 로그와 파일을 읽음 → 핵심 원인과 파일 경로만 메인 AI에 돌려줌 → 메인 AI는 요약과 필요한 증거를 검토. 이 구조는 메인 대화가 중간 조사 자료로 가득 차는 상황을 줄이는 데 유용합니다. 그렇다고 별도 맥락이 이전 대화를 전혀 보지 못한다는 절대적인 규칙은 아닙니다. 프레임워크의 설정에 따라 전달되는 지침·도구·문서·대화 이력이 다릅니다.

4. 별도 맥락이면 토큰 요금도 줄어드나요?

반드시 그렇지는 않습니다. 여기서 '메인 대화가 차지하는 맥락'과 '전체 API 또는 서비스가 처리한 토큰 사용량'을 구별해야 합니다. 서브에이전트의 작업이 메인 대화에 들어오지 않아도, 서브에이전트가 읽고 생성한 입력·출력에는 별도의 모델 사용량이 발생할 수 있습니다. 가상의 예를 들어 보겠습니다. 아래 숫자는 실제 가격이나 실측 결과가 아닙니다.

항목 작업 예시 가상 처리 토큰
메인 에이전트 요청 판단·결과 통합 4,000
조사 서브에이전트 파일·로그 읽고 요약 12,000
검토 서브에이전트 오류 재검토 7,000
전체 합계 세 작업 전체 23,000

메인 대화에 23,000토큰이 모두 들어오지 않았더라도 실제 시스템 전체가 처리한 토큰 사용량은 따로 계산해야 합니다. 어떤 경우에는 업무를 여러 번 위임하면서 설명을 반복하고 결과를 합치는 과정 때문에 총 사용량이 늘어날 수도 있습니다. 반대로 짧고 전문적인 작업을 더 저렴한 모델에 맡기거나 긴 검색 결과를 압축해 돌려받으면, 설정과 작업에 따라 효율이 좋아질 수 있습니다. 정리하면 '서브에이전트 = 무조건 50% 비용 절감' 같은 공식은 없습니다. 실제 차이는 도구 호출 횟수·모델 종류·작업 규모·반복 실행 횟수로 측정해야 합니다.

5. 서브에이전트가 잘하는 작업은 무엇인가요?

서브에이전트는 목표가 비교적 분명하고 결과를 독립적으로 확인할 수 있는 작업에 적합합니다. 예를 들어 다음과 같습니다.

맡길 업무 기대할 결과 검토할 위험
프로젝트 파일 찾기 관련 파일 목록과 이유 잘못된 파일을 선택했는지
오류 로그 조사 의심 원인과 재현 단서 실제 실행 없이 추측했는지
코드 품질 검토 읽기 쉬운 수정 제안 기존 기능이 깨지는지
기술 문서 정리 공식 링크·근거 요약 출처를 꾸며 냈는지
테스트 결과 분석 실패 항목과 우선순위 실제 테스트 로그가 있는지

반면 몇 줄밖에 없는 간단한 질문이라면 서브에이전트를 새로 부르는 것 자체가 불필요한 단계가 될 수 있습니다. 또한 서로 밀접하게 연결된 업무를 여러 서브에이전트가 동시에 수정하면 같은 파일의 변경이 충돌할 위험도 있습니다. 작은 작업을 무조건 잘게 쪼갤 필요는 없습니다.

6. Claude Code의 실제 서브에이전트 구조

Anthropic의 공식 Claude Code 문서는 서브에이전트를 자체 시스템 프롬프트·도구 접근 범위·컨텍스트를 가진 전문 AI 작업자로 설명합니다. 특정 도구를 필요할 때만 사용하는 일반적인 기술 설명에 비해, Claude Code에서는 코드 검색용, 검토용, 디버깅용과 같이 목적을 좁힌 보조 작업자를 구성할 수 있습니다. 공식 문서에 소개되는 예시는 다음과 같습니다. Explore: 프로젝트 파일을 찾거나 관련 코드를 분석하는 읽기 중심 작업에 적합합니다. Plan: 변경 계획을 세우기 전 코드·구조를 조사할 때 활용됩니다. General-purpose: 자료 조사뿐 아니라 복잡한 구현·수정이 필요한 작업을 맡을 수 있습니다. 실제 내장 서브에이전트의 모델 선택·도구·승인 방식은 Claude Code 버전과 사용 환경에 따라 변할 수 있습니다. 예전 강의에서 “Explore는 반드시 특정 저가 모델을 사용한다”고 단정했다면 현재 공식 안내와 대조해야 합니다.

7. Claude Code에서 읽기 전용 검토 서브에이전트 설정 예시

Claude Code 공식 문서는 프로젝트 전용 서브에이전트를 .claude/agents/ 폴더의 Markdown 파일로 정의할 수 있다고 설명합니다. 개인의 여러 프로젝트에서 공통으로 사용하려면 ~/.claude/agents/ 위치를 활용할 수도 있습니다. 예를 들어 웹사이트에서 문제 가능성을 찾되 파일을 수정하지 않는 검토 담당을 만든다고 가정해 보겠습니다. 폴더 모습은 다음과 같습니다. ~~~text my-site/ └── .claude/ └── agents/ └── code-reviewer.md ~~~ code-reviewer.md 내용의 교육용 예시는 다음과 같습니다. ~~~markdown

name: code-reviewer description: 변경된 코드의 오류 가능성과 읽기 쉬운 구조를 검토할 때 사용합니다. tools: Read, Grep, Glob model: sonnet

당신은 읽기 전용 코드 검토 담당입니다.

  1. 사용자에게 요청받은 파일만 조사하세요.
  2. 문제가 의심되는 파일 경로와 관련 코드 위치를 기록하세요.
  3. 실제 확인한 사실과 추측을 구별하세요.
  4. 파일을 작성·수정·삭제하지 마세요.
  5. 검토가 끝나면 핵심 문제 세 가지와 확인 방법을 짧게 보고하세요. ~~~ 이 예시에서는 서브에이전트 이름, 언제 사용할지 알리는 설명, 허용할 읽기 도구, 모델과 작업 지침을 지정했습니다. 이 코드는 실제 설치·실행 테스트를 거친 구성 파일이 아닙니다. Claude Code의 현재 버전·사용 중인 계정 및 환경에서 해당 모델·도구 이름이 지원되는지 공식 문서를 확인하세요. 또한 '도구 목록을 적었다'는 사실만으로 모든 상황에서 안전한 샌드박스가 된다고 가정해서는 안 됩니다. 상위 세션의 권한 모드와 조직 정책도 중요합니다.

8. 서브에이전트에게 실제로 무엇을 부탁하나요?

처음에는 복잡한 지시보다 범위가 좁은 작업 한 가지가 좋습니다. 예를 들어 다음과 같이 요청할 수 있습니다.

“이번 웹사이트에서 검색 버튼이 작동하지 않는 이유를 조사해 주세요. code-reviewer 서브에이전트를 사용한다면, 검색 버튼과 관련된 파일만 읽기 전용으로 검토해 주세요. 파일을 수정하거나 명령을 실행하지 말고, 실제 확인한 경로·의심 원인·추가 확인이 필요한 부분을 요약해 주세요.” 이 프롬프트에서는 작업 범위·사용할 보조 작업자·금지 동작·보고 형식을 모두 적었습니다. 서브에이전트가 결과를 돌려주면 다음을 확인합니다. ① 어떤 파일을 실제로 열어 봤나요? ② 발견했다는 문제를 코드 위치와 연결했나요? ③ 테스트를 하지 않았다면 '예상 원인'이라고 표시했나요? ④ 원본 파일을 수정하지 않았나요? ⑤ 추가 조사에 필요한 권한을 갑자기 요구하지 않았나요? 실제 작업 도구에 접근할 수 없는 챗봇에게 같은 문장을 입력한다면 서브에이전트가 실행된 것처럼 답해도 실제 실행이라고 믿으면 안 됩니다.

9. 스킬(Skill)과 서브에이전트의 차이

AI 도구를 배우다 보면 스킬이라는 단어도 자주 등장합니다. 둘 다 AI의 작업을 도울 수 있지만 역할은 다릅니다. 스킬은 특정 상황에서 참고할 지침·지식·작업 절차를 묶은 것입니다. 서브에이전트는 별도의 작업 맥락에서 실제 하위 업무를 수행하는 보조 작업자입니다.

구분 스킬 서브에이전트
본질 재사용할 지침·참고자료 일을 맡아 수행하는 AI 작업자
예 '블로그 SEO 검수 방법' 문서 'SEO 문제가 있는 페이지 찾기' 담당
실행 맥락 기존 맥락에 불러오는 방식이 일반적 별도 맥락을 가질 수 있음
최종 산출물 검토 절차·참고 지식 작업 수행 결과·요약·변경 제안

예를 들어 '코드 보안 점검 체크리스트'가 스킬이라면, 그 체크리스트를 받아 파일 20개를 검토하는 보조 AI가 서브에이전트입니다. 기능별로 스킬을 서브에이전트에 연결할 수도 있습니다. 하지만 스킬을 설치했다고 새 서브에이전트가 자동 생성되는 것은 아닙니다.

10. 서브에이전트와 에이전트 팀은 같은가요?

반드시 같지는 않습니다. Claude Code 공식 문서는 서브에이전트와 에이전트 팀(Agent teams)을 구분합니다. 서브에이전트는 주로 메인 세션 안에서 일부 일을 맡고 결과를 상위 에이전트에게 돌려주는 작업자입니다. 에이전트 팀은 여러 세션의 동료 작업자가 공동 작업을 조정하고 직접 소통하도록 구성하는 방식입니다. 가상의 예시로 이해해 보겠습니다. 서브에이전트 방식

메인 AI → 조사 담당에게 요청 → 조사 결과를 메인 AI가 받음. 팀 방식 프런트엔드 담당·백엔드 담당·테스트 담당이 별도 작업으로 소통하며 큰 프로젝트를 함께 진행. 그러나 '팀'이라는 이름이 붙었다고 반드시 모든 변경 충돌이 자동 해결되는 것은 아닙니다. 같은 파일에 동시에 수정이 들어가면 여전히 작업 분리·브랜치·검토가 필요할 수 있습니다.

11. 서브에이전트의 대화 맥락과 파일 공간은 다릅니다

가장 쉽게 오해하는 부분입니다. 서브에이전트가 독립적인 컨텍스트를 사용한다는 것은, 반드시 독립된 컴퓨터나 파일 폴더에서 실행된다는 뜻이 아닙니다. Claude Code 공식 문서에는 서브에이전트가 메인 세션의 현재 작업 디렉터리에서 시작할 수 있고, 실제 저장소 작업을 분리하려면 isolation: worktree와 같은 별도 설정을 사용할 수 있다는 설명이 있습니다. 따라서 다음 둘을 구별해야 합니다. 대화 분리: 서브에이전트가 자기 맥락에서 긴 파일·로그를 읽는 것. 파일 분리: 서브에이전트가 다른 작업자의 파일 수정과 충돌하지 않도록 별도 작업 공간을 사용하는 것. 둘은 별개입니다. 특히 두 서브에이전트에게 동시에 같은 HTML 파일을 수정하라고 하면 같은 파일을 공유하는 구성에서는 수정 충돌이 발생할 수 있습니다. 먼저 조사·검토 같은 읽기 중심 작업부터 위임하고, 실제 파일 수정이 필요할 때에는 작업 범위·저장 위치·리뷰·승인 체계를 명확히 만드는 것이 안전합니다.

12. 어떤 권한을 줄 것인가가 중요합니다

서브에이전트에게 파일 접근이나 명령 실행 도구가 주어지면 실제로 읽거나 수정할 수 있는 범위가 넓어질 수 있습니다. 예를 들어 코드 조사만 하는 담당이라면 우선 읽기 전용 도구를 고려할 수 있습니다. 프로그램을 수정하는 담당이라면 쓰기 권한·명령 실행·네트워크 사용 여부를 더 신중하게 결정해야 합니다. 공식 문서에서도 서브에이전트의 도구 범위와 권한 모드를 설정할 수 있고, 일부 상위 세션 권한이 하위 작업자에게 적용되는 구조를 안내합니다. 실전에서 주의할 것은 다음 다섯 가지입니다. 첫째, 최소 권한: 읽기만 필요한 작업에 삭제·수정 권한을 줄 필요는 없습니다. 둘째, 비밀정보: API 키·비밀번호·고객 정보가 들어 있는 파일을 읽을 수 있는지 확인해야 합니다. 셋째, 외부 문서의 지시: 인터넷 페이지나 저장소 README에 있는 명령을 무조건 따라 실행하지 않도록 해야 합니다. 넷째, 실제 변경 검수: 여러 작업자가 코드를 작성하더라도 최종 변경사항(diff)을 사람이 확인해야 합니다. 다섯째, 실행 여부: 로그를 요약한 결과와 실제 테스트 실행·수정 완료 기록을 구분하세요. 읽기 전용 설정조차 모든 위험을 제거하지는 않습니다. 민감한 정보를 읽을 수 있다면 입력·출력으로 노출될 가능성에 대한 검토가 필요합니다.

13. OpenAI의 Agents SDK에서도 비슷한 개념이 있나요?

네. OpenAI 공식 Agents SDK 문서도 여러 에이전트를 협력시키는 방법을 설명합니다. 대표적으로 다음 두 방식을 구분합니다. Agents as tools: 메인 에이전트가 제어권을 유지하면서 전문 에이전트를 도구처럼 호출하고 결과를 통합하는 방식입니다. Handoffs: 작업의 제어권을 다른 전문 에이전트에게 넘겨주는 방식입니다. 둘은 중요한 차이가 있습니다.

방식 누가 계속 대화를 주도하나요? 적합한 일
Agents as tools 원래 메인 에이전트 조사·검토 결과를 받아 최종 답을 만들기
Handoffs 넘겨받은 전문 에이전트 특정 분야 전문가가 나머지 대화 담당

이를 Claude Code의 서브에이전트와 기능이 완전히 똑같다고 단정하면 안 됩니다. 공급자와 프레임워크마다 대화 전달·도구 호출·권한·과금 동작이 다르기 때문입니다. 그러나 큰 작업을 분해하고 적합한 전문 작업자에게 맡긴다는 원리는 비슷합니다.

14. 서브에이전트를 사용했는지 무엇으로 확인하나요?

AI에게 “여러 에이전트가 조사했습니다”라는 답을 받았다고 해서 실제로 별도 작업자가 실행됐다는 증거는 아닙니다. 서비스와 도구에 따라 다음 자료를 확인할 수 있습니다.

확인 대상 무엇을 알 수 있나요?
도구 호출 기록 실제 서브에이전트 호출이 있었는가?
에이전트 이름 어떤 담당자가 맡았는가?
입력 업무 무엇을 조사·검토하도록 맡겼는가?
파일/출처 기록 실제 어떤 자료를 읽었는가?
완료 결과 확인한 사실·추정·미완료 항목은 무엇인가?
비용/사용량 메인 외에 하위 작업에도 비용이 발생했는가?

Claude Code 공식 문서는 서브에이전트 호출이 도구 호출 형태로 표시될 수 있다고 안내합니다. 하지만 표시 방법은 사용하는 인터페이스와 버전에 따라 다릅니다. 실제 확인 가능한 호출·로그·도구 결과가 없다면 '작업을 시켰다'와 '작업이 끝났다'를 구별해야 합니다.

15. 처음 사용할 때 추천하는 작업 분배 예시

코드를 모르는 블로그 운영자가 웹사이트를 관리하는 상황을 가정해 보겠습니다. 목표는 “새 글을 발행하기 전에 오류가 없는지 확인하기”입니다. 가장 먼저 두 가지 읽기 중심 작업만 나눌 수 있습니다. 서브에이전트 A — 링크 조사 담당

“공개하려는 글의 내부 링크 목록을 추출하고 실제 URL이 열리는지 확인 가능한 범위에서 검사하세요. 각 URL·확인 시점·확인 실패 이유를 표로 작성하세요. 파일이나 공개 글은 수정하지 마세요.” 서브에이전트 B — 모바일 구조 검토 담당 “HTML과 CSS에서 모바일 화면을 가릴 수 있는 고정 너비, 긴 제목, 표 넘침 요소를 읽기만 하고 목록으로 알려 주세요. 실제 320px·390px 브라우저 테스트를 하지 않았다면 테스트 통과라고 적지 마세요.” 이후 메인 에이전트는 두 결과를 받아 실제 확인된 문제·아직 검증되지 않은 문제를 분리해 정리합니다. 중요한 점은 이 예제가 실제 웹사이트에서 검증된 자동화 결과는 아니라는 사실입니다. 실제 브라우저·파일 접근 기능이 없으면 AI는 원고에 적힌 설명만 근거로 판단할 수 있습니다.

16. 서브에이전트가 항상 좋은 선택은 아닙니다

작업을 나누는 데도 비용과 관리 부담이 있습니다. 간단한 한 문장 질문: 별도 작업자를 만들 필요가 없을 수 있습니다. 같은 정보를 여러 작업자에게 반복 전달하는 업무: 입력 토큰이 중복될 수 있습니다. 서로 같은 파일을 수정하는 업무: 변경 충돌과 결과 합치는 비용이 생길 수 있습니다. 민감 자료가 많은 업무: 접근 권한이 늘수록 보호·감사 작업이 중요해집니다. 결과를 통합하기 어려운 업무: 서로 다른 서브에이전트의 답이 충돌할 때 사람이 판단해야 할 수 있습니다. 처음에는 파일 찾기·오류 원인 조사·문서 검토처럼 분리하기 쉬운 한 가지 작업부터 시작하세요. 여러 개를 동시에 만드는 것보다 하나의 위임이 실제로 도움이 되는지 확인하는 편이 좋습니다.

자주 묻는 질문(FAQ)

Q. 서브에이전트는 다른 AI 모델을 의미하나요?

반드시 그렇지는 않습니다. 같은 모델을 사용하면서 서로 다른 작업 지침을 따를 수도 있고, 설정에 따라 다른 모델을 사용할 수도 있습니다.

Q. 서브에이전트를 사용하면 모든 대화 기록을 공유하나요?

그렇지 않을 수 있습니다. Claude Code 서브에이전트는 자체 맥락을 사용하며, 상위 에이전트가 전달한 작업과 지정된 자료를 중심으로 수행합니다. 다른 프레임워크에서는 전달되는 대화 이력이 다를 수 있습니다.

Q. 서브에이전트를 많이 만들면 무조건 저렴한가요?

아닙니다. 메인 대화에 쌓이는 정보는 줄어들 수 있지만 전체 토큰·도구 호출·병합 비용은 증가할 수 있습니다.

Q. 서브에이전트가 코드를 수정할 수도 있나요?

도구 접근과 권한 설정에 따라 가능합니다. 읽기만 해야 한다면 쓰기·삭제 기능을 제한하고 최종 변경은 사람이 검수해야 합니다.

Q. 서브에이전트와 스킬은 무엇이 다른가요?

스킬은 재사용할 지침·지식·절차이고, 서브에이전트는 일을 맡아서 수행하는 보조 AI 작업자입니다. 스킬을 서브에이전트에게 제공할 수도 있습니다.

Q. 서브에이전트가 실행되면 다른 PC에서 작업하나요?

반드시 그렇지 않습니다. 별도 컨텍스트와 별도 컴퓨터·파일 작업 공간은 다른 개념입니다. 저장소 분리가 필요하면 worktree 등 관련 구성을 확인해야 합니다.

Q. Claude Code에서 서브에이전트를 만들려면 무엇이 필요한가요?

공식 문서는 프로젝트의 .claude/agents/ 또는 개인의 ~/.claude/agents/ 안에 Markdown 정의 파일을 두는 방식을 안내합니다. 실제 지원 기능과 도구명은 현재 버전을 확인해야 합니다.

Q. '서브에이전트가 테스트했습니다'라는 말을 믿어도 될까요?

실제 테스트 도구 호출·실행 로그·테스트 대상 버전을 확인해야 합니다. 검증 가능한 기록 없이 완료라고 주장하면 추측과 실행 결과를 구별하기 어렵습니다.

결론: 나눠 맡기되, 결과와 권한은 확인하세요

서브에이전트를 이해할 때는 다음 네 문장을 기억하면 됩니다. 첫째, 서브에이전트는 큰 일을 나누어 맡는 보조 AI 작업자입니다. 둘째, 별도 맥락에서 조사해 필요한 결과만 메인 AI로 돌려줄 수 있습니다. 셋째, 별도 맥락을 쓴다고 전체 토큰 요금이나 파일 충돌 위험이 자동으로 줄어들지는 않습니다. 넷째, 실제 실행 여부·도구 권한·최종 결과는 사람이 확인해야 합니다. AI를 처음 배우는 단계라면 복잡한 에이전트 팀부터 만들기보다, “이 오류와 관련된 파일만 찾아서 요약해 줘”처럼 작은 조사 업무를 분리하는 것부터 이해해 보세요.

공식 참고 자료

함께 읽으면 좋은 글