[Claude] Claude Code에서 Subagent 생성 및 활용하는 방법

 

이번 글에서는 Claude Code에서 Subagent를 만들고 활용하는 방법을 정리해보고자 합니다. Claude Code 설치 방법, 토큰 관리 팁 등 Claude Code 관련된 글 링크 모음은 글 아래에 있으니 참고해 주시길 바랍니다.

 

Claude Code Docs에 따르면, Subagent는 특정 유형의 태스크를 처리하는데 특화된 AI 어시스턴트라고 설명하고 있습니다. Claude Code 활용 중 subagent의 설명과 일치하는 작업을 만나면 해당 작업을 subagent에게 위임하게 되고, subagent는 독립적으로 작동하여 결과를 반환합니다.

 

그럼 Claude Code에서 subagent를 생성하는 방법부터 살펴보겠습니다.

 

* 다만 docs나 Claude Code 내에서 용어를 subagent와 agent를 혼용하고 있어, 앞으로 제목에서는 subagent 단어를 쓰고 내용에서는 비교적 짧은 agent 단어를 쓰려고 합니다.

 

1. Claude Code에서 Subagent 생성하는 방법

우선 Claude Code에서 '/agents' 명령어를 실행하고, 'Create new agent'를 선택합니다.

 

그럼 'Project'와 'Personal', agent 범위에 대한 두 가지 옵션이 나타나게 됩니다.

 

  1) Project는 현재 프로젝트에서만 활용하는 agent

  2) Personal은 모든 프로젝트에서 활용할 수 있는 개인 agent입니다.

 

각 agent 범위에 동일한 이름의 agent가 있을 경우에는 Project가 우선순위를 가지게 됩니다. 저는 모든 프로젝트에서 범용적으로 활용할 수 있는 'Personal'을 선택하도록 하겠습니다. 

 

다음은 생성 방법입니다. 저는 아직 agent에 대해 자세히 알지는 못하기 때문에, 추천 방법인 'Generate with Claude'를 선택하겠습니다.

 

이제 해당 agent가 무엇을 수행하고 언제 활용되는지 설명해달라는 창이 나타나게 됩니다.

 

저는 가장 기본적인 code-reviewer agent를 만들고자 했고, 여러 자료들을 참고해 description을 아래와 같이 작성해 입력했습니다.

---
name: code-reviewer
description: Reviews code for quality and best practices. MUST BE USED for all code changes
tools: Read, Glob, Grep, Bash
model: sonnet
---

Provide a code review from a senior developer’s perspective. 
Categorize feedback into Critical, Warning, and Suggestion. 
Focus specifically on security, performance, and readability, and include concrete, actionable recommendations for improvement.

 

 

그럼 description으로부터 agent를 생성하는 프로세스가 진행됩니다.

 

생성이 완료되면 agent가 사용 가능한 툴들을 설정하는 창이 나타납니다. 저는 모든 툴들을 사용할 수 있도록 설정하겠습니다.

 

다음으로 선택할 것은 모델입니다. 이전 description에도 작성했듯이 모델은 sonnet을 선택하도록 하겠습니다.

 

그리고 색도 선택해 줍니다.

 

agent 메모리 설정은 Personal 범위에 맞게 'Enable'을 선택하겠습니다.

 

마지막으로 agent 생성에 대한 확인창이 나타납니다. 이전에 작성한 내용을 바탕으로 description과 prompt가 수정돼서 작성되었습니다. Enter를 눌러줍니다.

 

User agents에 방금 생성한 code-reviewer가 있는 것을 확인할 수 있고, 이제 agent 생성은 완료된 것입니다.

 

2. Claude Code에서 Subagent 활용하는 방법

그럼 간단하게 방금 생성한 agent를 활용해보도록 하겠습니다. 최근 코드 변경사항을 검토해 달라고 요청해 봤습니다.

 

결과는 다음과 같습니다. 현재 프로젝트에서 가장 최근 변경사항이 CLAUDE.md 파일을 수정한 것이었는데, 해당 내용에 대해 자세히 코멘트해 준 것을 볼 수 있습니다.

 

code-review 외에도 debugger, data-scientist 등 다양한 agent를 생성할 수 있으니 여러 시도를 하며 본인에 맞게 최적화하시길 바랍니다.

 

부가적으로 Claude Code에는 이미 내장된 agents들이 존재합니다. explore(탐색 및 분석용), plan(계획 수립을 위한 컨텍스트 수집용), general-purpose 등이 있으며, 보다 자세한 설명은 Docs 내 내장 subagent 부분을 참고하시길 바랍니다.

 

 

📌 Claude Code 관련 글 모음

• Claude Code 2.0 설치 방법 (mac)
• Claude Code 2.0 설치 방법 (Windows)
• VS Code에서 Claude Code 활용하는 방법
• Claude Code 토큰 사용 팁 정리
• Claude Code 자주 사용하는 명령어 정리
• Claude Code에서 Skills 활용하는 방법

 

<참고>

1. https://code.claude.com/docs/en/sub-agents

Create custom subagents - Claude Code Docs

 

2. https://goddaehee.tistory.com/454

Claude Code 공식문서 리뷰-Build with Claude Code[1] : Subagents

 

3. https://tech.hyperithm.com/claude_code_guides_2

하이퍼리즘 기술 블로그