Custom Subagents

특정 역할에 특화된 나만의 AI 에이전트를 만들 수 있습니다. 코드 리뷰 전문가, 문서 작성 전문가 등을 직접 정의해요.

에이전트 정의 파일(.md)을 만들어두면, Claude가 필요할 때 해당 에이전트를 자동으로 호출합니다. 반복 작업에 특화된 전문가 에이전트를 만들어두면 매번 긴 지시를 다시 설명하지 않아도 됩니다.

에이전트 정의 파일 구조 (11개 필드)

name: 에이전트 이름 (영문, 하이픈 사용) description: 언제 호출할지 설명 (중요!) tools: 허용할 도구 목록 (Read, Write, Bash 등) disallow-tools: 금지할 도구 model: 사용할 모델 (claude-opus-4-6 등) subagent_type: 에이전트 유형 isolation: worktree (격리 실행 여부) mode: acceptEdits / bypassPermissions max_turns: 최대 대화 횟수 run_in_background: 백그라운드 실행 team_name: 소속 팀

코드 리뷰 에이전트 예시 (.claude/agents/code-reviewer.md)

---
name: code-reviewer
description: 코드 품질 검토. 보안·성능·가독성 순으로 분석하고 개선점 제안
tools: Read, Grep, Glob
---

# 코드 리뷰 에이전트

코드를 검토할 때는 다음 순서로 진행합니다:

1. 보안 취약점 (SQL 인젝션, XSS, 인증 누락 등)
2. 성능 문제 (N+1 쿼리, 불필요한 루프 등)
3. 가독성 (변수명, 함수 분리, 주석)

항상 한국어로 보고하고, 심각도를 🔴/🟡/🟢로 표시하세요.

전역 vs 프로젝트 에이전트

~/.claude/agents/ — 내 모든 프로젝트에서 사용 가능한 개인 에이전트 .claude/agents/ — 현재 프로젝트에서만 사용 (팀원과 공유 가능, git에 포함)

자동 호출되는 상황

"이 코드 리뷰해줘" → code-reviewer 에이전트 자동 호출 "문서 작성해줘" → doc-writer 에이전트 자동 호출 "배포해줘" → deployment 에이전트 자동 호출 description 필드가 잘 쓰여 있을수록 Claude가 정확히 판단합니다.

장점과 주의사항

•✅ 반복 지시 불필요 — 한 번 정의하면 항상 그 방식대로
•✅ 도구 제한으로 안전성 확보 — 읽기 전용 에이전트는 파일 수정 불가
•✅ 팀원과 공유 가능 — .claude/agents/를 git에 포함
•✅ 모델 선택 — 간단한 작업엔 Haiku, 복잡한 작업엔 Opus
•⚠️ description이 불명확하면 잘못된 에이전트가 호출될 수 있음
•⚠️ 너무 많은 에이전트 → Claude가 어떤 걸 써야 할지 혼란

💡

에이전트 설명(description)은 3인칭으로, '언제' 호출해야 하는지 명확하게 적으세요. "코드 리뷰를 해야 할 때 사용" 보다 "PR 또는 파일 검토 요청 시 보안·성능·가독성을 체크하는 전문 리뷰어"처럼 구체적으로.

Agent Teams

Remote Control