서브에이전트 만들기

요약대본

Claude Code에는 내장된 서브에이전트가 포함되어 있지만, 직접 만들 수도 있습니다. 커스텀 서브에이전트는 코드 검토, 테스트 작성, 문서 확인과 같은 특정 작업에 특화됩니다. 이들은 YAML 프런트매터가 포함된 마크다운 파일로 정의되며, 이 프런트매터는 Claude에게 언제 서브에이전트를 사용해야 하는지와 서브에이전트가 어떻게 동작해야 하는지를 알려줍니다.

서브에이전트 만들기

서브에이전트를 만드는 가장 쉬운 방법은 Claude에게 작성해 달라고 요청하는 것입니다. 원하는 서브에이전트와 저장 위치를 설명하면 Claude가 파일을 작성합니다. 이 레슨의 동영상과 처음 세 개의 스크린샷은 /agents 마법사를 보여주는데, 이는 Claude Code v2.1.198에서 제거되었습니다. 서브에이전트 파일과 그 필드는 변경되지 않았으므로, 여전히 범위, 도구, 모델, 색상을 선택하게 됩니다. 요청할 때 이러한 선택 사항을 포함하세요.

먼저, 서브에이전트의 범위를 선택합니다. .claude/agents/에 있는 파일은 프로젝트 수준이고, ~/.claude/agents/에 있는 파일은 사용자 수준입니다:

프로젝트 수준 -- 현재 프로젝트에서만 사용 가능
사용자 수준 -- 내 컴퓨터의 모든 프로젝트에서 공유됨

다음으로, 생성 방법을 선택할 수 있습니다. 설정을 직접 작성할 수도 있지만, 권장되는 방법은 Claude가 대신 생성하도록 하는 것입니다. 서브에이전트가 무엇을 하길 원하는지 설명하기만 하면, Claude가 입력 내용을 바탕으로 이름, 설명, 시스템 프롬프트를 생성합니다.

Claude Code의 /agents create-new-agent 흐름으로, 생성 방법으로 "Generate with Claude (recommended)"와 "Manual configuration"이 표시됨

도구 커스터마이징

생성 과정에서 서브에이전트가 접근할 수 있는 도구를 커스터마이징할 기회가 주어집니다. 도구 카테고리는 다음과 같습니다:

읽기 전용 도구
편집 도구
실행 도구
MCP 도구
기타 도구

에이전트 생성의 "Select tools" 단계로, All tools, Read-only tools, Edit tools, Execution tools, MCP tools, Other tools에 대한 체크박스가 표시됨

서브에이전트가 실제로 무엇을 필요로 하는지 생각해 보세요. 코드 리뷰어는 대개 편집 도구가 필요하지 않습니다 -- 코드를 변경하는 것이 아니라 읽고 분석해야 합니다. 다만, 대기 중인 변경 사항을 더 쉽게 파악할 수 있도록 실행 도구는 활성화해 두는 것이 좋을 수 있습니다.

모델과 색상 선택하기

도구를 설정한 후에는 서브에이전트를 구동할 Claude 모델을 선택합니다. 선택 가능한 옵션은 다음과 같습니다:

Haiku -- 빠르고 가벼운 작업에 가장 적합
Sonnet -- 속도와 깊이 사이의 적절한 균형
Opus -- 복잡한 분석에 가장 적합
Inherit -- 현재 메인 대화에서 실행 중인 모델을 그대로 사용

마지막으로 색상을 선택합니다. 이는 UI에 표시되어 어떤 서브에이전트가 활성 상태인지 빠르게 확인할 수 있게 해줍니다. 작은 부분이지만, 여러 서브에이전트를 동시에 실행할 때 도움이 됩니다.

에이전트 생성의 "Choose background color" 단계로, 색상 목록과 청록색으로 강조된 code-quality-reviewer 이름의 미리보기가 표시됨

설정 파일

