Claude Code 사용자 정의 Subagent 만들기 - 완벽 가이드

Claude Code를 사용하다 보면 반복적인 작업 패턴이 생기기 마련입니다. 코드 리뷰를 할 때마다 같은 체크리스트를 확인하거나, 디버깅할 때마다 동일한 절차를 따르게 되죠. 이런 작업을 전문화된 AI 에이전트에게 위임할 수 있다면 어떨까요? 바로 그것이 사용자 정의 Subagent입니다.

이 글에서는 Claude Code에서 나만의 Subagent를 만드는 방법을 처음부터 끝까지 정리해 보겠습니다.

---

Subagent란 무엇인가?

Subagent는 특정 작업에 특화된 AI 어시스턴트입니다. 메인 Claude 대화에서 복잡한 작업을 만나면, 해당 작업을 전문 Subagent에게 위임하여 독립적으로 처리하게 할 수 있습니다.

각 Subagent는 독립된 컨텍스트 윈도우에서 실행되며, 다음과 같은 요소를 개별적으로 설정할 수 있습니다.

• 커스텀 시스템 프롬프트 (어떤 역할을 수행할지)
• 사용 가능한 도구 제한 (Read, Write, Bash 등)
• 모델 선택 (Sonnet, Opus, Haiku)
• 최대 실행 턴 수
• 권한 모드

---

Subagent 파일은 어디에 저장하나?

Subagent 정의 파일의 저장 위치에 따라 적용 범위가 달라집니다.

저장 위치	적용 범위	우선순위
--agents CLI 플래그	현재 세션만	1 (최고)
.claude/agents/	현재 프로젝트	2
~/.claude/agents/	모든 프로젝트	3
플러그인의 agents/	플러그인 활성화 범위	4 (최저)

프로젝트 전용 에이전트는 .claude/agents/에, 모든 프로젝트에서 사용할 에이전트는 ~/.claude/agents/에 저장하면 됩니다.

---

Subagent 만드는 3가지 방법

방법 1: 대화형 CLI 사용 (추천)

가장 간편한 방법입니다. Claude Code에서 /agents 명령어를 입력하면 대화형 메뉴가 나타납니다.

/agents
→ Create new agent 선택
→ User-level 또는 Project-level 선택
→ Generate with Claude 옵션으로 자동 생성 가능
→ 도구, 모델, 색상 등 커스터마이즈

방법 2: 마크다운 파일 직접 작성

Subagent는 YAML 프론트매터가 포함된 마크다운 파일로 정의됩니다. 이 형식만 알면 직접 작성할 수 있습니다.

---
name: code-reviewer
description: 코드 품질과 보안을 검토하는 전문 리뷰어
tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit
model: sonnet
maxTurns: 5
---

당신은 시니어 코드 리뷰어입니다.

리뷰 체크리스트:
- 코드 가독성
- 함수/변수 네이밍
- 중복 코드 여부
- 에러 핸들링
- 보안 취약점

방법 3: CLI 플래그로 임시 생성

세션 한정으로 빠르게 에이전트를 만들고 싶을 때 사용합니다.

