서브 에이전트로 작업 나누기

서브 에이전트는 메인 세션과 분리된 자기만의 컨텍스트를 가지고, 위임받은 특정 작업을 독립적으로 처리하는 별도 에이전트입니다. 일을 맡기면 그쪽에서 파일을 잔뜩 읽더라도 메인 세션에는 결론만 돌아오기 때문에, 컨텍스트를 절약하면서 복잡한 작업을 효율적으로 처리할 수 있습니다.

핵심 요약

• 서브 에이전트는 독립된 컨텍스트 윈도우에서 동작하는 '분신'입니다
• 복잡한 작업을 분할해 병렬로 처리할 수 있습니다
• 메인 세션의 컨텍스트를 소비하지 않고 깊은 조사가 가능합니다
• 2026년 8월 기준 6종의 에이전트가 내장돼 있습니다
• .claude/agents/에 파일을 두면 커스텀 서브 에이전트도 만들 수 있습니다

서브 에이전트는 어떻게 동작하나

메인 에이전트(평소 대화하는 Claude)가 프로젝트 매니저, 서브 에이전트가 영업팀이라고 해 봅시다. 매니저가 "다음 달 클라이언트 자료를 준비해줘"라고 전하면 영업팀이 알아서 소재 수집부터 자료 작성까지 하고, 매니저는 세세한 지시 없이 결과만 기다립니다.

> 이 코드베이스의 에러 핸들링을 조사해줘

=> 메인 에이전트: "서브 에이전트에게 조사를 의뢰합니다"
=> 서브 에이전트: (독립적으로 조사 → 결과를 정리해 보고)

동작은 네 단계입니다.

1. 작업 위임 — 메인 에이전트가 "이 조사를 해줘"라고 서브 에이전트에게 작업을 넘깁니다
2. 독립 실행 — 서브 에이전트가 자기 컨텍스트에서 자율적으로 작업을 실행합니다
3. 결과 보고 — 완료되면 결과 요약을 메인 에이전트에 반환합니다
4. 통합과 응답 — 메인 에이전트가 결과를 통합해 사용자에게 보고합니다

핵심은 컨텍스트의 독립성입니다. 서브 에이전트는 자기 전용 컨텍스트 윈도우가 있어서, 조사 도중의 경과나 시행착오가 메인 세션에 영향을 주지 않습니다.

왜 필요한가 — 맥락 격리·병렬·전문성

1. 맥락 격리 — 메인 세션에서 20개 파일을 읽으면 그 내용이 전부 남습니다. 서브 에이전트에게 시키면 20개를 읽고도 "핵심은 이 3곳입니다"라는 요약만 돌아옵니다. 조사 비용은 지불하되 조사 흔적은 남기지 않는 것, 이것이 서브 에이전트의 존재 이유이자 가장 큰 장점입니다. 컨텍스트가 왜 소중한지는 컨텍스트 윈도우 관리에서 다룹니다.

2. 분할과 병렬 처리 — "모든 API 엔드포인트를 문서화해줘" 같은 광범위한 작업을 하나의 에이전트로 처리하면 시간이 걸립니다. 여러 동료에게 서로 다른 서류 뭉치를 건네 병렬로 정리시키듯, 모듈별로 서브 에이전트를 나누면 크게 단축됩니다.

3. 전문성 — 코드 리뷰 전문, 테스트 작성 전문, 디버그 전문처럼 역할별 프롬프트를 가진 서브 에이전트를 만들면 각자 잘하는 분야에 전념해 더 높은 품질의 결과를 얻습니다.

언제 쓰고 언제 쓰지 말아야 하나

좋은 후보

• 광범위한 조사 — "결제 관련 코드가 어디에 흩어져 있는지 찾아줘"
• 독립적인 병렬 작업 — 여러 모듈을 동시에 검토
• 다른 관점의 검증 — 방금 작성한 코드를 새로운 눈으로 리뷰

나쁜 후보

• 파일 하나만 확인하면 되는 일 (직접 읽는 게 빠릅니다)
• 앞선 대화 맥락이 반드시 필요한 작업 (서브 에이전트는 처음부터 시작합니다)
• 사람과 여러 번 주고받아야 하는 일

내장 서브 에이전트 6종

.claude/agents/에 파일을 두지 않아도 처음부터 쓸 수 있는 내장 에이전트가 6종(2026년 8월 기준) 있습니다. 작업 성격에 따라 자동으로 선택되므로 특별히 의식할 필요는 없지만, 존재를 알아 두면 편리한 경우가 있습니다.

general-purpose

가장 범용적인 서브 에이전트입니다. 조사뿐 아니라 파일 편집과 명령 실행도 가능해 복잡한 여러 단계 작업을 자율적으로 처리합니다. 권한이 넓은 만큼 의도치 않은 변경에는 주의가 필요합니다.

claude

다른 전문 에이전트 어느 것에도 해당하지 않는 작업을 다루는 캐치올 에이전트입니다. 백그라운드에서 실행되는 세션의 기본 에이전트도 겸하며, 이 경우 메인 세션의 권한 모드를 이어받지 않고 설정 파일에서 지정된 권한 모드에 따라 동작합니다.

Explore

