Claude Code Subagents 핵심 가이드

Subagents란 무엇일까?

Subagents는 Claude Code에서 특정 업무를 담당하는 AI 전문가입니다. 각 subagent는 자신만의 역할, 도구 접근 권한, 별도의 시스템 프롬프트를 갖추고, 독립된 컨텍스트에서 동작합니다. 즉, 여러 AI 에이전트를 상황에 따라 호출해 다양한 작업을 더 효율적으로 수행할 수 있습니다.

Subagents의 주요 장점

Subagent마다 별도 컨텍스트를 쓰기 때문에, 주 대화 흐름이 어지러워지지 않습니다. 또한 각 분야에 맞게 맞춤 설정해서, 해당 업무를 더 잘 처리할 수 있고, 한번 만든 후엔 여러 프로젝트나 팀원들과 함께 재사용 가능합니다. 도구 권한도 개별적으로 설정해 보안과 유연성을 동시에 확보할 수 있습니다.

Subagent 빠르게 만드는 법

/agents 명령어로 서브에이전트 메뉴 열기
[Create New Agent] 선택해서 프로젝트 또는 사용자 단위로 생성
세부 역할, 사용 도구, 시스템 프롬프트를 상세히 정의(Claude로 초안을 생성 후 직접 수정 가능)
저장하면 자동으로 적합한 상황에 Claude가 알아서 호출하거나, 직접 이름을 언급해서 사용할 수 있습니다.

Subagent의 파일 구조와 위치

프로젝트 단위: .claude/agents/ 폴더(현재 프로젝트 한정, 우선순위 높음)
사용자 단위: ~/.claude/agents/ 폴더(모든 프로젝트에서 사용 가능, 우선순위 낮음)

서브에이전트는 Markdown 파일로 저장되며, YAML frontmatter로 이름, 설명, 도구 리스트(선택)을 정의합니다.

---
name: test-runner
description: 코드 변경 시 테스트를 실행하고 실패를 분석 후 수정
tools: Bash, Grep
---
테스트 자동화 전문가로, 실패 원인 파악과 원래 테스트 목적을 보존하면서 수정작업을 수행합니다.

도구 설정 방법

서브에이전트가 사용할 수 있는 도구를 세밀하게 지정할 수 있습니다.

‘tools’ 항목에 도구명을 쉼표로 나열해 필요한 도구만 허용
아무 것도 작성하지 않으면, 기본적으로 모든 도구(MCP 서버 포함)를 상속
/agents 명령어로 손쉽게 도구 권한을 관리할 수 있어, 직접 파일 수정 없이도 설정이 가능합니다

Subagents 운영 및 관리법

/agents 명령어 추천: 메뉴에서 모든 서브에이전트 목록 보기, 생성/수정/삭제, 권한 관리 등 한 번에 가능

직접 파일 관리도 가능:

# 프로젝트 서브에이전트 생성 예시
mkdir -p .claude/agents
echo '...내용...' > .claude/agents/test-runner.md

효과적으로 Subagent 활용하기

Claude가 업무 타입과 서브에이전트 설명을 참고해 자동으로 적절한 에이전트에게 작업을 할당합니다. 하지만, 직접 특정 agent를 언급해 사용(명령에 이름 포함)할 수도 있습니다. 예)

Use the code-reviewer subagent to check my recent changes

대표적인 Subagent 예시

코드 리뷰어: 코드의 품질, 보안, 가독성 검사. git diff로 변경점 파악, 체크리스트 기반 피드백 제공.
디버거: 에러, 실패 원인 찾기. 로그 분석, 최소 수정안 제시, 근본 문제 해결에 집중.
데이터 사이언티스트: SQL/BigQuery 분석, 효율적 쿼리 작성, 데이터 요약 및 인사이트 제공.

Subagent 만들 때 베스트 프랙티스

Claude로 초안 생성 후, 직접 커스터마이징
역할을 명확히(하나의 기능에만 집중)
프롬프트엔 구체적 안내·예시·제약 조건을 충분히 기술
최소한의 도구만 권한 부여(필요한 만큼만!)
팀원들이 협업할 수 있도록 프로젝트 에이전트는 버전 관리에 포함

고급 활용 팁

여러 subagent를 연결해서 복잡한 워크플로 구축(예: 코드 분석 후 성능 개선)
설명문에 “PROACTIVELY” 또는 “MUST BE USED” 등 적극적 사용 문구를 넣으면 Claude가 더욱 자주 자동 할당
각 subagent는 새 컨텍스트에서 시작하므로, 초기엔 필요한 정보를 파악하느라 약간의 지연이 발생할 수 있음

Claude Code의 다른 고급 명령어 및 설정 메뉴도 참고하면 더욱 강력하게 사용할 수 있습니다.

출처 : Subagents - Anthropic