Claude Code 서브에이전트 커스텀 만들기: 내 AI팀 구성하는 단계별 가이드

저도 처음엔 Claude Code를 그냥 "채팅으로 코드 짜는 도구" 정도로만 쓰고 있었어요. 그러다 서브에이전트를 알게 됐는데, 솔직히 말하면 이게 진짜 게임체인저였습니다. 코드 리뷰, 보안 감사, 테스트 작성을 각각 전문화된 에이전트에게 맡기면 — 메인 대화창이 로그로 도배되는 일도 없고, 작업마다 딱 필요한 권한만 주니까 훨씬 안전하거든요.

Claude Code 서브에이전트가 뭔지, 어떻게 만드는지, 어떤 실수를 피해야 하는지 순서대로 정리해봤습니다.

.claude/agents/ 폴더 구조 — 전문화된 AI 팀 구성

---

 

서브에이전트가 뭔지부터 짚고 가면

서브에이전트는 .claude/agents/ 폴더에 마크다운 파일로 정의하는 전문화된 AI 어시스턴트입니다. 핵심은 독립된 컨텍스트 윈도우예요. 메인 대화에서 분리되어 자기 공간에서 작업하고, 결과 요약만 돌려보내죠.

Claude 공식 문서에는 이렇게 나와 있어요.

"Use one when a side task would flood your main conversation with search results, logs, or file contents you won't reference again: the subagent does that work in its own context and returns only the summary."

파일 100개를 뒤지는 작업을 메인 세션에서 하면 컨텍스트가 금방 터집니다. 서브에이전트에 맡기면 그 작업은 별도 공간에서 돌고, 메인 세션엔 깔끔한 요약만 남아요. 에이전트마다 다른 Claude 모델(Haiku, Sonnet, Opus)을 지정할 수 있어서 비용 최적화도 됩니다.

기존 Task 툴과의 차이가 궁금하실 수 있어요. Task 툴은 그때그때 임시 세션을 만들어 쓰는 방식인데, 서브에이전트는 고유한 정체성과 전문성을 미리 선언해두고 재사용합니다. "코드 리뷰가 필요하면 항상 이 에이전트에게" 같은 패턴이 가능해지는 거예요.

---

 

YAML frontmatter 구조 — 필수는 딱 두 개

파일 구조는 간단합니다. YAML frontmatter + 시스템 프롬프트 본문이 전부예요.

---
name: agent-identifier          # 필수: 소문자-하이픈 형식
description: |                  # 필수: Claude가 언제 이 에이전트를 쓸지 결정하는 근거
  When and why Claude should use this agent.
  "MUST BE USED for..." 패턴이 자동 위임에 효과적.
model: sonnet                   # 선택: sonnet | opus | haiku
tools: [Read, Edit, Bash]       # 선택: 허용 도구 목록 (생략 시 전체 허용)
disallowedTools: [Write]        # 선택: 명시적 차단 목록
permissionMode: default         # 선택: default | acceptEdits | dontAsk | bypassPermissions
maxTurns: 10                    # 선택: 최대 agentic 턴 수
background: false               # 선택: true면 항상 병렬 실행
---
시스템 프롬프트 본문

필수 필드는 name과 description 두 개뿐입니다. 나머지는 전부 선택이에요. 근데 tools 필드는 꼭 챙기는 걸 권장해요. 생략하면 모든 도구에 접근하게 돼서, 리뷰어가 실수로 파일을 수정하는 상황이 생길 수 있거든요.

description 필드가 생각보다 중요합니다. Claude는 이걸 읽고 "지금 이 작업에 어떤 에이전트를 불러야 하는지" 판단해요. "MUST BE USED for..." 패턴에 구체적인 키워드를 포함하면 자동 위임이 훨씬 잘 됩니다.

YAML frontmatter 구조 — 필수 2개 + 선택 필드 완전 해부

---

 

서브에이전트 만드는 두 가지 방법

방법 1: /agents 명령으로 GUI에서 만들기

