Claude Code 서브에이전트 완전 정리

핵심 요약

서브에이전트는 Claude Code 안에 있는 "작은 전문 AI들"로, 특정 역할에 맞게 프롬프트·도구·모델을 따로 설정해 두고 필요할 때 호출해 쓰는 구조입니다. 각 서브에이전트는 독립된 컨텍스트에서 작업해 메인 대화의 맥락을 더럽히지 않으면서, 코드 리뷰, 디버깅, 탐색, 데이터 분석 등 특화된 업무를 더 정확하고 효율적으로 처리하도록 돕습니다.

서브에이전트란 무엇인가

서브에이전트는 Claude Code가 작업을 "위임"할 수 있는, 미리 설정된 전문 AI 조수입니다. 각 서브에이전트는 하나의 명확한 목적과 역할을 가지고, 그 목적에 맞는 시스템 프롬프트, 사용할 수 있는 도구 목록, 모델 설정, 그리고 독립된 대화 컨텍스트를 갖습니다.

메인 Claude가 사용자의 요청을 보고 "이건 코드 리뷰 전문가가 더 잘하겠다"라고 판단하면, 코드 리뷰용 서브에이전트를 호출해 그 안에서 작업을 진행하고 결과만 가져옵니다. 이때 서브에이전트의 내부 대화와 탐색 내용은 메인 대화의 토큰을 거의 쓰지 않으므로, 긴 세션에서도 메인 맥락을 더 오래 유지할 수 있습니다.

서브에이전트를 쓰면 뭐가 좋은가

첫째, 컨텍스트 분리입니다. 복잡한 코드 탐색이나 디버깅을 하다 보면 로그와 검색 결과가 잔뜩 쌓이는데, 이걸 서브에이전트 컨텍스트에 가둬두면 메인 대화는 "무슨 일을 할지"에만 집중할 수 있습니다.

둘째, 전문성 강화입니다. 서브에이전트의 시스템 프롬프트를 매우 구체적으로 작성해 두면, "이 에이전트는 디버깅할 때 이런 순서로, 이런 기준으로 생각해라"처럼 작업 방식까지 고정할 수 있습니다. 결과적으로 같은 종류의 작업을 반복할 때 품질과 스타일이 일정해지고, 팀 전체가 동일한 기준으로 일하게 만들 수 있습니다.

셋째, 재사용성과 공유입니다. 프로젝트별로 만든 서브에이전트를 저장해두면, 다른 프로젝트나 팀원들도 그대로 불러와 사용할 수 있습니다. 특히 코드 리뷰, 테스트 실행, 데이터 분석처럼 반복되는 업무는 서브에이전트 하나로 워크플로우를 표준화하기 좋습니다.

넷째, 권한 제어입니다. 각 서브에이전트마다 사용할 수 있는 도구와 권한 모드를 다르게 설정할 수 있어, 위험한 도구(예: 강력한 Bash 실행, 자동 수정 등)는 제한된 에이전트에게만 허용하는 식으로 안전 장치를 만들 수 있습니다.

서브에이전트 생성과 관리 흐름

실제 사용 흐름은 /agents 명령으로 시작합니다.

터미널이나 Claude Code 입력창에서 /agents를 실행하면, 서브에이전트를 만들고 수정하고 삭제할 수 있는 인터페이스가 열립니다. 여기서 "새 에이전트 만들기"를 선택한 뒤, 사용자 계정 전체에서 쓸 것인지(사용자 수준) 특정 프로젝트에서만 쓸 것인지(프로젝트 수준)를 정합니다.

그 다음에는 서브에이전트의 역할, 사용 상황(언제 Claude가 이 에이전트를 쓰면 좋은지), 도구 접근 권한, 모델 등을 설정합니다. 권장 방식은 "먼저 Claude에게 초안을 생성하게 한 뒤, 생성된 시스템 프롬프트를 직접 손보는 것"으로, 이렇게 하면 생각보다 빠르게 쓸만한 에이전트를 만들 수 있습니다.

저장을 하면 해당 서브에이전트는 곧바로 사용 가능해집니다. Claude가 상황을 보고 자동으로 위임하기도 하고, "코드 리뷰어 에이전트로 내 최근 변경사항을 봐줘"처럼 이름을 직접 언급해 호출할 수도 있습니다.

서브에이전트가 저장되는 위치와 우선순위

서브에이전트는 결국 "마크다운 파일 + YAML 설정"으로 저장됩니다.

