Claude Code 서브에이전트, 언제 어떻게 쓰면 좋을까 - 직접 써보며 정리한 기록
Claude Code 서브에이전트, 언제 어떻게 쓰면 좋을까 — 직접 써보며 정리한 기록
개발 도구 사용기 · 공식 문서와 실제 사용 경험 기준
Claude Code로 작업하다 보면 대화 하나에 코드 검색, 테스트 실행, 문서 조회가 뒤섞이면서 맥락이 금방 길어집니다. 그럴 때 도움이 됐던 기능이 "서브에이전트(subagent)"였습니다. 이 글은 서브에이전트가 무엇이고 언제 쓰면 좋은지를 공식 문서 기준으로 정리하고, 직접 써보며 느낀 점을 덧붙인 기록입니다. 화면이나 명령은 도구 버전에 따라 달라질 수 있으니, 정확한 내용은 본문에 적은 공식 문서를 함께 확인하시길 권합니다.
서브에이전트란 무엇인가
서브에이전트는 메인 대화와 분리된 별도의 컨텍스트에서 동작하는 작업 단위입니다. 핵심은 "분리"입니다. 서브에이전트는 지금까지 메인 대화에서 오간 내용이나 이미 읽어 둔 파일을 그대로 보지 않고, 자신에게 주어진 작업만 새 맥락에서 처리합니다. 그리고 작업이 끝나면 결과 요약만 메인 대화로 돌려줍니다.
이 구조가 왜 유용한가 하면, 출력이 많은 작업을 시켜도 메인 대화가 지저분해지지 않기 때문입니다. 예를 들어 로그 파일을 훑거나, 수십 개 파일을 검색하거나, 테스트를 돌려 길게 쏟아지는 출력을 처리할 때 — 그 장황한 중간 과정은 서브에이전트 안에서 끝나고, 메인 대화에는 "찾은 결론"만 올라옵니다. 제 경우 큰 코드베이스를 탐색할 때 이 점이 가장 체감됐습니다.
어떻게 호출하나
호출 방식은 크게 자동과 수동으로 나뉩니다.
- 자동 위임: 각 서브에이전트에는 "어떤 상황에 쓰는지"를 적은 설명(description)이 있어, 작업과 맞으면 알아서 위임됩니다.
- 이름으로 지정: "○○ 서브에이전트로 이 부분을 살펴봐"처럼 자연어로 특정 에이전트를 콕 집어 부를 수 있습니다.
/agents명령: 실행 중인 서브에이전트를 보거나, 새로 만들고, 기존 것을 편집·삭제할 수 있는 관리 화면입니다.
직접 만들 수도 있습니다. 프로젝트의 .claude/agents/ 폴더(또는 모든 프로젝트에서 쓰려면 사용자 홈의 ~/.claude/agents/)에 마크다운 파일을 두면 됩니다. 파일 맨 위 frontmatter에 설정을 적고, 그 아래에 시스템 프롬프트를 적는 형식입니다.
name: code-reviewer
description: 코드 품질과 모범 사례를 검토
tools: Read, Glob, Grep
model: sonnet
---
당신은 코드 리뷰어입니다. 호출되면 코드를 분석해
품질·보안·모범 사례 관점에서 구체적인 피드백을 주세요.
tools를 생략하면 모든 도구를 상속하고, 적어 두면 그 도구만 허용됩니다. 예를 들어 위처럼 읽기 계열(Read·Glob·Grep)만 주면 "읽기만 하고 절대 고치지 않는 리뷰어"를 만들 수 있습니다.
대표적인 빌트인 서브에이전트
직접 만들지 않아도 기본으로 제공되는 유형이 있습니다. 용도가 분명히 갈립니다.
가볍게 "이 함수가 어디서 쓰이는지" 정도를 찾을 때는 빠른 Explore가 적합하고, 검색에서 끝나지 않고 실제로 코드를 고치는 단계까지 가야 하면 general-purpose가 맞습니다. 한 가지 알아 둘 점은, 탐색용 서브에이전트는 메인 대화의 규칙 파일(CLAUDE.md)을 자동으로 들고 가지 않는다는 것입니다. 꼭 지켜야 할 규칙이 있다면 위임할 때 다시 적어 주는 편이 안전합니다.
실제로 쓰면 좋았던 상황
- ▸ 병렬 탐색 — 인증·데이터베이스·API처럼 서로 독립된 영역을 각각 다른 서브에이전트에 맡겨 동시에 살펴볼 때.
- ▸ 컨텍스트 절약 — 테스트 출력이나 긴 로그처럼 양이 많은 작업을 분리해, 메인 대화에는 요약만 남길 때.
- ▸ 권한 제약 — 읽기 도구만 가진 리뷰어처럼, 의도적으로 할 수 있는 범위를 좁혀 안전하게 맡길 때.
반대로, 메인 대화가 나은 경우
서브에이전트가 항상 정답은 아닙니다. 직접 써보니 다음 같은 상황에서는 그냥 메인 대화로 진행하는 편이 나았습니다.
- 주고받는 횟수가 잦은 작업. 서브에이전트는 매번 맥락이 새로 시작되므로, 짧은 왕복이 반복되면 오히려 비효율적입니다.
- 계획 → 구현 → 테스트가 촘촘히 이어지는 작업. 단계끼리 맥락을 계속 공유해야 하면 한 대화에서 이어가는 게 자연스럽습니다.
- 너무 많은 서브에이전트를 한꺼번에 돌리는 경우. 각자의 결과가 한꺼번에 메인으로 모이면 맥락이 다시 넘쳐 버릴 수 있습니다.
정리하면 "스스로 완결되는 덩어리 작업"은 서브에이전트에, "긴밀하게 이어지는 작업"은 메인 대화에 두는 기준이 무난했습니다.
자주 묻는 질문
Q. 서브에이전트와 메인 대화의 가장 큰 차이는?
컨텍스트 공유 여부입니다. 메인 대화는 그동안의 맥락을 그대로 이어가지만, 서브에이전트는 분리된 맥락에서 작업한 뒤 결과 요약만 돌려줍니다.
Q. 직접 만든 서브에이전트는 팀과 공유할 수 있나요?
프로젝트의 .claude/agents/에 둔 파일은 저장소에 함께 커밋해 공유할 수 있습니다. 개인용으로만 쓰려면 홈 폴더의 ~/.claude/agents/에 두면 모든 프로젝트에서 쓸 수 있습니다.
Q. 특정 서브에이전트를 못 쓰게 막을 수도 있나요?
설정의 권한(permissions) 항목에서 특정 에이전트 사용을 거부하도록 지정할 수 있습니다. 자세한 규칙은 공식 권한 문서를 참고하면 됩니다.
마무리
서브에이전트는 "일을 더 빨리 시키는 기능"이라기보다, 맥락을 깔끔하게 나누는 기능에 가깝습니다. 출력이 많거나 독립적인 작업은 분리해서 결과만 받아오고, 긴밀하게 이어지는 작업은 메인 대화에 두는 식으로 구분해 쓰면 대화가 한결 정돈됩니다. 처음에는 Explore로 가벼운 탐색부터 맡겨 보고, 익숙해지면 자주 하는 작업을 사용자 정의 서브에이전트로 만들어 두는 흐름을 권합니다.
이 글의 기능 설명은 Claude Code 공식 문서를 기준으로 정리했습니다. 화면 구성이나 명령은 버전에 따라 달라질 수 있으니, 최신 내용은 공식 문서에서 직접 확인하시길 권합니다.
- 서브에이전트 가이드: code.claude.com/docs/en/sub-agents
- 병렬 에이전트 비교: code.claude.com/docs/en/agents
※ 본 글은 공개된 공식 문서와 개인적인 사용 경험을 바탕으로 정리한 정보성 콘텐츠입니다. 도구의 기능·화면·명령은 버전에 따라 달라질 수 있으며, 특정 결과를 보장하지 않습니다.