Claude Code에서 /agents를 입력하면 Library 탭이 열립니다. "Create new agent"를 선택하고, 스코프(프로젝트 or 사용자), 역할과 목적을 설명하면 Claude가 description, name, 시스템 프롬프트를 자동으로 생성해줘요. 도구 목록과 모델을 검토한 뒤 저장하면 재시작 없이 바로 적용됩니다.

처음 만드는 분들한테는 이 방법이 제일 편해요.

방법 2: 직접 .md 파일 작성

.claude/agents/ 폴더에 .md 파일을 직접 만드는 방법입니다.

.claude/
└── agents/
    ├── code-reviewer.md
    ├── test-writer.md
    └── security-auditor.md

저장 위치에 따라 스코프가 달라져요.

위치	스코프	특징
.claude/agents/	프로젝트 전용	Git으로 팀 공유 가능
~/.claude/agents/	전체 개인 프로젝트	모든 세션에서 재사용

팀 프로젝트라면 .claude/agents/에 두고 Git에 포함시키는 게 좋습니다. 팀 전체가 동일한 에이전트를 쓸 수 있거든요.

---

 

실전 서브에이전트 예시 3가지

말로만 하면 감이 안 오죠. 바로 쓸 수 있는 예시입니다.

코드 리뷰어 (읽기 전용 — 가장 안전한 시작점)

---
name: code-reviewer
description: MUST BE USED for code review, PR review, security audit,
  and refactor suggestions on TypeScript/Next.js code. Read-only — never writes files.
tools: Read, Grep, Glob, Bash
model: sonnet
---

# Role
Senior code-reviewer specializing in TypeScript and Next.js.

# Context discovery
1. Read CLAUDE.md at repo root
2. Run: git diff main...HEAD
3. Read changed files and their imports

# Workflow
For each changed file: Correctness → Security → Performance → Maintainability

# Output format
## Critical (must fix before merge)
## Warnings (should fix)
## Suggestions (optional improvement)
## Verdict: MERGE_READY | NEEDS_WORK | BLOCKING

tools에 Write가 없는 게 포인트예요. 리뷰어가 파일을 직접 수정하는 일은 없어야 하니까요.

보안 감시자 (Opus 모델 사용)

---
name: security-auditor
description: Security-focused code reviewer. Use proactively after writing
  authentication, authorization, or data-handling code.
tools: Read, Grep, Glob
model: opus
---

Role: Senior application security engineer reviewing code for vulnerabilities before it ships.
Focus: SQL injection, XSS, authentication bypass, sensitive data exposure, dependency risks.
Output: severity-ranked findings with OWASP category and remediation steps.

미묘한 패턴 인식이 중요한 보안 감사에는 Opus 모델을 씁니다. 비용이 더 들지만, 여기서 Haiku를 쓰는 건 좀 아깝죠.

테스트 작성자

---
name: test-writer
description: Generates unit and integration tests for new or modified code.
tools: Read, Write, Edit, Bash, Glob
model: sonnet
---

Generate comprehensive tests covering happy paths, edge cases, and error conditions.
Follow existing test patterns in the project. Run tests after writing to verify they pass.

메인 세션에서 3개 에이전트 동시 병렬 실행 흐름도

---

 

병렬 실행 — 여러 에이전트를 동시에 돌리는 방법

메인 오케스트레이터가 Task 툴을 여러 번 연속 호출하면 병렬 실행이 됩니다. 각 에이전트는 독립된 컨텍스트에서 동시에 작동하고, 모두 완료되면 결과를 통합해요.

메인 세션
  ├── Task → code-reviewer (독립 컨텍스트, 병렬)
  ├── Task → security-auditor (독립 컨텍스트, 병렬)
  └── Task → test-writer (독립 컨텍스트, 병렬)
       ↓ (모두 완료 후)
  결과 통합 → 메인 세션

실용적인 상한선은 3~5개 동시 실행입니다. 그 이상 넘어가면 결과 병합에 드는 시간이 병렬 실행의 이득을 상쇄하기 시작해요.