프로젝트 전용 서브에이전트는 해당 리포지토리나 폴더 아래의 .claude/agents/ 디렉터리에 저장됩니다. 사용자 전역 서브에이전트는 홈 디렉터리의 ~/.claude/agents/ 아래에 저장되며, 모든 프로젝트에서 공통으로 사용할 수 있습니다.

이 두 위치에 같은 이름의 에이전트가 동시에 있을 경우, 프로젝트 디렉터리 .claude/agents에 있는 정의가 우선합니다. 즉, 팀 공통 규칙이 필요한 건 프로젝트 수준에 정의하고, 개인 취향이나 개인용 도우미는 사용자 수준에 두면 충돌을 관리하기 쉽습니다.

추가로, CLI에서 claude --agents '{...}'처럼 JSON으로 임시 정의를 넘길 수 있는데, 이 경우 우선순위는 "프로젝트 > CLI > 사용자" 순서가 됩니다. CLI 방식은 빠르게 실험하거나 스크립트·자동화에서 일시적으로만 쓰고 싶은 에이전트를 정의할 때 유용합니다.

서브에이전트 설정 파일 구조와 주요 필드

각 서브에이전트는 다음과 같은 형태의 마크다운 파일로 정의됩니다.

---
name: code-reviewer
description: 코드 리뷰 용도에 언제 어떻게 사용할지 설명
tools: Read, Grep, Glob, Bash
model: sonnet
permissionMode: default
skills: skill1, skill2
---

여기에 시스템 프롬프트 본문을 작성합니다.
역할, 작업 방식, 체크리스트, 제약사항 등을 자세히 정의합니다.

앞부분의 --- 사이 YAML이 "메타데이터"이고, 아래의 본문이 시스템 프롬프트입니다. name은 소문자와 하이픈을 쓰는 고유 이름이며, 나중에 "이 이름의 에이전트를 써달라"고 호출할 때 사용됩니다.

description은 "언제, 어떤 상황에서 이 에이전트를 써야 하는지"를 자연어로 설명하는 부분입니다. Claude는 이 설명을 참고해 자동 위임 여부를 결정하므로, "프로액티브하게 사용", "필수 사용" 같은 문구를 넣으면 더 자주, 적극적으로 호출합니다.

tools는 이 에이전트가 사용할 수 있는 도구만 골라 적는 필드입니다. 비워두면 메인 대화가 가진 모든 도구(MCP 도구 포함)를 그대로 상속하지만, 보안이나 혼선을 줄이기 위해 꼭 필요한 도구만 적어두는 것이 좋습니다.

model에는 sonnet, opus, haiku 같은 모델 별칭을 지정하거나, inherit로 메인 대화의 모델을 그대로 쓰게 만들 수 있습니다. 비워두면 기본 서브에이전트 모델(일반적으로 sonnet)을 사용합니다.

permissionMode는 권한 요청을 어떻게 처리할지에 대한 정책입니다. 예를 들어 "계획만 세우는 모드", "사용자에게 거의 묻지 않고 실행하는 모드", "편집 제안만 하는 모드" 등 다양한 전략을 선택할 수 있습니다.

skills는 특정 Skill을 자동으로 불러와서 시작하게 하는 목록이고, 서브에이전트는 기본적으로 메인 대화의 Skill을 상속하지 않기 때문에, 필요한 경우 여기서 명시적으로 적어줘야 합니다.

모델 선택과 도구 설정 전략

서브에이전트마다 다른 모델을 사용하는 것은 성능·비용·속도 사이 균형을 맞추는 중요한 수단입니다.

예를 들어, 단순한 코드 검색·구조 파악처럼 빠른 응답이 중요한 작업에는 haiku를, 복잡한 리팩터링 계획이나 깊은 분석이 필요한 작업에는 sonnet이나 opus를 배치할 수 있습니다. 한편, 메인 대화의 모델을 자주 바꾼다면, model: inherit로 설정해 전체 세션에서 일관된 능력·스타일을 유지하도록 만드는 것도 좋은 전략입니다.

도구 설정에서는 "최소 권한 원칙"을 적용하는 것이 안전합니다. 예를 들어 코드 리뷰 에이전트에는 파일 읽기·검색만 허용하고, 수정 권한은 디버거·리팩터링 전용 에이전트에만 주는 식으로 책임과 위험을 분리할 수 있습니다. 또한 MCP 서버에서 제공하는 도구가 많을수록 헷갈릴 수 있으니, /agents 인터페이스를 통해 어떤 도구를 켜고 끌지 명시적으로 선택하는 것이 관리에 유리합니다.

서브에이전트 호출 방식: 자동 위임 vs 직접 호출