코드베이스 조사에 특화된 읽기 전용 에이전트입니다. 모델은 메인 대화의 모델을 계승합니다(Claude API에서는 Opus가 상한).

"이 프로젝트에서 Redis를 쓰는 곳을 찾아줘"
→ Explore 에이전트가 자동으로 기동해 조사

편집 권한이 없으므로 광범위한 조사를 안전하게 맡길 수 있습니다. 조사 결과를 바탕으로 편집까지 하고 싶다면 다른 에이전트가 필요합니다.

Plan

계획 모드(/plan)에서 쓰이는 에이전트입니다. 구현 계획을 세울 때 코드베이스를 조사해 필요한 정보를 모아 줍니다.

claude-code-guide

Claude Code와 에이전트 SDK의 공식 문서를 참조하는 전문 에이전트입니다. 기능·사용법·설정 방법에 관한 질문에 최신 공식 정보를 바탕으로 답하므로, 쓸 수 있는 커맨드 종류나 서브 에이전트 설정 방법을 직접 찾지 않고도 바로 답을 얻을 수 있습니다.

statusline-setup

/statusline 커맨드를 실행했을 때 쓰이는 에이전트입니다. 스테이터스 라인은 Claude Code 하단에 표시되는 텍스트로, 현재 디렉터리명 등을 표시할 수 있습니다. 조금 고급 내용이니 보통은 의식하지 않아도 됩니다.

대표 유스케이스

대규모 코드베이스 조사

수십에서 수백 파일에 걸친 조사도 요약으로 돌아오므로 메인 세션의 컨텍스트를 압박하지 않습니다. 조사 후에도 여유를 갖고 작업을 이어갈 수 있습니다.

"이 프로젝트에서 인증이 어떻게 구현돼 있는지 조사해줘"

여러 파일의 병렬 편집

독립적인 작업은 동시에 여러 에이전트에 맡길 수 있습니다. 서로 의존하지 않는다면 순차 실행보다 훨씬 빠릅니다.

"모든 컨트롤러에 로깅 처리를 추가해줘"

인증 모듈, 결제 모듈, 알림 모듈을 각각 따로 조사해서
개선점을 정리해줘.

다만 같은 파일을 여러 서브 에이전트가 동시에 수정하면 충돌합니다. 병렬 편집은 파일이 겹치지 않게 나눠야 합니다.

문서 자동 생성

여러 엔드포인트를 병렬로 처리하고 통일된 포맷으로 문서를 만들 수 있습니다.

"모든 API 엔드포인트의 문서를 생성해줘"

지시를 쓸 때

서브 에이전트는 이전 대화를 모릅니다. 그래서 지시가 그 자체로 완결돼야 합니다.

결과를 다루는 법

서브 에이전트의 보고는 요약본입니다. 중요한 결정을 내리기 전에는 지목된 파일을 직접 확인하세요. 요약 과정에서 뉘앙스가 사라질 수 있습니다.

쓸 수 있는 에이전트 확인과 커스텀 에이전트 만들기

사용 가능한 서브 에이전트는 .claude/agents/(프로젝트 단위) 또는 ~/.claude/agents/(모든 프로젝트 공통)에 배치된 파일을 직접 보거나, Claude에게 "쓸 수 있는 서브 에이전트를 알려줘"라고 물어 확인할 수 있습니다.

새로 만들 때도 "~라는 서브 에이전트를 만들어줘"라고 의뢰하면 필요한 설정을 물어 가며 파일을 만들어 줍니다. 물론 .claude/agents/에 Markdown 파일을 직접 써도 됩니다. 팀이 공유하는 전문 에이전트의 예입니다.

---
name: security-reviewer
description: 변경된 코드에서 보안 취약점을 찾는다. 인증·권한·입력 검증 관련 수정 후 사용.
tools: Read, Grep, Glob, Bash
---

너는 보안 리뷰어다. 변경 diff에서 인증·권한 우회, 검증 없는 사용자 입력,
비밀값 노출을 확인하라. 발견한 것만 보고하고 없으면 "발견 없음"이라고만 답하라.

tools로 권한을 좁히는 것이 중요합니다. 리뷰어에게 편집 권한을 줄 이유는 없습니다. 프론트매터 항목별 의미와 모델 지정, 배치 위치의 우선순위 같은 정의 파일의 상세는 커스텀 에이전트 정의 파일에서 다룹니다.

정리

• 서브 에이전트는 독립 컨텍스트에서 동작하며, 조사 비용은 내되 흔적은 메인 세션에 남기지 않습니다
• 병렬 처리, 컨텍스트 절약, 전문성 발휘가 장점이고, 파일 하나 확인이나 대화 맥락이 필요한 일에는 맞지 않습니다
• general-purpose, claude, Explore, Plan, claude-code-guide, statusline-setup 6종이 내장돼 있습니다(2026년 8월 기준)
• 지시는 자족적으로 쓰고, 보고는 요약본이므로 중요한 결정 전에 직접 확인합니다
• 지식을 제공할지 작업을 위임할지 고민된다면 Skills vs 서브에이전트를, 완료 시점에 처리를 끼우고 싶다면 SubagentStop 훅을 참고하세요