커스텀 에이전트

동작하는 코드

.claude/agents/ 디렉토리에 코드 리뷰 전문 에이전트를 만들어봅시다:

> .claude/agents/code-reviewer.md를 만들어줘. 내용:

---
name: code-reviewer
description: 코드 리뷰 전문가. 품질, 보안, 유지보수성을 검토합니다.
tools: Read, Grep, Glob, Bash
model: inherit
---

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

## 리뷰 절차

1. `git diff`로 변경 사항 확인
2. 타입 안전성, 에러 핸들링, 성능 분석
3. 보안 취약점 검사
4. 코딩 컨벤션 준수 여부 확인

## 출력 형식

각 파일별로:

- [통과] 또는 [문제]
- 문제가 있으면 구체적인 개선 제안
- 심각도: 높음/중간/낮음

에이전트가 등록되었는지 확인합니다. 세션 안에서 /agents 명령어를 입력하세요:

> /agents

이제 코드를 수정한 뒤 리뷰를 요청합니다:

> @code-reviewer 방금 변경한 코드를 리뷰해줘

Claude가 code-reviewer 에이전트를 서브에이전트로 실행합니다.

직접 수정하기

문서화 전문 에이전트도 만들어보세요:

> .claude/agents/doc-writer.md를 만들어줘. 내용:

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

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

## 문서화 규칙

- 모든 public 함수에 JSDoc/TSDoc 주석 추가
- README.md에 설치, 사용법, API 레퍼런스 포함
- 코드 예시는 실행 가능한 것으로
- 한국어로 작성

에이전트를 백그라운드로 실행해봅시다:

> @doc-writer 이 프로젝트의 API 문서를 작성해줘

실행 중에 Ctrl+B를 누르면 백그라운드로 전환됩니다. 메인 프롬프트에서 다른 작업을 계속하세요. 에이전트가 완료되면 결과를 확인할 수 있습니다.

"왜?" — 전문화된 역할이 더 좋은 결과를 낸다

범용 프롬프트보다 전문 역할을 부여하면 결과가 좋아집니다. 이유는:

1. 역할에 맞는 관점: 코드 리뷰어는 보안과 품질에 집중하고, 문서 작성자는 가독성과 완전성에 집중합니다.
2. 도구 제한: 필요한 도구만 허용해서 불필요한 작업을 방지합니다.
3. 병렬 처리: 여러 에이전트를 동시에 실행해서 시간을 절약합니다.

에이전트 정의 구조

---
name: 에이전트 이름
description: 역할 설명 (매칭에 사용)
tools: 허용할 도구 목록
model: inherit 또는 sonnet, opus, haiku
permissionMode: default
---

시스템 프롬프트 내용

permissionMode로 에이전트의 권한을 제어할 수 있습니다:

| 모드 | 동작 | | ------------------- | ---------------------------------------------- | | default | 필요할 때 사용자에게 승인 요청 | | dontAsk | 승인 프롬프트를 자동 거부 (허용된 도구만 동작) | | bypassPermissions | 모든 권한 검사 건너뜀 (주의) | | plan | 읽기 전용 탐색만 허용 |

에이전트 저장 위치

| 위치 | 범위 | | ------------------- | -------------------------- | | .claude/agents/ | 프로젝트 전용 (Git에 커밋) | | ~/.claude/agents/ | 모든 프로젝트 공통 |

실무에서 유용한 에이전트 패턴

| 에이전트 | 역할 | | ------------------ | --------------------- | | code-reviewer | 코드 변경 사항 리뷰 | | doc-writer | API 문서, README 작성 | | test-writer | 유닛/통합 테스트 생성 | | security-auditor | 보안 취약점 검사 | | refactorer | 코드 정리, 패턴 개선 |

서브에이전트 호출

@에이전트명 작업 지시

@으로 호출하면 해당 에이전트가 서브에이전트로 실행됩니다. 서브에이전트는 메인 세션과 별도의 컨텍스트에서 작업하고, 결과만 반환합니다.

심화 학습