서브에이전트

Claude Code에서 작업별 워크플로우와 향상된 컨텍스트 관리를 위한 전문화된 AI 서브에이전트를 생성하고 사용하세요.

Claude Code의 사용자 정의 서브에이전트는 특정 유형의 작업을 처리하기 위해 호출할 수 있는 전문화된 AI 어시스턴트입니다. 이들은 사용자 정의 시스템 프롬프트, 도구 및 별도의 컨텍스트 창을 가진 작업별 구성을 제공하여 더 효율적인 문제 해결을 가능하게 합니다.

서브에이전트란 무엇인가요?

서브에이전트는 Claude Code가 작업을 위임할 수 있는 사전 구성된 AI 개성입니다. 각 서브에이전트는:

• 특정 목적과 전문 영역을 가집니다
• 메인 대화와 분리된 자체 컨텍스트 창을 사용합니다
• 사용이 허용된 특정 도구로 구성될 수 있습니다
• 행동을 안내하는 사용자 정의 시스템 프롬프트를 포함합니다

Claude Code가 서브에이전트의 전문성과 일치하는 작업을 만나면, 해당 작업을 전문화된 서브에이전트에게 위임할 수 있으며, 서브에이전트는 독립적으로 작업하고 결과를 반환합니다.

주요 이점

컨텍스트 보존

각 서브에이전트는 자체 컨텍스트에서 작동하여 메인 대화의 오염을 방지하고 고수준 목표에 집중할 수 있게 합니다.

전문화된 전문성

서브에이전트는 특정 도메인에 대한 세부 지침으로 미세 조정될 수 있어 지정된 작업에서 더 높은 성공률을 달성합니다.

재사용성

한 번 생성되면 서브에이전트는 다양한 프로젝트에서 사용할 수 있고 일관된 워크플로우를 위해 팀과 공유할 수 있습니다.

유연한 권한

각 서브에이전트는 다른 도구 액세스 수준을 가질 수 있어 강력한 도구를 특정 서브에이전트 유형으로 제한할 수 있습니다.

빠른 시작

첫 번째 서브에이전트를 생성하려면:

1. 서브에이전트 인터페이스 열기

   다음 명령을 실행하세요:

   /agents
   

2. '새 에이전트 생성' 선택

   프로젝트 수준 또는 사용자 수준 서브에이전트를 생성할지 선택하세요

3. 서브에이전트 정의

   • 권장: 먼저 Claude로 생성한 다음 사용자 정의하여 자신만의 것으로 만드세요
   • 서브에이전트를 자세히 설명하고 언제 사용해야 하는지 명시하세요
   • 액세스 권한을 부여할 도구를 선택하세요 (또는 모든 도구를 상속받으려면 비워두세요)
   • 인터페이스는 모든 사용 가능한 도구를 보여주어 선택을 쉽게 만듭니다
   • Claude로 생성하는 경우 e를 눌러 자신의 에디터에서 시스템 프롬프트를 편집할 수도 있습니다
4. 저장 및 사용

   이제 서브에이전트를 사용할 수 있습니다! Claude는 적절할 때 자동으로 사용하거나 명시적으로 호출할 수 있습니다:

   > code-reviewer 서브에이전트를 사용하여 최근 변경사항을 확인해주세요
   

서브에이전트 구성

파일 위치

서브에이전트는 두 가지 가능한 위치에 YAML 프론트매터가 있는 Markdown 파일로 저장됩니다:

유형	위치	범위	우선순위
프로젝트 서브에이전트	.claude/agents/	현재 프로젝트에서 사용 가능	최고
사용자 서브에이전트	~/.claude/agents/	모든 프로젝트에서 사용 가능	낮음

서브에이전트 이름이 충돌할 때, 프로젝트 수준 서브에이전트가 사용자 수준 서브에이전트보다 우선합니다.

파일 형식

각 서브에이전트는 다음 구조를 가진 Markdown 파일로 정의됩니다:

---
name: your-sub-agent-name
description: Description of when this subagent should be invoked
tools: tool1, tool2, tool3  # Optional - inherits all tools if omitted
---

Your subagent's system prompt goes here. This can be multiple paragraphs
and should clearly define the subagent's role, capabilities, and approach
to solving problems.

Include specific instructions, best practices, and any constraints
the subagent should follow.

구성 필드

필드	필수	설명
name	예	소문자와 하이픈을 사용하는 고유 식별자
description	예	서브에이전트의 목적에 대한 자연어 설명
tools	아니오	특정 도구의 쉼표로 구분된 목록. 생략하면 메인 스레드의 모든 도구를 상속

사용 가능한 도구

서브에이전트는 Claude Code의 모든 내부 도구에 대한 액세스 권한을 부여받을 수 있습니다. 사용 가능한 도구의 전체 목록은 도구 문서를 참조하세요.

권장: 도구 액세스를 수정하려면 /agents 명령을 사용하세요 - 연결된 MCP 서버 도구를 포함한 모든 사용 가능한 도구를 나열하는 대화형 인터페이스를 제공하여 필요한 도구를 더 쉽게 선택할 수 있습니다.

도구 구성에는 두 가지 옵션이 있습니다:

