# AI 에이전트 개발: Claude Code 서브에이전트 파일과 예시 5가지
> 에이전트 파일과 설명, 완성된 템플릿 5개, 병렬 실행, Managed Agents, 예시를 보존한 제한 사항과 비용 설명.
Source: https://ailoot.ai/blog/ko/claude-code-subagents/
Canonical: https://ailoot.ai/blog/ko/claude-code-subagents/
Language: ko
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-222
Revision: sha256-9268ef1f1850f04d83634f218522c4d2d506d6a74b65789c171df916322c9273
핵심 요점
Claude Code의 서브에이전트는 자체 컨텍스트, 도구 모음, 시스템 프롬프트를 갖춘 전문 AI 어시스턴트입니다. 메인 채팅이 서브에이전트에 작업을 맡길지 자체적으로 결정하거나, `@agent-`를 사용해 이름으로 호출할 수 있습니다. 서브에이전트는 메인 대화를 어지럽히지 않고 범위가 좁은 작업을 처리한 뒤 최종 요약만 반환합니다. 이 가이드에서는 서브에이전트가 Skill과 어떻게 다른지, Claude가 실제로 호출하도록 설명을 작성하는 방법, 30분 안에 사용할 수 있는 역할 5가지를 만드는 방법을 설명합니다.
Ailoot 사용에 관한 실용적인 안내는 [문서](https://ailoot.ai/docs/)에서 확인할 수 있습니다.
## Claude Code 서브에이전트란 무엇이며, 왜 ‘또 다른 Skill’이 아닌가요?
핵심 요점
서브에이전트는 자체 컨텍스트, 시스템 프롬프트, 도구 모음을 갖춘 전문 AI 어시스턴트입니다. Anthropic의 공식 문서는 서브에이전트를 별도의 컨텍스트에서 보조 작업을 맡고 결과 요약만 반환하는 어시스턴트로 설명합니다. 메인 채팅에 로드되어 메인 채팅의 메모리와 함께 작동하는 [Skills](https://ailoot.ai/blog/ko/claude-code-skills-library/)와 달리, 서브에이전트는 분리된 환경에서 작동합니다. 이것이 서브에이전트의 가장 큰 가치입니다.
Claude Code 문서는 이를 다음과 같이 정의합니다.
서브에이전트는 특정 유형의 작업을 위한 전문 AI 어시스턴트입니다. 보조 작업 때문에 메인 대화에 다시 가져오지 않을 검색 결과, 로그 또는 파일 내용이 가득 찰 것 같다면 서브에이전트를 사용하세요. 서브에이전트가 자체 컨텍스트에서 작업하고 결과만 반환합니다.
— Claude Code 문서, https://code.claude.com/docs/en/sub-agents
기업가가 이해하기 쉽게 표현해 보겠습니다. 부동산 중개업체를 떠올려 보세요. 이곳에는 이사, 마케터, 변호사, 영업 관리자가 있습니다. 한 직원이 이 모든 역할을 오가는 것은 팀이 아닙니다. 과부하가 걸린 사람 한 명일 뿐입니다. 각자가 자신만의 컨텍스트와 책임 영역을 가지고, 이사는 업무를 배정하고 결과를 모을 때 팀이 만들어집니다.
Claude Code의 서브에이전트도 같은 방식으로 작동합니다. 메인 채팅은 이사입니다. 서브에이전트는 범위가 좁은 작업, 자체 컨텍스트, 도구 모음을 가진 전문가입니다. 작업이 전문가의 설명에 부합하면 이사가 그 작업을 위임하며, 세부 사항에 빠져들지 않습니다.
### Anthropic이 서브에이전트를 만든 5가지 목적
Anthropic 문서는 서브에이전트를 직접 만들어야 하는 이유를 정확히 다섯 가지로 제시합니다.
서브에이전트는 조사와 구현을 메인 대화 밖에서 처리해 컨텍스트를 보존하고, 서브에이전트가 사용할 수 있는 도구를 제한해 제약을 적용하며, 사용자 수준 서브에이전트를 통해 프로젝트 간 설정을 재사용하고, 특정 영역에 초점을 둔 시스템 프롬프트로 동작을 전문화하며, Haiku처럼 빠르고 저렴한 모델에 작업을 맡겨 비용을 관리하도록 도와줍니다.
— Claude Code 문서, https://code.claude.com/docs/en/sub-agents
프로그래머가 아닌 사람에게 이 목록에서 가장 실용적인 항목은 **비용 관리**입니다. 부담이 큰 조사 작업은 저렴한 Haiku 모델에 맡기고, 메인 대화는 Sonnet이나 Opus로 계속할 수 있습니다. 토큰 절감 효과는 그에 비례합니다.
### 설치한 버전의 중첩 지원 확인하기
이 템플릿은 메인 세션이 작업자에게 직접 위임하는 구조입니다. 예전 문서의 “하위 에이전트는 다른 하위 에이전트를 시작할 수 없다”를 영구 규칙으로 보지 마세요. 중첩은 설치 버전과 허용 도구에 달려 있습니다. [별도 중첩 가이드](https://ailoot.ai/blog/ko/claude-code-nested-subagents/)의 버전별 방식을 참고하고 더 깊게 계획하기 전에 실제 지원을 검증하세요.
## 서브에이전트는 Skill, 슬래시 명령어, Hook과 어떻게 다른가요?
핵심 요점
Claude Code에는 서로 바꿔 쓸 수 없는 확장 메커니즘이 네 가지 있습니다. CLAUDE.md는 항상 로드되는 영구 지식입니다. Skills는 트리거되면 메인 채팅에 로드되는 준비된 방법론입니다. 슬래시 명령어는 일회성 작업을 위한 명시적인 `/command` 버튼입니다. 서브에이전트는 자체 컨텍스트를 가진 전문가이며 메인 채팅이 작업을 위임합니다. 가장 흔한 실수는 Skill이 필요한 곳에 서브에이전트를 만드는 것입니다.
앞선 [Skills](https://ailoot.ai/blog/ko/claude-code-skills-library/) 가이드에서 설명했듯이 Claude Code의 Skills와 슬래시 명령어는 사실상 하나의 형식으로 합쳐졌습니다. 하지만 서브에이전트는 다른 존재입니다. 그저 “더 큰 Skill”이 아닙니다.
네 가지 메커니즘을 요약한 표입니다.
| 기능 | CLAUDE.md | Skill | 슬래시 명령어 | 서브에이전트 |
|----|----|----|----|----|
| 로드 시점 | 항상 | 설명이 트리거될 때 | 명시적인 `/name` 명령을 실행할 때 | 위임하거나 `@agent-name`으로 호출할 때 |
| 작동 위치 | 메인 컨텍스트 | 메인 컨텍스트 | 메인 컨텍스트 | 자체 격리 컨텍스트 |
| 모델 | 메인 채팅과 동일 | 동일 | 동일 | 무엇이든 가능: Haiku, Sonnet, Opus, 상속 |
| 도구 | 사용 가능한 모든 도구 | 상속 | 상속 | `tools:`로 제한할 수 있음 |
| 반환 내용 | \- | 메인 대화에 바로 표시 | 메인 대화에 바로 표시 | 최종 요약만 |
| 병렬 처리 | \- | 아니요 | 아니요 | 가능, 여러 개를 병렬 실행 |
| 세션 간 메모리 | 인접 파일 | 인접 파일 | 인접 파일 | `memory: user/project/local` 필드 |
영어 가이드에서 설명하기 좋은 표현은 다음과 같습니다. Skills는 레시피이고, 서브에이전트는 전문 동료입니다.
간단히 말해, Skills는 레시피와 같고 서브에이전트는 전문 동료와 같습니다.
실제로는 다음과 같이 작동합니다. Skill은 설명이 작업과 일치할 때 자동으로 활성화되지만, 서브에이전트는 명시적으로 호출됩니다. 메인 채팅이 위임을 결정하거나, 사용자가 이름으로 호출할 수 있습니다.
### 의사결정 트리: “어떤 것을 선택해야 할까요?”
“Claude가 X를 해 줬으면 좋겠다”라고 생각할 때 다음 네 가지 질문을 해 보세요.
1. **항상 사용할 수 있어야 하는 지식인가요?** 예를 들어 “사용자가 선호하는 언어로 현지화한다” 또는 “em dash를 사용하지 않는다” 같은 내용입니다. `CLAUDE.md`에 넣으세요.
2. **지금은 수동으로 수행하지만 특정 상황에 트리거되는 방법론인가요?** 예를 들어 “매주 월요일에 영업 보고서를 작성한다” 같은 내용입니다. **Skill**을 만드세요.
3. **메인 채팅의 컨텍스트를 많이 차지하거나 병렬로 실행할 수 있는 작업인가요?** 예를 들어 “30개 출처를 대상으로 한 심층 조사” 또는 “새 기능을 작성하는 동안의 보안 감사” 같은 작업입니다. **서브에이전트**를 만드세요.
4. **Claude Code의 이벤트에 자동으로 대응해야 하나요?** 예를 들어 “매번 Edit 후에 린터를 실행한다” 같은 요구입니다. **Hook**을 작성하세요.
기업가의 작업 중 90%는 처음 두 범주에 속합니다. 서브에이전트는 “한 번에 작업 하나”에서 오케스트레이션으로 넘어갈 때 사용하는 고급 도구입니다.
## 서브에이전트는 어디에 있으며 어떤 것이 우선 적용되나요?
핵심 요점
Claude Code 서브에이전트는 조직의 관리 설정부터 플러그인까지, 우선순위가 서로 다른 다섯 곳에 저장할 수 있습니다. 이름이 같은 파일이 둘이면 우선순위가 높은 파일이 적용됩니다. 1인 기업가가 가장 흔히 사용하는 구성은 개인용 범용 에이전트를 위한 `~/.claude/agents/`와 프로젝트별 에이전트를 위한 각 프로젝트 내부의 `.claude/agents/`입니다.
서브에이전트 계층은 우선순위가 높은 순서부터 낮은 순서까지 다섯 단계로 구성됩니다.
| 수준 | 경로 | 적용 범위 | 우선순위 |
|----|----|----|----|
| Enterprise | 조직 관리 설정 | 회사의 모든 직원 | 1(가장 높음) |
| Session | JSON을 사용하는 CLI 플래그 `--agents` | 현재 세션에만 적용 | 2 |
| Project | `.claude/agents/name.md` | 현재 프로젝트에만 적용 | 3 |
| Personal | `~/.claude/agents/name.md` | 모든 프로젝트 | 4 |
| Plugin | `/agents/name.md` | 플러그인이 활성화된 모든 곳 | 5(가장 낮음) |
우선순위 로직은 Skills 및 CLAUDE.md와 같습니다. 조직 설정이 CLI보다 우선하고, CLI가 프로젝트보다 우선하며, 프로젝트가 개인 설정보다 우선하고, 개인 설정이 플러그인보다 우선합니다.
### 로드 시 알아야 할 사항
Claude Code 세션이 시작될 때 서브에이전트가 로드됩니다. 디스크에서 에이전트 파일을 직접 편집하면 세션을 다시 시작해야 변경 사항이 반영됩니다. 대화형 `/agents` UI에서 편집하면 즉시 적용됩니다.
범위마다 서브에이전트 하나는 파일 하나를 뜻합니다. `.claude/agents/`에 `code-reviewer.md`와 그 옆에 또 다른 `code-reviewer.md`(예를 들어 오래된 백업에서 가져온 파일)가 있으면 Claude Code는 둘 중 하나를 알리지 않고 무시합니다. 알림은 표시되지 않습니다.
플러그인 서브에이전트는 별도로 취급됩니다. 보안 제한이 있어 `hooks`, `mcpServers`, `permissionMode` 필드를 **지원하지 않습니다**. 이로써 타사 플러그인을 설치해도 해당 플러그인이 컴퓨터에서 임의 코드를 실행할 권한을 얻을 수 없습니다.
## 서브에이전트 파일의 구조: Frontmatter와 본문
핵심 요점
서브에이전트는 상단의 YAML frontmatter와 그 아래의 시스템 프롬프트로 구성된 단일 Markdown 파일입니다. 최소 두 필드는 `name`(소문자 + 하이픈)과 `description`(Claude가 언제 위임해야 하는지)입니다. 전체 스키마에는 16개 필드가 있습니다. tools, disallowedTools, model, permissionMode, maxTurns, skills, mcpServers, hooks, memory, background, effort, isolation, color, initialPrompt입니다. Anthropic은 설명을 간결하게 유지하라고 권합니다. 트리거가 명확할수록 Claude가 더 정확하게 서브에이전트를 활성화합니다.
공식 문서의 최소 예시는 단 9줄입니다.
```markdown
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.
```
이 정도면 충분합니다. 사용자가 메인 채팅에서 “내 PR을 검토해 줘”라고 말하면 Claude는 설명에서 “reviewer / code / quality”를 찾아 서브에이전트에게 위임합니다. 서브에이전트는 diff를 읽고 의견을 작성한 뒤 메인 채팅에 요약을 반환합니다. 메인 채팅은 로그와 중간 분석으로 어지럽혀지지 않습니다.
### 전체 Frontmatter 스키마
| 필드 | 필수 여부 | 기능 |
|----|----|----|
| `name` | 예 | 고유 식별자, 소문자 + 하이픈. 파일 이름이 반드시 일치해야 하는 것은 아님 |
| `description` | 예 | Claude가 위임하는 시점. 자동화 트리거 역할을 함 |
| `tools` | 아니요 | 허용된 도구 목록. 생략하면 부모의 모든 도구를 상속 |
| `disallowedTools` | 아니요 | 차단 목록. 먼저 적용한 뒤 `tools`를 적용 |
| `model` | 아니요 | `haiku` / `sonnet` / `opus` / 전체 ID / `inherit`(기본값) |
| `permissionMode` | 아니요 | `default` / `acceptEdits` / `auto` / `dontAsk` / `bypassPermissions` / `plan` |
| `maxTurns` | 아니요 | 중단 전 단계 수 제한 |
| `skills` | 아니요 | 시작 시 서브에이전트 컨텍스트에 로드할 Skills |
| `mcpServers` | 아니요 | 이 서브에이전트만 사용할 수 있는 MCP 서버 |
| `hooks` | 아니요 | 이 서브에이전트에만 적용되는 PreToolUse / PostToolUse / Stop |
| `memory` | 아니요 | `user` / `project` / `local`: 세션 간 메모리를 저장할 폴더 |
| `background` | 아니요 | `true`: 항상 백그라운드에서 실행. 기본값은 `false` |
| `effort` | 아니요 | `low` / `medium` / `high` / `xhigh` / `max`: 추론 수준 |
| `isolation` | 아니요 | `worktree`: 별도의 git worktree에서 실행 |
| `color` | 아니요 | UI 색상: red / blue / green / yellow / purple / orange / pink / cyan |
| `initialPrompt` | 아니요 | `--agent`를 통해 실행될 때 서브에이전트가 처음 보는 문구 |
`model: haiku` 필드는 앞서 언급한 다섯 가지 목표 중 “비용 관리”에 해당합니다. 문서 페이지 50개를 읽는 조사 에이전트가 있다면 Haiku로 실행해 Opus와 비교해 5–7배 절약하세요.
`isolation: worktree` 필드는 중요한 문제를 해결합니다. 서브에이전트가 리팩터링이나 마이그레이션처럼 잠재적으로 위험한 변경을 하지만, 작업 중인 복사본은 건드리지 않기를 바랄 수 있습니다. `isolation: worktree`를 설정하면 Claude Code가 프로젝트의 임시 git 복사본을 만듭니다. 서브에이전트는 그곳에서 작업하고 검토할 diff를 반환합니다.
### 파일 본문은 시스템 프롬프트입니다
Frontmatter 뒤에는 일반 Markdown, 즉 서브에이전트의 시스템 프롬프트가 옵니다. 특별한 구조는 필요하지 않지만, 다음은 검증된 패턴입니다.
1. **정체성** — 한 문장으로 표현합니다. “너는 코드 리뷰어다”, “너는 보안 감사자다”, “너는 문서 관리자다.”
2. **호출되는 상황과 가장 먼저 할 일** — 작업을 받은 뒤 수행할 첫 2–3가지 작업입니다.
3. **확인 항목 또는 단계 목록** — 서브에이전트가 따라야 할 5–10가지 항목입니다.
4. **반환할 내용** — 최종 보고서 형식입니다. 형식을 지정하지 않으면 서브에이전트가 구조화된 요약 대신 “에세이”를 작성하므로 매우 중요합니다.
5. **하지 않을 일** — 명시적인 제한입니다. 이 섹션이 없으면 서브에이전트는 즉흥적으로 처리하기 시작합니다.
파일 본문은 200–500줄로 유지하세요. 더 길어지면 긴 참고 내용을 인접한 별도 파일로 옮기고 프롬프트에서 링크하세요.
## Claude가 서브에이전트를 확실히 호출하도록 설명을 작성하는 방법
핵심 요점
설명은 Claude가 세션 시작 시 확인하고 위임 여부를 결정하는 유일한 필드입니다. 포럼에서 가장 흔한 불만은 “서브에이전트를 작성했는데 Claude가 호출하지 않는다”는 것입니다. 해결법은 세 부분으로 구성된 공식입니다. 하는 일 + 따옴표로 묶은 트리거 문구 + 사용하지 말아야 할 상황입니다. Anthropic은 Claude가 서브에이전트를 적극적으로 호출하도록 설명에 “use proactively” 또는 “use immediately after” 같은 문구를 명시적으로 넣으라고 권합니다.
코드 검토용 서브에이전트를 설정했지만 Claude가 에이전트를 사용하지 않고 모든 일을 직접 하는 경우가 있습니다. 대개 이유는 하나입니다. 설명에 “코드 검토 도우미”라고만 적혀 있습니다. Claude는 언제 호출해야 하는지 알지 못합니다.
### 효과적인 설명을 위한 공식(3부분)
**1부 — 하는 일.** 과정이 아니라 결과를 한 문장으로 설명합니다. “코드를 분석한다”가 아니라 “코드에서 취약점을 찾고 심각도와 수정 방법을 포함한 목록을 반환한다”라고 씁니다.
**2부 — 호출해야 할 때.** 사용자가 실제로 요청하는 방식 그대로 3–5개 문구를 따옴표로 묶습니다. 추측하지 말고 채팅 기록과 실제 표현을 살펴보세요.
**3부 — 호출하면 안 되는 때.** 이 서브에이전트가 응답하면 안 되는 유사 작업을 1–2개 설명합니다. 이 부분이 없으면 비슷한 에이전트 둘이 계속 충돌합니다.
### 마법의 문구 “Use Proactively”
Anthropic의 공식 문서는 다음과 같이 직접 권고합니다.
Claude는 요청의 작업 설명, 서브에이전트 설정의 description 필드, 현재 컨텍스트를 바탕으로 작업을 자동 위임합니다. 적극적인 위임을 유도하려면 서브에이전트 설명에 ‘use proactively’ 같은 문구를 추가하세요.
— Claude Code 문서, https://code.claude.com/docs/en/sub-agents
다시 말해, 설명에 명확한 신호가 없으면 Claude는 기본적으로 서브에이전트를 **호출하지 않는** 경향이 있습니다. “use proactively” 또는 “use immediately after writing code”를 추가하면 활성화 빈도가 크게 높아집니다.
### 좋은 설명은 다음과 같습니다
```yaml
description: |
코드 품질, 보안,
유지 관리성을 적극적으로 검토하는 코드 리뷰 전문가입니다. 코드를 작성하거나
수정한 직후 사용하세요. 심각도와 수정 권장 사항이 포함된
우선순위별 문제 목록을 반환합니다.
문서 변경, README 수정 또는 커밋 메시지 재작성에는 호출하지 마세요. 이러한 작업은 doc-maintainer가 처리합니다.
```
여기서 효과적인 부분은 다음과 같습니다.
- “검토한다” + “반환한다”라는 동사가 과정이 아닌 구체적인 결과를 지정합니다.
- “적극적으로”와 “직후”가 명시적인 트리거입니다.
- “...에는 호출하지 마세요”가 비슷한 서브에이전트와 충돌하는 상황을 막습니다.
- 설명은 영어로 작성하는 것이 표준입니다. Claude는 영어로 더 잘 대응합니다.
## 10분 만에 사용할 수 있는 서브에이전트 역할 5가지
핵심 요점
첫 서브에이전트를 처음부터 작성하지 않으려면 검증된 패턴을 사용하고 맞춤 설정하세요. 일반적인 작업을 다루는 역할 5가지를 정리했습니다. code-reviewer(변경 후 코드 검토), security-auditor(취약점과 유출 정보 탐지), research-agent(8개 이상 출처에 대한 심층 조사), doc-maintainer(문서를 코드와 동기화), refactor-agent(git worktree를 이용한 안전한 리팩터링)입니다. 각 역할에는 복사해서 조정할 수 있는 준비된 템플릿이 포함되어 있습니다.
아래의 각 역할은 `.claude/agents/.md` 파일 하나로 구성됩니다. 파일을 만든 뒤 Claude Code를 다시 시작하고 `/agents`를 열어 새 에이전트가 목록에 나타나는지 확인하세요. 그런 다음 `@agent-name`으로 호출할 수 있습니다.
### 1. code-reviewer — 변경할 때마다 코드 검토
Anthropic 문서의 공식 예시를 업무 프로세스에 맞게 수정한 것입니다.
```markdown
---
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
model: inherit
color: blue
---
당신은 높은 코드 품질 기준을 보장하는 시니어 코드 리뷰어입니다.
호출되면:
1. 메인 세션이 준 diff와 변경 파일 목록을 읽고 없으면 요청합니다.
2. Read, Grep, Glob으로 관련 파일을 살펴봅니다.
3. 파일 수정이나 셸 명령 없이 지적을 반환합니다.
검토 체크리스트:
- 코드가 명확하고 읽기 쉬움
- 함수와 변수 이름이 적절함
- 중복 코드가 없음
- 오류 처리가 적절함
- 비밀 정보나 API 키가 노출되지 않음
- 입력값 검증이 구현됨
- 테스트 커버리지가 충분함
- 성능 고려 사항을 처리함
우선순위별로 의견을 제시합니다.
- 치명적 문제(병합 전에 반드시 수정)
- 경고(수정해야 함)
- 제안(개선 검토)
형식: 각 문제마다 파일:줄 + 문제가 되는 이유를 설명하는 문장 1개 + 구체적인 수정 방법을 씁니다.
```
핵심은 `tools: Read, Grep, Glob`입니다. 파일 읽기·검색만 주고 Bash, Write, Edit은 주지 않습니다. 메인 세션이 diff를 준비해 전달합니다. git diff만 실행하라는 지침만으로 완전히 허용된 Bash를 제한할 수는 없습니다.
### 2. security-auditor — 취약점과 유출 정보 찾기
보안 감사자는 깊은 추론을 위한 opus와 같은 Read, Grep, Glob 제한을 사용합니다. 에이전트 메모리는 쓰기 능력도 부여하므로 읽기 전용 템플릿에서는 지속 메모리를 제외합니다.
```markdown
---
name: security-auditor
description: |
Security audit specialist. Use proactively to find OWASP Top 10
vulnerabilities, exposed secrets, injection risks, broken auth.
Run before any deploy or merge to main.
tools: Read, Grep, Glob
model: opus
color: red
---
당신은 보안 감사자입니다. 스타일 문제가 아니라 악용 가능한 취약점을 찾습니다.
감사 체크리스트:
- SQL / NoSQL 인젝션
- XSS (저장형, 반사형, DOM 기반)
- CSRF / SSRF 위험
- 하드코딩된 비밀 정보(API 키, 토큰, 비밀번호)
- 취약한 인증 / 세션 관리
- 안전하지 않은 역직렬화
- 입력값 검증 누락
- 경로 순회
- 오픈 리디렉션
- 안전하지 않은 직접 객체 참조(IDOR)
발견 사항마다 다음을 작성합니다.
- 심각도: Critical / High / Medium / Low
- 파일:줄
- 1–2문장으로 설명한 공격 시나리오
- 코드 예시가 포함된 수정 권고
린터나 스타일 관련 사소한 내용은 건너뜁니다. 악용 가능한 문제만 보고합니다.
```
도구 측면에서는 읽기 전용이며, 취약점 연결고리 같은 복잡한 점검을 위해 `model: opus`를 사용합니다.
### 3. research-agent — 8개 이상 출처를 대상으로 한 심층 조사
이 패턴은 Anthropic이 다중 에이전트 조사 시스템을 다룬 글에서 직접 설명합니다. 핵심은 명확한 출력 형식을 지정하고 원시 결과를 쏟아내지 못하게 하는 것입니다.
```markdown
---
name: research-agent
description: |
Deep web research specialist. Use proactively for fact-finding,
competitive analysis, gathering external documentation, comparing
approaches across multiple sources.
tools: WebFetch, WebSearch, Read, Write
model: sonnet
maxTurns: 30
color: purple
---
당신은 조사 분석가입니다. 목표는 원시 검색 결과가 아닌 종합 보고서입니다.
절차:
1. 질문을 하위 검색어 3–5개로 나눕니다
2. 각 하위 검색어를 WebSearch로 검색하고 검색어마다 상위 출처 3–5개를 가져옵니다
3. 최소 2개의 독립 출처를 통해 주장을 교차 검증합니다
4. SEO 팜과 집계 사이트의 콘텐츠는 제외하고 1차 출처를 우선합니다
5. 구체적인 주장은 URL을 표시하고 원문 그대로 인용합니다
6. 다음 형식으로 반환합니다: TL;DR (항목 3개) + 조사 결과 + 출처 (최소 8개 도메인)
피해야 할 안티패턴:
- 하나의 출처만으로 사실을 인용하지 않습니다
- 의역한 인용을 원문 그대로인 것처럼 제시하지 않습니다
- 검색 결과 원문을 부모에게 그대로 반환하지 않습니다
- 군더더기 서론이나 결론을 넣지 않습니다(“도움이 되었으면 합니다”)
```
`maxTurns: 30`은 조사가 끝없이 반복되지 않도록 제한하는 장치입니다. Anthropic은 다중 에이전트 시스템에서 이 수치를 보고합니다.
Claude Opus 4를 리드 에이전트로, Claude Sonnet 4를 서브에이전트로 사용한 다중 에이전트 시스템은 단일 Claude Opus 4보다 90.2% 더 우수한 성능을 보였습니다.
— Anthropic Engineering, https://www.anthropic.com/engineering/multi-agent-research-system
90퍼센트는 조사 벤치마크 작업을 기준으로 합니다. 실제 비즈니스 작업에서 향상 폭은 더 작지만, 전반적인 규모는 비슷합니다.
### 4. doc-maintainer — 코드와 문서의 동기화 유지
이 역할은 “비용 관리”의 전형적인 예인 `model: haiku`를 사용합니다. 문서 작업에는 Opus가 필요하지 않습니다. Haiku는 3분의 1 가격으로 작업을 처리합니다.
```markdown
---
name: doc-maintainer
description: |
Documentation sync specialist. Use after merging features to update
README, API docs, CHANGELOG. Reads recent commits, identifies
undocumented changes, updates docs proactively.
tools: Read, Write, Edit, Glob, Grep, Bash
model: haiku
memory: project
color: green
---
코드와 문서의 동기화를 유지합니다.
호출되면:
1. 최근 변경 사항을 확인하려고 `git log --since="last release"`를 실행합니다
2. README.md, docs/, CHANGELOG.md를 읽습니다
3. 문서화되지 않은 새 기능, 문서에는 남아 있는 삭제된 API, 버전 불일치를 찾습니다
출력:
- 업데이트한 파일(Edit을 사용하고 Write는 사용하지 않아 기존 구조를 보존합니다)
- Keep-A-Changelog 형식의 CHANGELOG.md 항목
- 실제 변경 내용 목록(의역이 아닌 실제 diff 요약)
스타일 규칙:
- 능동태, 현재 시제
- 코드 예시는 복사하여 붙여 넣을 수 있어야 함
- 마케팅 표현 금지(“강력한”, “견고한”, “매끄러운”)
- 군더더기 금지(“이 가이드가 도움이 될 것입니다...”)
```
### 5. refactor-agent — worktree를 통한 안전한 리팩터링
이 역할은 `isolation: worktree`를 사용합니다. 서브에이전트가 저장소의 별도 복사본에서 작업하므로, 결과가 괜찮을 때만 병합합니다.
```markdown
---
name: refactor-agent
description: |
Safe refactor specialist. Use for renames, extracts, inlines that
shouldn't touch your working copy until reviewed. Runs in a
temporary git worktree.
tools: Read, Edit, Write, Bash, Grep, Glob
model: sonnet
isolation: worktree
permissionMode: acceptEdits
color: yellow
---
동작을 바꾸지 않고 코드를 리팩터링합니다.
엄격한 규칙:
1. 리팩터링 전과 후에 테스트가 통과해야 합니다.
리팩터링 전에 테스트가 실패하면 중단하고 보고합니다.
2. 커밋마다 원자적 리팩터링 하나만 수행합니다(추출, 이름 변경, 인라인화).
3. 명시적인 지시 없이는 공개 API를 변경하지 않습니다.
4. 리팩터링한 구현을 직접 테스트하는 경우가 아니면 테스트를 수정하지 않습니다.
절차:
- 테스트 스위트 실행 -> 기준 결과 확인
- 원자적 리팩터링 수행
- 테스트 스위트 실행 -> 확인
- conventional 형식의 메시지로 커밋: refactor(scope): what
반환 내용: 변경 사항 요약 + 사용자가 diff를 확인하고 병합할 수 있는 worktree 경로.
```
이 역할을 쓰면 리팩터링에서 가장 골치 아픈 문제, 즉 “망가뜨렸는데 어떻게 되돌려야 할지 모르겠다”가 사라집니다. 원본 복사본은 그대로 유지되고 서브에이전트는 격리된 worktree에서 작업합니다.
준비된 서브에이전트를 복사하는 데 그치지 않고 Claude를 안정적으로 만들어 줄 **조합**을 구성하고 싶으신가요? 서브에이전트는 **AI 클론**의 일부입니다. Claude에게 내 논리에 따라 작동하는 전문 팀을 제공하는 방법입니다. 이 방법론의 세 가지 기둥은 **AI 클론**(Skills + 서브에이전트) + **[Second Brain](https://ailoot.ai/blog/ko/claude-code-second-brain/)** + **컨텍스트 엔지니어링**입니다. 이 조합은 Claude를 추측하는 어시스턴트에서 당신의 논리에 따라 생각하는 도구로 바꿔 줍니다.
## 서브에이전트 5개를 병렬 실행하기: 오케스트레이터 + 작업자
핵심 요점
서브에이전트의 가장 큰 강점은 병렬 실행입니다. 메인 채팅 하나가 계획을 맡고, 전문 서브에이전트 다섯 개(또는 열 개)가 각자의 컨텍스트에서 서로 다른 단계를 동시에 처리합니다. 메인 채팅은 결과를 모아 점검합니다. 순차 작업보다 3–5배 빨라지고, 메인 대화가 로그와 중간 분석에 파묻히는 “컨텍스트 오염”도 없어집니다.
병렬 오케스트레이션은 “지휘자 + 오케스트라” 구조입니다. 지휘자는 계획을 맡고, 악보를 쓰지 않으며, 연주를 점검합니다. 누군가 음을 틀리면 대신 연주를 끝내는 것이 아니라 다시 연주해 달라고 요청합니다.
기업가에게는 새 고객을 위한 전략을 준비하는 마케팅 대행사가 더 가까운 비유입니다. 분석가 한 명은 SWOT 분석을 하고, 다른 한 명은 경쟁사를 분석하며, 세 번째는 고객 프로필을 작성합니다. 선임 분석가는 예산에 맞지 않는 가설을 걸러내고 프로젝트 매니저는 최종 프레젠테이션을 구성합니다. Claude Code에서 이 파이프라인은 한 문장으로 시작하며, 비평가가 사후에 추가되는 대신 처음부터 과정에 포함됩니다.
### 최소 오케스트레이션 프롬프트
메인 채팅에 한 문장만 입력하면 충분합니다.
```
서브에이전트 다섯 개를 병렬로 실행해 줘. 서로 다른 출처를 조사하는 research-agent 세 개
(Anthropic 문서, GitHub 저장소, AI 블로거), 약한 결론을 걸러내는 critic-agent 하나,
최종 문서를 작성하는 summary-agent 하나를 실행해.
맥락: X에 관한 가이드를 쓰고 있어. 목표 분량: 출처를 포함해 2,000단어.
시작하기 전에 각 에이전트가 CLAUDE.md를 읽어.
```
그러면 Claude가 다섯 에이전트에게 작업을 위임합니다. 각 에이전트는 자체 컨텍스트에서 작업합니다. 조사 에이전트는 각자 지정된 출처를 사용하고, 비평가는 결과를 걸러내며, 요약 에이전트는 내용을 구성합니다. 최종 요약만 메인 채팅에 돌아옵니다.
### 병렬 처리가 효과적인 경우
항상 효과적인 것은 아닙니다. 다음 조건을 만족할 때만 병렬 실행이 의미 있습니다.
1. 작업이 **서로 독립적**이어야 합니다. research-agent #2가 research-agent #1의 결과를 기다린다면 병렬 처리는 이루어지지 않습니다. 사실상 순차적으로 작업하게 됩니다.
2. 작업에 **시간이 오래 걸려야** 합니다. “줄 끝 공백 제거”를 병렬 처리하는 건 의미가 없습니다. 서브에이전트 실행에 드는 오버헤드가 이득을 없앱니다.
3. 사용 가능한 **한도가 충분해야** 합니다. 자세한 내용은 아래 별도 절에서 다룹니다. 병렬 서브에이전트는 토큰을 빠르게 소모합니다.
### Anthropic의 Multi-Agent v2: 한 단계 더 나아가기
2026년 5월, Anthropic은 병렬 서브에이전트를 실행하는 기존 방식과 세 가지 중요한 차이가 있는 Multi-Agent Orchestration v2를 출시했습니다. 자세한 내용은 다음 절에서 다룹니다.
## Multi-Agent v2의 새로운 기능: Orchestration, Outcomes, Dreaming
핵심 요점
2026년 5월 6일, 샌프란시스코에서 열린 Code with Claude 컨퍼런스에서 Anthropic은 Managed Agents v2의 기능 세 가지를 발표했습니다. 모두 공개 베타입니다. Multi-Agent Orchestration은 리드 에이전트가 작업을 나누고 공유 파일 시스템을 사용해 전문가들에게 병렬로 위임할 수 있게 해 줍니다. Outcomes에서는 성공 기준을 작성하면 별도의 평가 에이전트가 결과를 확인합니다. Dreaming은 REM 수면과 비슷합니다. 예약된 프로세스가 과거 세션을 읽고 패턴을 찾아 에이전트 메모리를 업데이트합니다.
### Multi-Agent Orchestration: 공유 파일 시스템 + 진행 중 확인
Anthropic은 이 기능을 다음과 같이 설명합니다.
작업이 단일 에이전트가 처리하기에 너무 많을 때, 다중 에이전트 오케스트레이션을 사용하면 리드 에이전트가 작업을 여러 부분으로 나누고 각자 모델, 프롬프트, 도구를 가진 전문가에게 맡길 수 있습니다. 전문 에이전트는 공유 파일 시스템에서 병렬로 작업하고 결과를 리드 에이전트의 공유 컨텍스트에 전달합니다.
— Anthropic - Claude Managed Agents의 새로운 기능, https://claude.com/blog/new-in-claude-managed-agents
기존 서브에이전트와의 핵심 차이는 **공유 파일 시스템**입니다. 이전에는 각 서브에이전트가 완전히 격리되어 작업했고, 결과 요약을 반환하는 방법으로만 정보를 주고받았습니다. 이제 전문 에이전트는 공유 폴더에 쓸 수 있고, 리드 에이전트는 작업이 끝난 뒤뿐 아니라 진행 중에도 결과를 읽습니다. 이로써 “모두 하루 종일 일했는데 마지막에 두 사람이 서로 양립할 수 없는 접근법을 사용한 것으로 드러나는” 문제를 해결합니다.
두 번째는 **작업 중 확인**입니다. 리드 에이전트는 멈춰서 어느 전문 에이전트에게든 “진행 상황이 어때?”라고 물은 뒤 전체 계획을 조정할 수 있습니다. 실제 팀 관리자가 일하는 방식과 비슷합니다.
### Outcomes: 단계별 지침 대신 평가 기준
Outcomes에서는 성공 기준을 작성하고 에이전트가 이를 충족할 방법을 찾습니다. 별도의 평가자가 자체 컨텍스트에서 결과를 확인하므로 메인 에이전트의 추론에 “오염되지” 않습니다.
이 방식은 표준 프롬프트 루프와 비교해 작업 해결 성공률을 최대 10포인트 향상시켰으며, 가장 어려운 작업에서 효과가 가장 컸습니다.
— Anthropic - Claude Managed Agents의 새로운 기능, https://claude.com/blog/new-in-claude-managed-agents
어려운 작업에서 10퍼센트 향상은 큰 차이입니다. 특히 “1~7단계를 따라라”라고 하는 대신 “이 품질 기준을 충족하는 긴 기사를 작성하라”라고 작업을 정의할 때 그렇습니다.
### Dreaming: 세션 사이에 경험을 쌓는 에이전트
이 기능은 개념적으로 가장 새롭습니다. 에이전트가 이전 세션을 살펴보고 성공과 실수에서 패턴을 찾아 메모리 저장소를 업데이트합니다. 변경을 적용하기 전에 수동으로 검토하도록 설정할 수도 있고, 에이전트가 메모리를 직접 수정하도록 할 수도 있습니다.
Anthropic에 따르면 법률 기술 기업 Harvey는 Dreaming을 구현한 뒤 법률 문서 작성 작업의 성공률이 약 6배 증가했습니다. 이는 데모만이 아니라 이미 프로덕션에서 작동하고 있습니다.
### 프로그래밍을 하지 않는 기업가에게 의미하는 점
Multi-Agent Orchestration은 현재 Claude Code CLI에서 직접 사용할 수 없고 Claude Agent SDK를 통해 제공됩니다. 하지만 방향은 분명합니다. “N개의 서브에이전트를 직접 실행”하는 방식에서 “작업을 설명하면 리드 에이전트가 누구에게 어떻게 위임할지 결정”하는 방식으로 오케스트레이션이 바뀌고 있습니다. 서브에이전트를 막 시작했다면 아직 v2는 걱정하지 마세요. “메인 채팅 하나 + 역할이 다른 서브에이전트 3–5개”라는 고전적인 패턴을 익히면 3–6개월 후 Managed Agents로 자연스럽게 옮겨 갈 수 있습니다.
## 서브에이전트를 제대로 작동하지 않게 만드는 7가지 실수
핵심 요점
가장 흔한 서브에이전트 문제는 Claude의 버그가 아니라 서브에이전트 자체의 설계 실수입니다. 트리거 문구가 없는 설명, Skill에 적합한 작업에 서브에이전트를 사용하기, “멋져 보인다는 이유로” 에이전트 60개를 병렬 실행하기, 모든 도구를 모든 에이전트에 제공하기, 명시적인 출력 형식이 없기, 모호한 요청, 작업이 아니라 역할을 기준으로 한 아키텍처가 이에 해당합니다. 이런 실수는 각각 활성화 또는 서브에이전트 결과를 망가뜨립니다.
### 실수 1. “X 도우미”라는 설명은 트리거가 되지 않습니다
증상: 서브에이전트를 작성하고 구조를 확인했으며 모든 것이 유효하지만 Claude가 사용자 요청에 이를 호출하지 않습니다. 원인은 거의 항상 같습니다. 설명이 “코드 검토 도우미”처럼 추상적입니다. 해결 방법은 실제 사용자가 자주 하는 표현 3–5개를 따옴표로 묶어 설명에 직접 추가하고 “use proactively” / “use immediately after”를 넣는 것입니다.
### 실수 2. Skill이 필요한 곳에 서브에이전트 만들기
서브에이전트는 자체 컨텍스트를 만들고 시스템 프롬프트를 로드하며 토큰을 더 사용하므로 Skill보다 비용이 많이 듭니다. 작업이 짧고 메인 컨텍스트를 소모하지 않으며 한 번에 처리할 수 있다면 서브에이전트가 아니라 Skill이어야 합니다. 안티패턴의 예로 JSON 스키마를 20개 규칙에 따라 확인하는 `format-validator` 서브에이전트가 있습니다. 이는 Skill이어야 합니다. 모델 하나로 처리할 수 있고, 격리할 필요도 없으며, 컨텍스트를 추가로 로드하지 않아도 됩니다.
### 실수 3. 처음부터 “병렬 에이전트 60개” 실행하기
가장 널리 퍼진 착각입니다. “에이전트 1,500개를 돌리고 있다”는 트윗을 보고 “나도 그래야겠다”고 생각합니다. 실제로 에이전트 60개는 한 시간 만에 Pro 플랜 한도를 소진하고, 서로 충돌하는 결과를 쏟아내며, 하루가 끝날 때까지 완성된 결과물을 하나도 만들지 못합니다.
Medium의 한 실무자는 이렇게 설명합니다.
해결 방법은 작업 하나에 서브에이전트 하나로 시작하는 것입니다. 익숙해지면 역할이 다른 서브에이전트를 하나 더 추가하세요. 두 에이전트를 오케스트레이션하는 방법을 익힌 뒤에는 3–5명으로 구성된 팀으로 확장하세요. “어제 Claude Code를 설치했다”에서 “오늘 병렬로 20개를 실행한다”로 건너뛰면 코드는 망가지고 한도는 소진될 수밖에 없습니다.
### 실수 4. 모든 에이전트에 모든 도구 제공하기
코드 리뷰어가 Bash, Write, WebFetch에 접근할 수 있다면 심각한 보안 및 비용 문제가 됩니다. 리뷰어에게 파일을 쓸 권한은 물론 인터넷에 접근할 권한도 줄 필요가 없습니다.
해결 방법은 `tools`를 엄격히 제한하는 것입니다. 코드 리뷰어에게는 `Read, Grep, Glob`만 제공하세요. 보안 감사자에게도 같은 읽기·검색 도구와 메인 세션의 diff를 주세요. Bash는 셸 능력을 주며 git diff만으로 자동 제한되지 않습니다. 조사 에이전트에게는 `WebFetch, WebSearch, Read, Write`를 제공하세요. 특정 작업에 필요한 범위를 넘어서는 권한을 서브에이전트에 주지 마세요.
### 실수 5. 서브에이전트가 원시 결과를 메인 컨텍스트에 쏟아붓기
조사 에이전트가 메인 채팅에 “찾은 페이지 30개를 전부 보여 줄게요. 알아서 판단하세요”라고 답하면 서브에이전트의 가장 큰 장점인 잡음 격리를 잃게 됩니다. 해결 방법은 서브에이전트의 시스템 프롬프트에 출력 형식을 명시하는 것입니다. “반드시 이것만 반환: 3개 항목의 TL;DR + 출처 목록 5개. 코드 덤프 금지, 원시 검색 결과 금지.” 형식은 **엄격**해야 합니다. 서브에이전트가 “에세이로 바꾸는” 재량을 가져서는 안 됩니다.
### 실수 6. 모호한 호출: 불명확한 위임 요청
서브에이전트는 메인 대화의 기록을 **볼 수 없습니다**. 깨끗한 컨텍스트 + CLAUDE.md + 사용자가 명시적으로 작성한 내용만 가지고 시작합니다. “인증을 수정해”라고 쓰면 서브에이전트가 내용을 지어낼 수 있습니다. 대신 이렇게 쓰세요. “로그인에 성공한 뒤 사용자가 /dashboard가 아니라 /login으로 리디렉션되는 OAuth 리디렉션 루프를 수정해. 파일: src/lib/auth.ts.”
명확한 원칙은 다음과 같습니다. 위임할 때는 프로젝트에 막 합류한 새 계약직 직원에게 제공할 만큼 충분한 컨텍스트를 서브에이전트에 전달하세요.
### 실수 7. 작업 기준이 아니라 역할 기준으로 에이전트 만들기
“frontend-developer, backend-developer, qa-engineer를 만들고 팀으로 일하게 하자”는 방식은 솔깃합니다. 하지만 효과가 없습니다. 각 “역할”은 프로젝트 전체에 대한 컨텍스트를 놓치고, 서로 볼 수 없으므로 세부 사항에 합의할 수 없습니다.
해결 방법은 명확한 결과가 있는 반복적인 **작업**을 서브에이전트에 맡기는 것입니다. **역할**이 아닙니다. “frontend-developer”가 아니라 “explore-ui-tree”, “refactor-component”, “audit-accessibility”처럼 만드세요. 작업 기준 서브에이전트는 각각 하나의 구체적인 일을 하고 하나의 구체적인 결과를 반환합니다.
## 병렬 서브에이전트의 비용은 얼마이며 언제 효과가 있나요?
핵심 요점
병렬 서브에이전트는 순차 작업보다 토큰을 3–5배 빠르게 소모합니다. Pro 플랜(월 \$20)에서 병렬 서브에이전트 5개를 실행하면 한 시간 만에 사용 한도를 소진하게 됩니다. Max 5x(\$100/월)는 정기적으로 병렬 작업을 할 때 현실적인 최소 요금제입니다. 서브에이전트는 집중 작업이 최소 10분 필요한 경우에 효과가 있습니다. README의 오타 하나를 고치려고 서브에이전트를 실행하면 아끼는 시간보다 더 많은 토큰을 사용합니다.
| 구성 | 활발하게 작업할 때 일일 사용량 |
|----|----|
| Claude Code 세션 1개 | ~\$13 |
| 병렬 서브에이전트 3개 | ~\$30-40 |
| 병렬 서브에이전트 5–10개 | \$50-130 |
| 에이전트 30개(개발자 10명 × 서브에이전트 3개) | \$300-400 |
복잡한 작업에 병렬 서브에이전트 5개를 실행하면 한 시간 안에 Pro 플랜 한도가 소진됩니다. Max 5x($100)는 정기적으로 병렬 작업을 할 때 현실적인 최소 요금제입니다. 팀과 Enterprise에서는 비용 문제를 도구 예산 수준에서 이미 처리합니다.
Claude Code에서 토큰을 절약하는 방법은 [한도에 관한 별도 가이드](https://ailoot.ai/blog/ko/claude-code-token-limits-saving/)를 참고하세요. 서브에이전트의 핵심 원칙은 집중 작업이 **최소 10분** 필요한 경우에 효과가 있다는 것입니다. 작업 시간이 더 짧다면 서브에이전트를 만들지 말고 메인 채팅이나 Skill로 처리하세요.
## 서브에이전트를 AI 클론과 Second Brain에 어떻게 통합하나요?
핵심 요점
서브에이전트는 Claude Code 방법론의 네 번째 단계입니다. 논리적인 순서는 먼저 [CLAUDE.md](https://ailoot.ai/blog/ko/claude-md-template/)(영구 컨텍스트), 그다음 [Skills](https://ailoot.ai/blog/ko/claude-code-skills-library/)(준비된 방법론), 다음으로 [Second Brain](https://ailoot.ai/blog/ko/claude-code-second-brain/)(프로젝트 지식 구조), 마지막으로 서브에이전트(전문 작업자)입니다. 이 순서를 거꾸로 하면 결과 없이 기대감만 커집니다. CLAUDE.md가 없는 서브에이전트는 내용을 지어내고, Skills가 없으면 매번 같은 일을 처음부터 반복하며, 지식 구조가 없으면 평범한 답을 내놓습니다.
첫 전문 서브에이전트를 만들기 전에 프로젝트에 다음 세 가지가 있어야 합니다.
1. **올바른 [CLAUDE.md](https://ailoot.ai/blog/ko/claude-md-template/).** 서브에이전트는 시작하기 전에 CLAUDE.md를 읽습니다. 이것은 서브에이전트의 “고용 계약서”입니다. 파일이 없으면 프로젝트 맥락, 제한 사항, 어조를 알지 못하고 내용을 지어냅니다.
2. **기본 [Skills](https://ailoot.ai/blog/ko/claude-code-skills-library/).** Skill은 패키지화된 방법론입니다. 서브에이전트는 한 번에 모든 Skill을 불러오는 것이 아니라 필요한 Skill만 로드합니다. Skills가 없으면 매번 같은 일을 처음부터 반복합니다.
3. **[Second Brain](https://ailoot.ai/blog/ko/claude-code-second-brain/): 지식 구조.** `business/` 폴더(또는 해당 분야에서 이에 상응하는 폴더)는 모든 서브에이전트가 참조하는 라이브러리입니다. 이 구조가 없으면 서브에이전트는 다른 누구의 답과도 다를 바 없는 평범한 ChatGPT 답변을 제공합니다.
순서를 거꾸로 하면 결과 없이 기대감만 커집니다. `business/` 폴더가 비어 있는데 “병렬 서브에이전트 60개를 운영 중”이라고 해 봐야, 같은 접근법을 사용하는 평범한 ChatGPT 세션 60개가 생길 뿐입니다.
완전한 조합인 **AI 클론 + Second Brain + 컨텍스트 엔지니어링**은 Claude를 일관되게 만드는 **세 가지 기둥**입니다. 서브에이전트는 AI 클론의 일부로, Claude에게 당신의 논리에 따라 작동하는 전문 팀을 제공하는 방법입니다.
### 출처
- [사용자 지정 서브에이전트 만들기 - Claude Code 문서](https://code.claude.com/docs/en/sub-agents)
- [Claude Code가 더 자율적으로 작동하도록 하기 - Anthropic News](https://www.anthropic.com/news/enabling-claude-code-to-work-more-autonomously)
- [다중 에이전트 조사 시스템을 구축한 방법 - Anthropic Engineering](https://www.anthropic.com/engineering/multi-agent-research-system)
- [Agent Skills로 실제 환경에 에이전트 투입하기 - Anthropic Engineering](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
- [Claude Managed Agents의 새로운 기능(Multi-Agent v2, Outcomes, Dreaming) - Anthropic 블로그](https://claude.com/blog/new-in-claude-managed-agents)
가장 빠르게 시작하는 방법은 위 첫 번째 예시에서 `code-reviewer`를 복사해 `.claude/agents/code-reviewer.md`에 넣고, Claude Code를 다시 시작한 뒤 다음 커밋에서 `@agent-code-reviewer`를 호출하는 것입니다. 5분이면 서브에이전트가 필요한지 아니면 메인 채팅으로 충분한지 알 수 있습니다.
[ailoot.ai](https://ailoot.ai/)에서 Ailoot을 계속 살펴볼 수 있습니다.
## Claude Code 서브에이전트: 구조, 역할 5가지, 오케스트레이션: 자주 묻는 질문
### 프롬프트에 적으면 리뷰어의 Bash가 git diff로만 제한되나요?
아닙니다. Bash 허용은 셸 능력을 주며 프롬프트는 명령 허용 목록이 아닙니다. 읽기 전용 템플릿은 Bash·Write·Edit을 빼고 메인 세션에서 diff를 받습니다.
### Bash 없이 최근 변경을 어떻게 검토하나요?
메인 세션이 위임할 때 diff와 변경 파일 목록을 제공합니다. 리뷰어는 Read, Grep, Glob으로 파일을 읽고 검색해 수정 없이 지적을 반환합니다.
## Ailoot · 회사와 그 프로젝트 포트폴리오
Ailoot는 축적된 운영 경험, 폭넓은 고객 기반, 안정적인 서비스, 지속적인 KPI 관리를 바탕으로 합니다.
회사와 그 프로젝트 포트폴리오: 수백만 고객, 매월 수십억 규모의 매출.
Ailoot는 이러한 운영 경험을 고객의 제품, 에이전트, 애플리케이션, 자동화에서 AI 기능을 이용할 수 있는 API 접근에 활용합니다.