서브에이전트는 두 가지 방식으로 사용됩니다.

첫째, 자동 위임입니다. Claude는 사용자의 요청 내용, 서브에이전트의 description, 현재 사용할 수 있는 도구와 컨텍스트를 보고 "지금은 어느 에이전트를 써야 할지"를 스스로 판단합니다. 이때 설명에 "프로액티브하게 사용", "항상 이 작업 후 바로 사용" 같은 문구가 있으면 더 과감하게 그 에이전트를 선택합니다.

둘째, 명시적 호출입니다. 사용자가 직접 "test-runner 서브에이전트를 사용해 실패한 테스트를 고쳐줘"처럼 에이전트 이름을 언급하면, Claude는 그 지시를 존중해 해당 에이전트로 작업을 보내려고 시도합니다. 이 방식은 특히 여러 비슷한 에이전트가 있을 때 원하는 역할을 확실히 지정할 수 있어 편리합니다.

실전에서는 "일반적인 작업은 자동 위임에 맡기되, 중요한 코드 수정이나 배포 관련 작업처럼 민감한 일은 직접 특정 에이전트를 지목하는" 식의 혼합 사용이 효율적입니다.

기본으로 제공되는 내장 서브에이전트

Claude Code에는 몇 가지 기본 에이전트가 이미 탑재되어 있습니다.

가장 범용적인 것은 "general-purpose" 에이전트입니다. 이 에이전트는 넓은 도구 권한과 강력한 모델(Sonnet)을 사용해, 탐색과 코드 수정이 모두 필요한 복잡한 작업을 처리합니다. 예를 들어 "인증 처리하는 곳을 다 찾아서 새 토큰 형식으로 바꿔줘"처럼 검색·이해·수정이 모두 필요한 요청에 잘 어울립니다.

"Plan" 에이전트는 계획 모드일 때만 쓰이는 특수 에이전트입니다. 이때 Claude는 실제 코드를 바로 수정하지 않고, 먼저 Read, Glob, Grep, Bash 등으로 코드를 조사해 맥락을 모은 뒤, 그 결과를 바탕으로 사람이 검토하기 좋은 계획을 제안합니다. 서브에이전트가 서브에이전트를 다시 부르는 "무한 중첩"을 막기 위한 구조도 함께 포함되어 있습니다.

"Explore" 에이전트는 haiku 모델을 쓰는, 읽기 전용 탐색 전용 에이전트입니다. 파일 패턴 검색(Glob), 내용 검색(Grep), 파일 읽기(Read), 읽기 전용 Bash 명령(ls, git log, git diff 등)만 사용할 수 있고, 어떤 파일도 수정할 수 없습니다. 그래서 "에러가 어디서 처리되는지 찾아줘", "이 코드베이스 구조를 정리해줘" 같은 탐색 중심 작업을 빠르게 처리해줍니다.

예시 에이전트: 코드 리뷰어, 디버거, 데이터 사이언티스트

문서에는 실전에 바로 써도 좋은 예제 정의들이 있습니다.

코드 리뷰어 에이전트는 git diff로 변경사항부터 확인하고, 수정된 파일 중점으로 코드 품질·보안·테스트·성능 관점까지 체크하는 체크리스트형 에이전트입니다. 출력도 "치명적 문제 / 경고 / 제안"처럼 우선순위로 나눠 주도록 프롬프트에 명시되어 있어, 리뷰 결과를 바로 작업 티켓으로 옮기기 쉽습니다.

디버거 에이전트는 에러 메시지와 스택 트레이스를 우선 수집하고, 재현 방법 파악 → 실패 지점 찾기 → 최소 수정안 적용 → 검증이라는 디버깅 루틴을 따르도록 설계되어 있습니다. 또한 "근본 원인, 증거, 구체 수정, 테스트 방법, 재발 방지 방법"까지 정리해서 설명하도록 돼 있어, 단순한 "임시 땜질"이 아닌 진짜 원인 해결에 초점을 맞춥니다.

데이터 사이언티스트 에이전트는 SQL·BigQuery 기반 분석 업무를 위해 만들어져 있습니다. 요구사항 이해 → 쿼리 작성 → BigQuery CLI 사용 → 결과 해석 → 인사이트 제안까지 흐름을 잡아주고, 성능·비용 효율적인 쿼리 작성과 가독성 좋은 결과 제공을 강조합니다. 이처럼 특정 역할을 명료하게 정의하면, 사람이 매번 머릿속에서 하던 사고 과정을 프롬프트 안에 고정할 수 있습니다.