참고로 HAMY.xyz 사례에서는 단일 /code-review 명령 하나로 9개 에이전트를 동시에 실행합니다 — test-runner, linter, code-reviewer, security-reviewer, quality-reviewer, test-quality-reviewer, performance-reviewer, dependency-reviewer, simplicity-reviewer. 제안의 약 75%가 실용적이라고 저자는 평가하더라고요.

background: true 필드를 frontmatter에 지정하면 해당 에이전트는 항상 백그라운드로 실행됩니다. 린터처럼 항상 병렬로 돌아야 하는 에이전트에 유용해요.

---

 

서브에이전트 vs Hooks vs MCP — 뭘 써야 하나

헷갈리기 쉬운 부분인데, 역할 차이가 명확합니다.

구분	핵심 역할	언제 쓰나
서브에이전트	격리된 작업 위임	코드 탐색, 보안 감시, 조사 작업
Hooks	이벤트 기반 자동화 강제	파일 편집 후 포맷팅, 커밋 전 린트
MCP	외부 시스템 연결	GitHub API, Jira, DB, Sentry 등

서브에이전트의 실행은 모델 판단에 의존합니다. Hooks는 달라요 — "파일 편집 후 항상 포맷팅 실행"처럼 모델 판단 없이 강제로 실행됩니다. "이걸 AI가 알아서 판단해도 되는가"가 선택 기준이에요. 강제로 실행되어야 하면 Hooks, 유연하게 맡겨도 되면 서브에이전트.

---

 

자주 하는 실수 5가지

1. 서브에이전트가 자동으로 안 불린다

description 필드가 모호한 게 원인입니다. "MUST BE USED for code review on TypeScript..." 처럼 트리거 키워드를 구체적으로 써야 해요. 아니면 그냥 "Use the code-reviewer agent to audit this module"처럼 명시적으로 언급하는 것도 방법입니다.

2. 서브에이전트가 다른 서브에이전트를 호출하려 한다

서브에이전트는 중첩이 안 됩니다. 1단계까지만 허용돼요. 복잡한 체인이 필요하면 메인 세션에서 순차적으로 조율해야 합니다.

3. 토큰 비용이 예상보다 훨씬 많다

N개 에이전트를 병렬 실행하면 토큰 비용이 약 N배 증가합니다. Anthropic 문서 기준으로 서브에이전트 집약 워크플로우는 단일 세션 대비 최대 7배까지 올라가요. 간단한 작업은 그냥 단일 세션으로, 반복·단순 작업에는 Haiku 모델을 지정하는 식으로 조절하세요.

4. 컨텍스트가 60~70%를 넘어가면 성능이 떨어진다

흔히 "agent dumb zone"이라고 부르는 현상입니다. 컨텍스트 사용량이 60~70%를 넘으면 눈에 띄게 성능이 저하돼요. 50% 시점에서 수동으로 /compact를 실행하는 게 안전합니다.

5. 리뷰어가 항상 문제를 찾아낸다

"문제를 찾아라"고 프롬프트하면 실제로 없는 문제도 만들어냅니다. "정확성이나 요구사항에 영향을 미치는 문제만 플래그하라"처럼 범위를 제한해야 해요.

---

 

처음 시작한다면 이 순서로

1. 코드 리뷰어부터 — 읽기 전용이라 가장 위험이 없습니다
2. 테스트 작성자 추가 — 리뷰어가 익숙해지면 바로 이어서
3. 리뷰어 → 테스트 작성자 순차 조율 패턴 구현
4. 팀이 익숙해지면 보안 감시자, 문서화 에이전트 추가

1주일이면 실제로 효과를 평가하기에 충분합니다.

GitHub의 VoltAgent/awesome-claude-code-subagents 저장소에 100개 이상의 전문화 서브에이전트 예시가 공개돼 있어요. 처음 시작할 때 여기서 하나 가져다 쓰고 입맛에 맞게 수정하는 게 제일 빠릅니다.

서브에이전트 도입 추천 순서 로드맵 — 1주일이면 효과 검증 가능

직접 .claude/agents/ 폴더에 파일 하나 만들어서 써보세요. name과 description 두 줄만 있어도 일단 동작합니다. 정교하게 다듬는 건 써보면서 해도 늦지 않아요.