Claude Academy
로그인

Creating a subagent

강의 210분
Sign in to save your progressYou can keep reading without an account, but completed lessons won't be saved.
Sign in

서브에이전트 생성하기

요약대본

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

한국어 대본
  • 00:00이전 영상에서는 서브에이전트가 무엇이고 어떻게 작동하는지 다뤘습니다.
  • 00:07Claude Code에는 기본 제공 서브에이전트가 포함되어 있지만, 직접 서브에이전트를 만들 수도 있습니다
  • 00:12특정 작업을 전문으로 하는. 사용자 정의 서브에이전트는 YAML
  • 00:17프런트매터가 포함된 Markdown 파일입니다. 이 Markdown 파일에는 Claude가
  • 00:20이 서브에이전트를 언제 사용해야 하는지 이해하도록 돕는 설정과 서브에이전트
  • 00:25자체에 제공할 지침이 들어 있습니다. 이제 서브에이전트를 만드는 가장 쉬운 방법은 slash agents 명령입니다.
  • 00:34이 패널은 서브에이전트를 관리하는 기본 인터페이스입니다. 여기에서 새 에이전트 만들기를 선택하세요.
  • 00:40그다음 현재 프로젝트용 서브에이전트를 만들지, 아니면
  • 00:44컴퓨터의 모든 프로젝트에서 공유되는 서브에이전트를 만들지 묻습니다. 다음으로 서브에이전트를
  • 00:49수동으로 만들 수도 있지만, 자동으로 생성하도록 Claude Code를 사용하는 방법을 권장합니다. 첫 번째
  • 00:54서브에이전트는 코드 리뷰어로 만들겠습니다. Claude에게 코드 품질과
  • 01:00보안 문제를 검토하는 서브에이전트를 만들어 달라고 요청합니다. Claude는 입력을 사용해 서브에이전트의 이름, 설명, 시스템 프롬프트를
  • 01:08생성합니다. 잠시 후 이것들을 확인하겠지만, 먼저 다음 기회가 주어집니다.
  • 01:13이 서브에이전트가 접근할 수 있는 도구를 맞춤 설정하는 기회입니다. 이제 이 서브에이전트는
  • 01:19코드 검토만 담당하므로, 편집 도구를 사용하지 못하게 할 수도 있습니다. 하지만 변경 사항을 더 쉽게 확인하도록 실행
  • 01:25권한은 허용하겠습니다. 다음으로 서브에이전트를 구동할
  • 01:32모델을 선택하라는 메시지가 표시됩니다. 마지막으로 색상을 선택합니다. 이 색상은 UI에서 서브에이전트를
  • 01:38더 쉽게 식별하는 데 사용되며, 개인적인 멋도 조금 더해 줍니다. 이제
  • 01:44요약 창에서 서브에이전트 설정 파일이 현재 프로젝트의 다음 경로에 저장된다는 것을 확인할 수 있습니다.
  • 01:49이제 무슨 일이 일어나는지 더 잘 이해하기 위해 이 파일을 열어 보겠습니다.
  • 01:56name 필드는 고유 식별자입니다. 이 필드는 서브에이전트를 참조하는
  • 02:00방법으로, Claude에게 직접 요청하거나 메시지에 @agent code quality reviewer를 사용해 참조할 수 있습니다.
  • 02:06description은 Claude가 서브에이전트를 사용할 시점을 제어합니다. description은 한
  • 02:11줄에 있어야 합니다. 여기에 이스케이프된 줄바꿈 문자가 있는 것이 보입니다. Claude가 이
  • 02:16서브에이전트를 자동으로 더 자주 사용하게 하려면 description에 proactively라는 단어를 추가하세요.
  • 02:22Claude가 언제 서브에이전트를 사용해야 하는지 이해하도록 예시 대화를 추가할 수도 있습니다.
  • 02:29tools 필드에는 서브에이전트가 접근할 수 있는 도구가 나열됩니다. 이 목록은 에이전트 생성 중에
  • 02:35접근 권한을 부여한 도구와 일치하지만, 원한다면 이 파일에서 도구 목록을 추가로 편집할 수 있습니다.
  • 02:41model 필드는 사용할 Claude 모델을 지정합니다. Sonnet, Opus, Haiku 또는 Inherit 중 하나입니다.
  • 02:48빠른 작업에는 Haiku, 복잡한 분석에는 Opus를 사용하고, 그 중간이 필요하면 Sonnet을 사용하세요.
  • 02:54Inherit를 사용하면 주 대화와 동일한 모델이 사용됩니다. 파일의 본문에는 서브에이전트에 제공되는
  • 03:00시스템 프롬프트가 들어 있습니다. 시스템 프롬프트는 서브에이전트에 지침을 제공하여
  • 03:05작업을 완료하고 주 에이전트에
  • 03:10정보를 반환하는 방법을 이해하도록 돕습니다.
  • 03:15이제 서브에이전트를 만든 다음 할 재미있는 부분입니다.
  • 03:18코드 변경을 몇 가지 수행하게 하고 Claude에게 이를 검토하도록 요청하여 서브에이전트를 테스트하세요.
  • 03:29예상할 때 서브에이전트가 사용되지 않는다면
  • 03:32description을 확인하세요. 더 구체적인 예시를 추가하면 Claude가 언제 위임해야 하는지 이해하는 데 도움이 됩니다.
  • 03:40여기까지입니다.
Watch on YouTube

서브에이전트 생성하기

서브에이전트를 생성하는 가장 쉬운 방법은 /agents 슬래시 명령을 사용하는 것입니다. 이 명령은 서브에이전트를 관리하는 메인 인터페이스를 엽니다. 거기서 Create new agent를 선택하세요.

먼저 서브에이전트의 범위를 선택하라는 요청을 받게 됩니다:

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

다음으로, 생성 방법을 선택할 수 있습니다. 구성을 직접 작성할 수도 있지만, 권장되는 방법은 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 -- 서브에이전트가 접근할 수 있는 도구 목록입니다. 생성 과정에서 선택한 내용과 일치하지만, 언제든지 여기서 목록을 편집할 수 있습니다.
  • model -- 사용할 Claude 모델을 지정합니다: sonnet, opus, haiku, 또는 inherit 중 하나입니다.
  • color -- 서브에이전트를 식별하기 위한 UI 색상입니다.

시스템 프롬프트

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

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

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

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

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

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

서브에이전트 테스트하기

서브에이전트를 생성한 후, 코드를 일부 변경하고 Claude에게 이를 리뷰하도록 요청하여 테스트해 보세요.

FastAPI 프로젝트가 열려 있는 코드 에디터와 사이드 패널의 Claude Code, code-reviewer 서브에이전트를 사용하여 최근 변경 사항을 리뷰하도록 요청받음

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