고급 기능: 체인, 재개, 동적 선택, 성능

서브에이전트는 더 복잡한 워크플로우에도 활용할 수 있습니다.

먼저, 여러 에이전트를 '체인'처럼 이어서 쓸 수 있습니다. 예를 들어 "code-analyzer로 성능 문제를 찾아내고, 그 결과를 바탕으로 optimizer로 수정해줘"처럼 슬롯별 역할을 부여하면, 하나의 긴 작업을 두 단계의 전문 작업으로 분리할 수 있습니다.

또한 서브에이전트는 재개(resume)가 가능합니다. 각 실행에는 고유한 agentId가 부여되고, 그 대화는 별도 파일(agent-xxx.jsonl)로 저장됩니다. 이 ID를 다시 지정하면 같은 서브에이전트가 이전 맥락을 그대로 이어받아 후속 분석을 할 수 있어, 대규모 코드베이스 분석이나 장기 리서치에 특히 유용합니다.

동적 선택 측면에서는, Claude가 상황에 따라 어떤 서브에이전트를 쓸지 스스로 선택하는데, 이때 결정에 가장 큰 영향을 주는 것이 description입니다. 따라서 "정확히 무엇을 언제 할지"를 설명하는 것이, 단순한 소개 문구보다 훨씬 중요합니다.

성능 관점에서는, 서브에이전트가 매번 깨끗한 컨텍스트에서 시작하기 때문에 필요한 정보를 다시 수집하는 비용이 생길 수 있습니다. 그러나 그 대신 메인 대화의 컨텍스트가 덜 오염되고, 장기 세션에서 토큰 한계를 덜 빨리 소모하는 이점이 있습니다. 즉, "한 번에 끝나는 짧은 작업"보다는 "여러 번 반복하거나, 메인 대화의 맥락을 길게 가져가야 하는 세션"에서 진가를 발휘합니다.

설계와 활용을 위한 실전 팁

서브에이전트는 처음부터 완벽하게 만들기보다, Claude에게 초안을 생성시키고 조금씩 다듬어가는 것이 빠릅니다. 특히 체크리스트, 단계별 프로세스, 출력 형식 예시를 시스템 프롬프트에 충분히 넣어두면, 에이전트의 일관성과 품질이 눈에 띄게 좋아집니다.

역할은 최대한 좁게 잡는 것이 좋습니다. "모든 걸 다 하는 슈퍼 에이전트"는 결국 메인 Claude와 크게 다를 바가 없고, 행동이 예측 불가능해집니다. 반면 "테스트 실행 및 실패 케이스 수정 전문가", "클라이언트 오류 처리 코드만 보는 리뷰어"처럼 좁게 정의하면, 자동 위임도 더 정확하고 결과도 안정적입니다.

도구 권한은 작은 실수도 큰 사고로 이어질 수 있는 부분입니다. 파일 쓰기·위험한 Bash 명령·배포 스크립트 실행 같은 도구는 신중히 열고, 가능하면 사람의 확인을 거치는 워크플로우(예: Plan 모드 → 리뷰 → 실행)를 설계하는 것이 좋습니다.

마지막으로, 프로젝트 수준 서브에이전트 파일을 버전 관리에 포함시키면 팀 전체 개발 문화 자체를 "프롬프트로 문서화"하는 효과를 얻습니다. 코드 스타일 가이드, 보안 규칙, 리뷰 기준, 운영 체크리스트 등을 서브에이전트 프롬프트 안에 녹여두면, 새 팀원이 들어와도 곧바로 같은 기준으로 일할 수 있습니다.

인사이트

서브에이전트는 단순한 "프롬프트 저장 기능"을 넘어, 팀의 작업 방식을 코드처럼 정의하고 재사용하게 해주는 구조입니다. 역할을 잘게 나누고, 도구와 모델을 알맞게 배치하고, 충분히 구체적인 프롬프트로 행동 양식을 고정하면, 사람이 직접 지시하지 않아도 일정한 품질의 일을 반복해서 수행할 수 있습니다.

실무에서는 먼저 "코드 리뷰", "테스트 실행 및 수정", "에러 디버깅" 같은 자주 반복되는 작업부터 하나씩 에이전트로 분리해 보세요. 이 과정을 통해 어떤 프롬프트가 잘 동작하는지, 어떤 도구 조합이 안전하고 효율적인지 감이 잡히면, 점점 더 많은 팀 업무를 서브에이전트 기반 워크플로우로 옮길 수 있습니다.

출처 및 참고 : Subagents - Claude Code Docs