긴 세션에서 가장 먼저 무너지는 것은 컨텍스트입니다. 테스트 로그 수천 줄, 검색 결과, 한 번 읽고 다시 안 볼 파일이 대화를 채우면 모델은 처음의 지시를 잊기 시작합니다. 서브 에이전트는 이런 일을 별도의 컨텍스트로 보내고 결과 요약만 받아 오는 장치입니다. 이 글은 서브 에이전트가 어떻게 돌아가는지, 언제 쓰고 언제 쓰지 말아야 하는지, Claude Code에 내장된 에이전트가 무엇인지, 그리고 위임한 결과를 어떻게 검증하는지를 다룹니다.
앞 글 「MCP로 외부 도구 연결하기」에서 붙인 도구는 서브 에이전트에도 그대로 상속됩니다. 다음 글 「커스텀 에이전트 정의 파일 작성법」에서 나만의 에이전트를 파일로 정의하는 법으로 이어집니다.
핵심 요약
- 서브 에이전트는 자기 컨텍스트 윈도우, 자기 시스템 프롬프트, 자기 도구 권한을 가진 별도 실행 단위이며, 끝나면 요약만 메인 대화로 돌아옵니다.
- 이점은 세 가지입니다. 메인 컨텍스트 보존, 독립적인 조사의 병렬 실행, 역할에 맞춘 프롬프트와 모델(전문성과 비용 제어).
- 잦은 왕복이 필요한 작업, 단계 간에 많은 맥락을 공유하는 작업, 지연이 중요한 작은 수정에는 쓰지 않는 편이 낫습니다.
- 내장 에이전트는 Explore, Plan, general-purpose와 보조 에이전트(claude-code-guide, statusline-setup)가 있고, 세션 목록에는 범용
claude항목도 나타납니다. - 위임 결과는 보고서가 아니라 증거로 받습니다. "실패한 테스트 이름과 에러 메시지만" 같은 출력 형식을 지시에 넣어야 합니다.
서브 에이전트는 어떻게 동작하나
메인 대화의 Claude가 어떤 작업을 서브 에이전트에 맡기기로 하면, 작업을 요약한 위임 메시지를 작성해 새 에이전트를 띄웁니다. 그 에이전트는 새 컨텍스트에서 시작합니다. 지금까지의 대화 기록, 이미 읽은 파일, 호출했던 스킬을 보지 못하고, 자기 시스템 프롬프트와 위임 메시지만 가지고 일합니다. 필요한 파일은 스스로 다시 읽습니다.
작업이 끝나면 결과 텍스트가 메인 대화로 돌아오고, 메인 Claude가 그것을 바탕으로 다음 행동을 정합니다. 사용자는 서브 에이전트가 읽은 수십 개 파일의 내용을 보지 않고 결론만 받습니다. 이것이 컨텍스트가 절약되는 원리입니다.
몇 가지 실무에서 부딪히는 세부 사항이 있습니다.
- 서브 에이전트는 메인 대화의 도구와 MCP 도구를 기본적으로 상속하되,
AskUserQuestion처럼 사용자 화면에 의존하는 도구는 쓸 수 없습니다. - 권한 프롬프트는 서브 에이전트가 직접 띄우지 않고 메인 세션에 나타납니다. 백그라운드로 도는 에이전트라도 어느 에이전트가 요청했는지 이름을 붙여 묻습니다.
- 현재 버전(v2.1.217 이후)에서 서브 에이전트는 기본적으로 백그라운드로 실행되며, 비대화형 실행(
claude -p)에서는 포그라운드로 돕니다. 실행 중인 작업은Ctrl+B로 백그라운드로 보낼 수 있고/tasks에서 목록을 봅니다. - 서브 에이전트도 자기 서브 에이전트를 만들 수 있으며 깊이는 기본으로 메인 아래 3단계까지이고 설정으로 바꿀 수 있습니다.
왜 필요한가: 맥락 격리, 병렬, 전문성
맥락 격리. 테스트 스위트 실행, 문서 가져오기, 로그 분석은 출력이 큽니다. 이런 작업을 메인에서 하면 결과가 대화에 그대로 남고, 이후 모든 턴이 그 무게를 짊어집니다. 서브 에이전트에 보내면 자세한 출력은 그쪽 컨텍스트에 남고 요약만 돌아옵니다. 공식 문서는 이것을 서브 에이전트의 가장 효과적인 용도로 꼽습니다.
병렬. 인증 모듈, DB 계층, API 계층을 각각 조사해야 할 때 세 에이전트를 동시에 띄우면 서로의 결과를 기다리지 않습니다. 조사 경로가 서로 의존하지 않을 때 가장 잘 맞습니다. 이 문서 묶음도 그룹별 집필 에이전트가 병렬로 돌아 만들어졌습니다.
전문성과 비용. 에이전트마다 시스템 프롬프트, 도구 제한, 모델을 다르게 둘 수 있습니다. 읽기 전용 리뷰어에게는 Write와 Edit을 빼고, 단순 조회에는 Haiku를 씁니다. 우리 6주차 교재의 모델 나눠 쓰기(계획과 정리는 가볍게, 구현과 복잡한 해결은 강하게)를 에이전트 단위로 고정하는 셈입니다.
언제 쓰고 언제 쓰지 말아야 하나
| 서브 에이전트가 맞는 경우 | 메인 대화가 맞는 경우 |
|---|---|
| 출력이 크지만 결론만 필요할 때(테스트, 로그, 대량 검색) | 짧은 왕복을 여러 번 반복하며 다듬어야 할 때 |
| 도구 제한이나 권한을 강제하고 싶을 때(읽기 전용 리뷰) | 계획, 구현, 테스트가 같은 맥락을 공유해야 할 때 |
| 작업이 자기 완결적이라 요약으로 넘겨받을 수 있을 때 | 빠르고 표적이 좁은 수정 |
| 독립적인 조사를 여럿 동시에 돌릴 때 | 지연이 중요할 때(에이전트는 새로 시작해 맥락을 다시 모음) |
두 가지 함정을 덧붙입니다. 첫째, 서브 에이전트가 각각 장문의 결과를 돌려주면 그 합이 메인 컨텍스트를 다시 채웁니다. 공식 문서도 경고하는 지점이라, 위임할 때 출력 형식과 길이를 정해 줘야 합니다. 둘째, 파일 하나를 고치는 일에 에이전트를 띄우면 메인이 직접 하는 것보다 느립니다. 우리 규칙은 "간단한 작업은 에이전트 없이 직접, 속도 최우선"입니다.
내장 서브 에이전트 6종
general-purpose
탐색과 수정을 모두 해야 하는 복잡한 다단계 작업용입니다. 모델은 메인 대화에서 상속하고 도구는 전부 씁니다. 결과 해석에 추론이 필요하거나 여러 종속 단계가 있을 때 Claude가 여기에 위임합니다.
claude
세션의 에이전트 목록에 나타나는 범용 항목으로, 특정 전문 에이전트에 맞지 않는 작업을 받는 기본값입니다. 공식 문서의 내장 목록에는 별도 설명이 없으므로, 명시적으로 지정할 일은 드물고 이름을 안 적었을 때 선택되는 정도로 이해하면 됩니다.
Explore
코드베이스 검색과 분석에 최적화된 읽기 전용 에이전트입니다. Write와 Edit이 거부되고, 빠르고 저렴하게 유지하기 위해 CLAUDE.md와 git 상태를 건너뜁니다. 모델은 메인에서 상속하되 Claude API에서는 Opus로 상한이 잡혀 있어, 세션 모델보다 비싼 모델로 돌지 않습니다. 호출할 때 quick, medium, very thorough 세 단계로 철저함을 지정합니다. 탐색을 더 싼 모델에 고정하고 싶으면 같은 이름 Explore로 커스텀 정의를 두고 model: haiku를 적으면 내장을 덮어씁니다.
Plan
플랜 모드에서 계획을 내놓기 전에 맥락을 모으는 조사 에이전트입니다. 읽기 전용이고 모델은 상속합니다. 탐색 출력이 별도 컨텍스트에 머물러 메인 대화가 읽기 전용 상태로 유지됩니다.
claude-code-guide
Claude Code 기능에 대한 질문("훅으로 이게 되나요?")을 받으면 자동으로 쓰이는 도우미로, Haiku로 돕니다.
statusline-setup
/statusline을 실행해 상태 표시줄을 구성할 때 쓰이는 도우미로, Sonnet으로 돕니다.
내장 에이전트는 기본으로 등록되지만 막을 수 있습니다. permissions.deny에 Agent(Explore)처럼 적으면 특정 유형이 차단되고, Agent 자체를 거부하면 어떤 위임도 일어나지 않습니다. CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1은 Explore와 Plan만 끕니다.
대표 유스케이스
대규모 코드베이스 조사
"결제 확인 API가 주문 금액을 어디서 대조하는지 찾아 줘"처럼 파일을 수십 개 열어야 답이 나오는 질문은 Explore에 맞습니다. 메인은 파일 경로와 결론만 받습니다. 우리 BizPlan CRM처럼 라우트가 많은 프로젝트에서 "가격의 단일 소스가 어디인가" 같은 질문을 던질 때 이 경로가 메인 컨텍스트를 지킵니다.
여러 파일의 병렬 편집
서로 독립적인 파일 묶음을 나누어 맡깁니다. "auth, db, api 모듈을 각각 별도 서브 에이전트로 조사해 줘"가 기본형이고, 편집까지 맡기려면 general-purpose에 파일 범위를 명시합니다. 같은 파일을 두 에이전트가 건드리지 않도록 범위를 겹치지 않게 자르는 것이 핵심입니다.
문서 자동 생성
API 문서, README, 변경 요약처럼 코드를 많이 읽고 글은 조금 쓰는 작업입니다. 읽은 양이 크고 결과물이 파일 하나로 닫히므로 위임에 잘 맞습니다. 우리 일일 작업 보고서 자동화도 세션 기록을 읽는 요약기를 도구 없이 별도로 돌리는 구조인데, 원리는 같습니다.
지시를 쓸 때
위임 메시지는 메인 Claude가 작성하지만, 사용자가 프롬프트에 담은 조건이 그대로 전달됩니다. 다음 네 가지를 넣습니다.
- 범위: 어느 디렉터리, 어느 파일, 어느 브랜치까지인지.
- 출력 형식: "실패한 테스트 이름과 에러 메시지만", "파일 경로와 줄 번호 목록으로". 형식을 정하지 않으면 장문의 보고서가 돌아와 컨텍스트를 다시 채웁니다.
- 금지 사항: "수정하지 말고 보고만", "운영 DB에 접근하지 말 것".
- 완료 기준: 무엇이 확인되면 끝인지. 우리 표현으로는 "정지 규칙은 증거"입니다. 실행 화면이나 로그가 있어야 완료입니다.
auth 모듈을 별도 서브 에이전트로 조사해 줘. 수정은 하지 말고,
세션 토큰을 검증하는 함수의 파일 경로와 줄 번호, 호출하는 곳 목록만
표로 돌려줘. 테스트를 돌렸다면 실패한 테스트 이름과 에러 메시지만 포함해.
결과를 다루는 법
서브 에이전트의 보고는 요약입니다. 요약은 빠뜨리거나 잘못 추론할 수 있으니 세 가지를 습관으로 둡니다.
- 핵심 주장은 직접 확인: "이 함수는 호출되는 곳이 없습니다"라는 보고를 받았으면 그 이름으로 한 번 검색해 봅니다. 확인 비용은 작고, 틀린 보고 위에 쌓는 수정은 비쌉니다.
- 증거가 있는 형식으로 요구: 파일 경로와 줄 번호, 실행한 명령, 그 출력을 함께 돌려받으면 검증이 쉽습니다.
- API 오류는 결과가 아님: 사용량 제한이나 서버 오류로 중단된 에이전트는 부분 결과와 함께 "완료하지 못했다"는 표시가 붙어 돌아옵니다(v2.1.199 이후). 이걸 결론으로 받지 말고 재시도하거나 재개합니다.
우리 운영 규칙은 한 발 더 나갑니다. 작성한 쪽이 스스로 승인하지 않고, 검증 패스는 별도 리뷰어 에이전트가 맡습니다. 결제나 보안처럼 중요한 코드는 다른 모델의 읽기 전용 리뷰까지 거칩니다.
쓸 수 있는 에이전트 확인과 커스텀 에이전트 만들기
/agents를 실행하면 현재 버전에서는 대화형 마법사 대신 "Claude에게 요청하거나 .claude/agents/를 직접 편집하라"는 안내가 나옵니다(v2.1.198부터 마법사가 제거됨). 사용 가능한 에이전트는 프롬프트에서 @를 입력했을 때 자동완성에 (agent) 표시와 함께 나타나며, @agent-<이름>으로 직접 적을 수도 있습니다.
커스텀 에이전트는 .claude/agents/(프로젝트) 또는 ~/.claude/agents/(사용자)에 YAML 프론트매터가 붙은 Markdown 파일로 둡니다. Claude에게 "읽기 전용 코드 리뷰어를 .claude/agents/에 만들어 줘"라고 시켜도 되고 직접 써도 됩니다. 파일 형식, 프론트매터 필드, 복붙용 예제는 다음 글에서 다룹니다.
정리
- 서브 에이전트는 별도 컨텍스트에서 일하고 요약만 돌려주는 실행 단위입니다.
- 큰 출력, 독립적 병렬 조사, 도구 제한이 필요한 작업에 쓰고, 잦은 왕복과 작은 수정에는 쓰지 않습니다.
- 내장은 Explore(읽기 전용 탐색), Plan(플랜 모드 조사), general-purpose(탐색+수정)와 보조 도우미들입니다.
- 지시에는 범위, 출력 형식, 금지 사항, 완료 기준을 넣습니다.
- 보고는 증거와 함께 받고 핵심 주장은 직접 확인합니다.
자주 묻는 질문
서브 에이전트를 쓰면 무엇이 좋아지나요?
메인 대화의 컨텍스트가 보존되어 긴 세션에서도 처음 지시를 잊지 않고, 독립적인 조사를 동시에 돌려 시간을 줄이며, 에이전트마다 도구와 모델을 제한해 안전성과 비용을 통제할 수 있습니다. 세 가지 중 실무에서 가장 크게 체감되는 것은 첫 번째입니다.
어떤 작업에는 서브 에이전트를 쓰지 않는 것이 좋나요?
짧은 왕복을 반복하며 다듬는 작업, 계획과 구현과 테스트가 같은 맥락을 공유해야 하는 작업, 파일 한두 개를 고치는 빠른 수정입니다. 에이전트는 새로 시작해 맥락을 다시 모으므로 작은 일에는 오히려 느립니다. 대화에 이미 있는 내용에 대한 짧은 질문은 /btw가 더 맞습니다.
내장 서브 에이전트에는 무엇이 있나요?
공식 문서 기준으로 Explore(읽기 전용 탐색), Plan(플랜 모드 조사), general-purpose(탐색과 수정), 그리고 도우미인 claude-code-guide(Haiku)와 statusline-setup(Sonnet)입니다. 세션의 에이전트 목록에는 범용 claude 항목도 보입니다. Explore와 Plan은 CLAUDE.md와 git 상태를 읽지 않습니다.
여러 서브 에이전트를 동시에 돌려도 되나요?
됩니다. 조사 경로가 서로 독립적일 때 효과가 큽니다. 다만 각 에이전트의 결과가 모두 메인으로 돌아오므로 출력 길이를 제한하고, 편집을 맡길 때는 파일 범위가 겹치지 않게 나눕니다. 지속적인 병렬이나 컨텍스트를 넘는 작업은 agent teams 쪽이 맞습니다.
서브 에이전트의 보고를 그대로 믿어도 되나요?
아니요. 보고는 요약이고 요약은 틀릴 수 있습니다. 파일 경로, 줄 번호, 실행 명령과 출력처럼 검증 가능한 형식으로 받고, 핵심 주장은 한 번 직접 확인합니다. 우리 기준으로 "완료"는 실행 화면이나 로그가 있을 때만 성립합니다.