• tools 필드를 생략하여 메인 스레드의 모든 도구를 상속받습니다 (기본값), MCP 도구 포함
• 개별 도구를 지정하여 더 세밀한 제어를 위해 쉼표로 구분된 목록으로 지정합니다 (수동으로 또는 /agents를 통해 편집 가능)

MCP 도구: 서브에이전트는 구성된 MCP 서버의 MCP 도구에 액세스할 수 있습니다. tools 필드가 생략되면 서브에이전트는 메인 스레드에서 사용 가능한 모든 MCP 도구를 상속받습니다.

서브에이전트 관리

/agents 명령 사용 (권장)

/agents 명령은 서브에이전트 관리를 위한 포괄적인 인터페이스를 제공합니다:

/agents

이것은 다음을 할 수 있는 대화형 메뉴를 엽니다:

• 모든 사용 가능한 서브에이전트 보기 (내장, 사용자, 프로젝트)
• 안내된 설정으로 새 서브에이전트 생성
• 도구 액세스를 포함한 기존 사용자 정의 서브에이전트 편집
• 사용자 정의 서브에이전트 삭제
• 중복이 있을 때 어떤 서브에이전트가 활성화되어 있는지 확인
• 사용 가능한 도구의 완전한 목록으로 도구 권한을 쉽게 관리

직접 파일 관리

서브에이전트 파일을 직접 작업하여 서브에이전트를 관리할 수도 있습니다:

# 프로젝트 서브에이전트 생성
mkdir -p .claude/agents
echo '---
name: test-runner
description: Use proactively to run tests and fix failures
---

You are a test automation expert. When you see code changes, proactively run the appropriate tests. If tests fail, analyze the failures and fix them while preserving the original test intent.' > .claude/agents/test-runner.md

# 사용자 서브에이전트 생성
mkdir -p ~/.claude/agents
# ... 서브에이전트 파일 생성

서브에이전트 효과적으로 사용하기

자동 위임

Claude Code는 다음을 기반으로 작업을 능동적으로 위임합니다:

• 요청의 작업 설명
• 서브에이전트 구성의 description 필드
• 현재 컨텍스트와 사용 가능한 도구

더 능동적인 서브에이전트 사용을 장려하려면 description 필드에 “능동적으로 사용” 또는 “반드시 사용해야 함”과 같은 문구를 포함하세요.

명시적 호출

명령에서 특정 서브에이전트를 언급하여 요청하세요:

> test-runner 서브에이전트를 사용하여 실패한 테스트를 수정해주세요
> code-reviewer 서브에이전트가 최근 변경사항을 살펴보게 해주세요
> debugger 서브에이전트에게 이 오류를 조사하도록 요청해주세요

예제 서브에이전트

코드 리뷰어

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is simple and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

디버거

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not just symptoms.

데이터 사이언티스트

---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.

모범 사례

• Claude 생성 에이전트로 시작: 초기 서브에이전트를 Claude로 생성한 다음 반복하여 개인적으로 만드는 것을 강력히 권장합니다. 이 접근 방식은 최상의 결과를 제공합니다 - 특정 요구사항에 맞게 사용자 정의할 수 있는 견고한 기반을 제공합니다.

• 집중된 서브에이전트 설계: 하나의 서브에이전트가 모든 것을 하도록 만들려고 하지 말고 단일하고 명확한 책임을 가진 서브에이전트를 생성하세요. 이는 성능을 향상시키고 서브에이전트를 더 예측 가능하게 만듭니다.

• 세부적인 프롬프트 작성: 시스템 프롬프트에 구체적인 지침, 예제 및 제약사항을 포함하세요. 더 많은 안내를 제공할수록 서브에이전트가 더 잘 수행됩니다.

• 도구 액세스 제한: 서브에이전트의 목적에 필요한 도구만 부여하세요. 이는 보안을 향상시키고 서브에이전트가 관련 작업에 집중하는 데 도움이 됩니다.

• 버전 관리: 팀이 혜택을 받고 협력적으로 개선할 수 있도록 프로젝트 서브에이전트를 버전 관리에 체크인하세요.

고급 사용법

서브에이전트 체이닝

복잡한 워크플로우의 경우 여러 서브에이전트를 체이닝할 수 있습니다:

> 먼저 code-analyzer 서브에이전트를 사용하여 성능 문제를 찾은 다음 optimizer 서브에이전트를 사용하여 수정해주세요

동적 서브에이전트 선택

Claude Code는 컨텍스트를 기반으로 서브에이전트를 지능적으로 선택합니다. 최상의 결과를 위해 description 필드를 구체적이고 행동 지향적으로 만드세요.

성능 고려사항

• 컨텍스트 효율성: 에이전트는 메인 컨텍스트를 보존하는 데 도움이 되어 더 긴 전체 세션을 가능하게 합니다
• 지연 시간: 서브에이전트는 호출될 때마다 깨끗한 상태로 시작하며 작업을 효과적으로 수행하는 데 필요한 컨텍스트를 수집하면서 지연 시간을 추가할 수 있습니다.

관련 문서

• 슬래시 명령 - 다른 내장 명령에 대해 알아보기
• 설정 - Claude Code 동작 구성
• 훅 - 이벤트 핸들러로 워크플로우 자동화