claude --agents '{
  "code-reviewer": {
    "description": "코드 리뷰 전문가",
    "prompt": "시니어 코드 리뷰어로서 품질과 보안을 검토하세요.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

---

YAML 프론트매터 주요 설정값

필드	필수	설명
name	O	고유 식별자 (소문자, 하이픈 사용)
description	O	Claude가 이 에이전트에 작업을 위임할 시점을 판단하는 설명
tools	X	허용할 도구 목록 (생략 시 모든 도구 상속)
disallowedTools	X	차단할 도구 목록
model	X	사용할 모델 (sonnet, opus, haiku, inherit)
permissionMode	X	권한 처리 방식
maxTurns	X	최대 에이전트 턴 수
memory	X	영구 메모리 범위 (user, project, local)
mcpServers	X	MCP 서버 연동 설정
hooks	X	라이프사이클 훅

description 필드가 가장 중요합니다. Claude는 이 설명을 기반으로 언제 해당 Subagent를 호출할지 결정합니다. 구체적이고 명확하게 작성해야 합니다.

---

사용 가능한 도구 목록

Subagent에 할당할 수 있는 주요 도구들입니다.

• Read - 파일 읽기
• Write - 파일 생성
• Edit - 파일 수정
• Bash - 터미널 명령어 실행
• Glob - 파일 패턴 검색
• Grep - 파일 내용 정규식 검색
• WebSearch - 웹 검색
• WebFetch - 웹 페이지 내용 가져오기
• Task - 다른 Subagent 생성 (메인 에이전트 전용)
• AskUserQuestion - 사용자에게 질문

도구 제한은 보안의 핵심입니다. 예를 들어 코드 리뷰 에이전트에는 Read, Grep, Glob만 주고 Write, Edit는 차단하는 것이 안전합니다.

---

권한 모드(Permission Mode) 이해하기

모드	동작	사용 사례
default	표준 권한 확인	일반 개발
acceptEdits	파일 수정 자동 승인	신뢰할 수 있는 워크플로우
dontAsk	권한 요청 자동 거부	읽기 전용 에이전트
delegate	조율 전용	다중 에이전트 코디네이터
bypassPermissions	모든 검사 건너뛰기 (주의)	CI/CD 파이프라인
plan	플랜 모드 (읽기 전용 탐색)	계획 수립 단계

---

실전 예제: 유용한 Subagent 3가지

1. 디버거 에이전트

---
name: debugger
description: 에러와 테스트 실패를 디버깅하는 전문가
tools: Read, Edit, Bash, Grep, Glob
---

당신은 근본 원인 분석 전문 디버거입니다.

호출 시:
1. 에러 메시지와 스택 트레이스 캡처
2. 재현 단계 파악
3. 실패 지점 격리
4. 최소한의 수정 적용
5. 솔루션 검증

2. 데이터 분석가 에이전트

---
name: data-scientist
description: SQL 쿼리와 데이터 인사이트 분석 전문가
tools: Bash, Read, Write
model: sonnet
---

당신은 SQL과 데이터 분석 전문 데이터 사이언티스트입니다.

호출 시:
1. 데이터 분석 요구사항 파악
2. 효율적인 SQL 쿼리 작성
3. 결과 분석 및 요약
4. 인사이트 명확하게 제시

3. 문서 작성 에이전트

---
name: doc-writer
description: API 문서와 README를 작성하는 기술 문서 전문가
tools: Read, Write, Glob, Grep
model: sonnet
---

당신은 기술 문서 작성 전문가입니다.

호출 시:
1. 코드베이스 구조 파악
2. 공개 API와 인터페이스 분석
3. 명확하고 예제가 포함된 문서 작성
4. 일관된 포맷 유지

---

영구 메모리(Persistent Memory) 활용

Subagent에 memory 필드를 설정하면, 에이전트가 학습한 내용을 세션 간에 유지할 수 있습니다.

---
name: code-reviewer
description: 코드를 리뷰하고 패턴을 학습합니다
memory: user
---

메모리 유형별 저장 위치는 다음과 같습니다.

• user: ~/.claude/agent-memory/<agent-name>/ (모든 프로젝트 공유)
• project: .claude/agent-memory/<agent-name>/ (팀 공유 가능)
• local: .claude/agent-memory-local/<agent-name>/ (로컬 전용)

프로젝트의 코드 패턴, 아키텍처 결정사항, 자주 발견되는 이슈 등을 축적하면 시간이 지날수록 더 정확한 리뷰가 가능해집니다.

---

Claude Agent SDK로 프로그래밍 방식으로 만들기

CLI 외에도 Python이나 TypeScript SDK를 사용해 코드에서 직접 Subagent를 정의할 수 있습니다.

Python 예제

from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition
import asyncio

async def main():
    async for message in query(
        prompt="코드 리뷰 에이전트로 이 코드베이스를 리뷰해줘",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Task"],
            agents={
                "code-reviewer": AgentDefinition(
                    description="코드 품질과 보안 리뷰 전문가",
                    prompt="코드 품질을 분석하고 개선점을 제안하세요.",
                    tools=["Read", "Glob", "Grep"]
                )
            }
        )
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

TypeScript 예제

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "코드 리뷰 에이전트로 이 코드베이스를 리뷰해줘",
  options: {
    allowedTools: ["Read", "Glob", "Grep", "Task"],
    agents: {
      "code-reviewer": {
        description: "코드 품질과 보안 리뷰 전문가",
        prompt: "코드 품질을 분석하고 개선점을 제안하세요.",
        tools: ["Read", "Glob", "Grep"]
      }
    }
  }
})) {
  if ("result" in message) console.log(message.result);
}

---

Subagent 활용 베스트 프랙티스

1. 하나의 역할에 집중하기
각 Subagent는 하나의 전문 분야만 담당하도록 설계하세요. "만능" 에이전트보다 "전문" 에이전트가 훨씬 효과적입니다.

2. description을 구체적으로 작성하기
Claude가 언제 이 에이전트를 호출할지 판단하는 핵심 기준입니다. "코드 리뷰" 보다는 "코드 변경 후 품질, 보안, 유지보수성을 검토하는 전문 리뷰어"처럼 구체적으로 작성하세요.

3. 최소 권한 원칙 적용하기
필요한 도구만 부여하세요. 읽기 전용 작업에는 Write, Edit를 제외하는 것이 안전합니다.

4. 버전 관리에 포함하기
프로젝트 수준 에이전트(.claude/agents/)는 git에 커밋하여 팀원들과 공유할 수 있습니다.

5. 병렬 실행 활용하기
독립적인 작업은 여러 Subagent를 동시에 실행하여 시간을 절약할 수 있습니다.

---

마치며

사용자 정의 Subagent는 Claude Code의 활용도를 크게 높여주는 기능입니다. 반복적인 작업을 자동화하고, 전문화된 에이전트에게 작업을 위임함으로써 개발 생산성을 한 단계 끌어올릴 수 있습니다.

처음에는 간단한 코드 리뷰 에이전트부터 시작해서, 점차 자신의 워크플로우에 맞는 에이전트를 추가해 나가보세요. /agents 명령어 하나로 시작할 수 있으니, 지금 바로 만들어 보시는 건 어떨까요?

---

참고 자료:

• Claude Agent SDK 공식 문서
• Claude Code Subagent 가이드