생성이 완료되면, 서브에이전트 설정 파일은 선택한 범위에 해당하는 폴더에 저장됩니다(프로젝트 수준 서브에이전트의 경우 일반적으로 .claude/agents/your-agent-name.md). 일반적인 서브에이전트 설정은 다음과 같습니다:

markdown

---
name: code-quality-reviewer
description: Use this agent when you need to review recently written or modified code for quality, security, and best practice compliance.
tools: Bash, Glob, Grep, Read, WebFetch, WebSearch
model: sonnet
color: purple
---

You are an expert code reviewer specializing in quality assurance, security best practices, and
adherence to project standards. Your role is to thoroughly examine recently written or modified code
and identify issues that could impact reliability, security, maintainability, or performance.

각 필드를 하나씩 살펴보겠습니다:

name -- 서브에이전트의 고유 식별자입니다. Claude에게 직접 요청하거나 메시지에 @agent-code-quality-reviewer라고 입력하여 이를 참조할 수 있습니다.
description -- Claude가 언제 서브에이전트를 사용할지 결정하는 데 사용됩니다. 반드시 한 줄이어야 합니다(줄바꿈이 필요하면 이스케이프된 개행 문자 \n을 사용하세요). 위임이 적절한 시점을 Claude가 이해하도록 돕기 위해 여기에 예시 대화를 포함할 수 있습니다.
tools -- 서브에이전트가 접근할 수 있는 도구 목록입니다. Claude가 요청 내용을 바탕으로 이를 채워 넣지만, 언제든지 이 목록을 직접 편집할 수 있습니다.
model -- 사용할 Claude 모델을 지정합니다: 별칭(sonnet, opus, haiku, 또는 fable), claude-sonnet-5와 같은 전체 모델 ID, 또는 inherit.
color -- 서브에이전트를 식별하기 위한 UI 색상입니다.

시스템 프롬프트

마크다운 파일의 본문(YAML 프런트매터 아래의 모든 내용)이 시스템 프롬프트입니다. 여기에서 서브에이전트에게 지시 사항을 전달합니다: 무엇에 집중해야 하는지, 어떻게 분석해야 하는지, 그리고 메인 에이전트에게 결과를 어떻게 보고해야 하는지를 알려줍니다.

잘 작성된 시스템 프롬프트는 유용한 서브에이전트와 핵심을 놓치는 서브에이전트의 차이를 만듭니다. 서브에이전트가 무엇을 찾아야 하는지, 그리고 출력을 어떻게 구성해야 하는지를 구체적으로 명시하세요.

Claude가 서브에이전트를 자동으로 사용하게 만들기

명시적으로 요청하지 않아도 Claude가 작업을 서브에이전트에 위임하길 원한다면, description 필드에 "proactively"라는 단어를 포함하세요. 예를 들면:

yaml

description: Proactively suggest running this agent after major code changes...

또한 description에 예시 대화를 추가하여 서브에이전트를 사용해야 하는 구체적인 시나리오를 Claude가 이해하도록 도울 수 있습니다. 예시가 구체적일수록 Claude는 언제 위임해야 하는지 더 잘 파악하게 됩니다.

서브에이전트 테스트하기

서브에이전트를 만든 후에는 코드를 일부 변경하고 Claude에게 검토를 요청하여 테스트해 보세요. 세션이 시작될 때 agents 폴더가 존재하지 않았다면, 새 서브에이전트를 불러오기 위해 먼저 Claude Code를 재시작하세요.

FastAPI 프로젝트가 열려 있는 코드 편집기와 사이드 패널의 Claude Code에서 code-reviewer 서브에이전트를 사용해 최근 변경 사항을 검토하도록 요청하는 모습

예상한 시점에 서브에이전트가 사용되지 않는다면, 다시 돌아가서 description을 확인하세요. 더 구체적인 예시와 트리거 시나리오를 추가하면 Claude가 언제 서브에이전트에 작업을 위임해야 하는지 이해하는 데 도움이 됩니다.