커스텀 에이전트 정의 파일 작성법

에이전트 정의 파일은 커스텀 서브에이전트의 설정과 행동을 기술한 Markdown 파일입니다. .claude/agents/ 아래에 두면 "코드 리뷰"나 "테스트 작성" 같은 특정 태스크를 전문 서브에이전트에게 위임할 수 있고, Git으로 팀과 공유할 수 있습니다. 보통은 메인 에이전트(Claude 본체)가 모든 일을 처리하지만, 정의 파일이 있으면 해당 상황에서 전문 에이전트가 자동으로 호출돼 반복 태스크의 품질이 일정해집니다. 서브에이전트 자체의 개념과 컨텍스트 분리 원리는 서브 에이전트로 작업 나누기에서 다룹니다.

핵심 요약

• 정의 파일은 .claude/agents/(프로젝트) 또는 ~/.claude/agents/(개인)에 Markdown으로 둡니다
• 프론트매터의 name·description·tools·model로 역할을 정하고, 본문에 지시를 적습니다
• description을 보고 Claude가 자동으로 서브에이전트를 고르며, 이름을 지정해 명시적으로 부를 수도 있습니다
• 만드는 방법은 Claude Code에 부탁하기와 파일 직접 두기 두 가지이며, /agents 위저드는 폐지됐습니다
• 추가·수정한 정의는 다음 실행부터 유효합니다

정의 파일은 어디에 두나

이름이 충돌하면 프로젝트 쪽이 우선합니다. 팀에서 통일할 에이전트는 프로젝트 쪽에, 개인적으로만 쓸 에이전트는 사용자 쪽에 두세요.

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

예전에는 /agents 커맨드의 대화식 위저드로도 만들 수 있었지만 폐지됐습니다. 지금 /agents를 실행하면 "The /agents wizard has been removed. Ask Claude to create or update subagents for you, or edit the files directly"라는 안내만 돌아옵니다(2026년 8월, v2.1.228 기준). 웹에 남아 있는 위저드 화면 캡처는 더 이상 재현되지 않으니 아래 두 방법을 쓰세요.

방법 1: Claude Code에게 만들게 하기

맡길 일과 원하는 이름·도구를 말하면 Claude가 파일을 써 줍니다.

> 코드 리뷰 전문 서브에이전트를 이 프로젝트용으로 만들어줘.
  이름은 code-reviewer 로 하고, 읽기 계열 도구만 쓸 수 있게 해줘.

판단이 필요한 부분은 중간에 물어봅니다. 위 의뢰에서는 "git diff를 직접 실행하려면 Bash도 허용할지"를 확인한 뒤 .claude/agents/code-reviewer.md를 생성했습니다. 생성된 프론트매터는 다음과 같습니다.

---
name: code-reviewer
description: 이 프로젝트의 코드 리뷰 전문 에이전트. 코드를 쓴/변경한 직후, 커밋이나 PR 작성 전에 PROACTIVELY 쓴다. 버그·엣지 케이스·에러 핸들링 누락·보안상 문제·기존 패턴으로부터의 일탈을 지적한다. 읽기 전용이며 코드 수정은 하지 않는다. 호출할 때는 리뷰 대상(미스테이징 변경, 특정 파일, 특정 커밋 범위 등)을 명시할 것. 지정이 없으면 미커밋 변경을 리뷰한다.
tools: Read, Grep, Glob, Bash
---

의뢰문에 없던 "호출 시 리뷰 대상을 명시할 것", "지정이 없으면 미커밋 변경을 본다" 같은 조건까지 description에 들어갔고, 본문에는 Bash를 읽기 전용 명령(git diff, git log, rg 등)으로 제한하는 규칙과 리뷰 절차·보고 포맷이 이어집니다. 프롬프트 작성이 서툴러도 초안은 이걸로 갖춰지니, 나머지는 프로젝트에 맞게 손보면 됩니다. 작성법 자체를 상담하고 싶을 때는 내장된 claude-code-guide 서브에이전트를 쓸 수 있습니다.

방법 2: .claude/agents/ 에 파일을 직접 두기

쓸 내용이 정해져 있거나 기존 정의를 손볼 때는 직접 편집하는 편이 빠릅니다. 리포지토리 루트에서 mkdir -p .claude/agents로 폴더를 만들고 code-reviewer.md 같은 파일을 추가하면 됩니다. 형식은 방법 1에서 생성된 파일과 같습니다. 모든 프로젝트에서 쓰려면 ~/.claude/agents/에 두세요.

추가한 정의는 다음 실행부터 유효합니다

어느 방법으로 만들었든 그 세션에서는 바로 호출할 수 없습니다. 에이전트 정의는 세션 시작 시 읽어 들이기 때문입니다. 작성 직후 호출하면 이런 에러가 납니다.

⎿  Error: Agent type 'code-reviewer' not found. Available agents: claude,
   claude-code-guide, Explore, general-purpose, Plan, …

Claude Code를 종료했다가 다시 실행하면 같은 의뢰가 code-reviewer(Review app.js) 형태로 서브에이전트에 넘어갑니다. 정의를 고쳤는데 반영이 안 되는 것 같을 때도 먼저 재실행부터 해 보세요.

정의 파일의 기본 구조

정의 파일은 프론트매터와 본문으로 구성됩니다.

---
name: agent-name
description: 언제 이 에이전트를 쓸지의 설명
tools: Read, Write, Bash
model: sonnet
---
# 에이전트명

에이전트의 역할과 전문 지식의 상세한 설명.

## 호출됐을 때의 동작
1. 스텝1
2. 스텝2

프론트매터 필드

model: inherit은 에이전트를 호출한 메인 에이전트의 모델을 그대로 쓴다는 뜻입니다. 각 항목의 의미는 커스텀 커맨드 프론트매터와 같은 요령이니 함께 보면 좋습니다.

description은 어떻게 써야 자동 호출이 잘 되나

description은 자동 호출의 판단 근거이므로 "어떤 상황에서 호출해야 하는가"를 명확히 적어야 합니다. "코드 리뷰 시에 사용", "테스트 실패 시에 사용"처럼 사용 장면을 쓰는 것이 효과적입니다.

PROACTIVELY 또는 MUST BE USED 키워드를 넣으면 Claude에 대한 지시가 강조됩니다. 공식 문서상 둘의 차이는 크지 않으며, 전자는 "적극적으로 사용", 후자는 "반드시 사용"에 가깝습니다. 평범한 문장으로도 동작하지만 이 키워드가 있으면 서브에이전트 선택 기준이 뚜렷해져 호출 정확도가 올라가는 경향이 있고, 서브에이전트가 여럿일 때 우선순위를 매기는 데 특히 효과적입니다.

다만 모든 태스크에 붙일 필요는 없습니다. 단일 파일의 간단한 수정, 원샷 태스크, 사용자가 명시적으로 지시한 작업은 메인 에이전트가 직접 처리하는 편이 효율적인 경우가 많습니다. PROACTIVELY가 어울리는 것은 코드 품질 체크나 테스트 생성 같은 복잡한 태스크, 정기적으로 반복하는 태스크, 컨텍스트 분리가 유효한 작업입니다.

발동 조건은 when 절로 적습니다. when tests fail.(테스트가 실패하면), when debugging issues or errors occur.(디버그 중이거나 에러가 나면), when code changes are detected.(코드가 변경되면)처럼 조건이 보이면 매칭이 쉬워집니다.

완성 예제 1: 코드 리뷰어

파일 경로: .claude/agents/code-reviewer.md

---
name: code-reviewer
description: Use PROACTIVELY when code changes are detected. 코드 품질, 보안, 유지보수성을 리뷰
tools: Read, Grep, Glob, Bash
model: sonnet
---
# Code Reviewer

당신은 시니어 코드 리뷰어입니다. 높은 코드 품질과 보안 기준을 확보합니다.

## 호출됐을 때의 동작
1. `git diff` 로 최근 변경을 확인
2. 변경된 파일에 초점을 맞춘다
3. 리뷰를 실시

## 리뷰 체크리스트
- 가독성 (심플하고 이해하기 쉬운가)
- 명명 (함수와 변수가 적절한가)
- 중복 (코드 중복이 없는가)
- 에러 핸들링
- 보안
- 테스트 커버리지

## 우선순위별 피드백
- 중요 (보안 문제, 명확한 버그)
- 경고 (퍼포먼스, 유지보수성)
- 제안 (리팩터링안)

수정 방법의 구체적인 예도 포함해 보고하세요.

완성 예제 2: 테스트 라이터

파일 경로: .claude/agents/test-writer.md

---
name: test-writer
description: Use PROACTIVELY after new feature implementation or when test coverage is insufficient
tools: Read, Write, Bash
model: sonnet
---
# Test Writer

포괄적인 테스트 케이스를 작성하는 테스트 전문가입니다.

## 테스트 작성 절차
1. 테스트 대상 코드를 이해
2. 엣지 케이스와 에러 케이스를 특정
3. 테스트 케이스를 설계
4. 테스트 코드를 구현
5. 테스트를 실행해 확인

## 테스트의 원칙
- AAA 패턴 (준비→실행→검증)
- 독립성 (단독으로 실행 가능)
- 가독성
- 망라성 (정상계와 이상계)
- 고속성 (빠른 피드백)

테스트는 구현의 상세가 아니라 **행동**을 테스트하세요.

도구 권한은 어디까지 줘야 하나

서브에이전트에게 허가할 도구는 꼭 필요한 것만 주세요. 지나친 권한은 그대로 보안 리스크가 됩니다. 리뷰나 분석만 하는 에이전트라면 tools: Read, Grep, Glob처럼 Write·Edit을 빼 두면 의도치 않은 편집을 원천적으로 막을 수 있습니다.

읽기 전용 에이전트의 좋은 활용처가 프로젝트 고유의 설계 규약 검증입니다. 예를 들어 Onion Architecture를 쓴다면 "Repository 층 파일이 infrastructure/repositories/에 있는가", "Domain 층이 Infrastructure 층에 의존하지 않는가", "비즈니스 로직이 Application·Infrastructure 층으로 새지 않았는가"를 점검하고 위반 위치(파일 경로와 행 번호)·위반 규칙·수정안을 보고하는 architecture-validator를 두는 식입니다. 기존 린터나 테스트로는 잡을 수 없는 팀 규약을 꾸준히 지켜봐 준다는 점이 강점입니다.

MCP 서버의 도구를 쓰게 하려면 mcp__<server-name>__<tool-name> 형식으로 지정합니다. tools를 생략하면 MCP 도구까지 포함한 모든 도구에 접근할 수 있으므로, 의도치 않은 조작을 막으려면 명시하는 편이 안전합니다.

---
name: note-analyzer
description: Obsidian 노트를 분석하는 전문 에이전트
tools: Read, mcp__obsidian-mcp-tools__get_vault_file
---

여러 서브에이전트를 협조시키려면

서브에이전트가 여럿이라면 CLAUDE.md에서 메인 에이전트를 '오케스트레이터(지휘자)'로 정의해 역할을 나눠 줄 수 있습니다. 메인 에이전트가 어떤 순서로 어느 서브에이전트를 부를지만 적어 주면 됩니다. CLAUDE.md의 기본 사용법은 CLAUDE.md 작성법을 참고하세요.

당신은 오케스트레이터(지휘자)입니다.
사용자로부터 코드 작성 의뢰를 받으면 아래 절차로 처리해 주세요.

## 워크플로
1. **계획 페이즈**: 사용자 요건을 정리하고 필요한 태스크를 추려낸다
2. **구현 페이즈**: code-writer 서브에이전트에게 코드 구현을 위임한다
3. **테스트 페이즈**: test-writer 서브에이전트에게 테스트를 작성하게 한다
4. **리뷰 페이즈**: code-reviewer 와 security-reviewer 에게 코드 품질과 보안 체크를 병렬로 위임한다
5. **수정 페이즈**: 리뷰 지적을 바탕으로 code-writer 또는 test-writer 에게 수정을 위임한다
6. **완료**: 최종 확인 후 사용자에게 보고한다

각 서브에이전트의 책무:
- **code-writer**: 코드 구현에만 전념
- **test-writer**: 테스트 케이스 설계와 구현
- **code-reviewer**: 코드 품질 체크
- **security-reviewer**: 보안 체크

이렇게 해 두면 "이 피처를 구현하고 테스트까지 만들고 리뷰해줘"라는 한마디로 여러 서브에이전트가 자동으로 협조해 태스크를 끝냅니다. 다소 극단적인 예이니 프로젝트 규모에 맞게 줄여 쓰세요.

서브에이전트는 어떻게 호출되나

자동 호출은 Claude가 description을 보고 알맞은 서브에이전트를 고르는 방식입니다. "코드를 리뷰해줘"에 code-reviewer가, "이 버그를 수정해줘"에 debugger가 붙는 식이라, description에 사용 장면과 키워드가 잘 적혀 있을수록 정확합니다.

명시적 호출은 "code-reviewer 서브에이전트를 써서 보안을 체크해줘", "test-writer 서브에이전트에게 테스트를 작성하게 해줘"처럼 이름을 지정하는 방식입니다. 자동 호출이 잘 안 되거나 특정 에이전트를 확실히 쓰고 싶을 때 유용합니다.

잘 동작하는 정의 파일의 두 가지 원칙

1. 1에이전트 1책임. 하나의 서브에이전트에 여러 역할을 주면 판단이 모호해져 기대대로 움직이지 않습니다. description: 코드를 쓰고 테스트하고 리뷰한다는 나쁜 예이고, description: 코드 리뷰만 한다가 좋은 예입니다. 여러 작업이 필요하면 여러 에이전트를 연계시키세요.
2. 본문은 구체적으로. 모호한 지시보다 구체적인 지시·예·제약을 담은 프롬프트가 일관된 결과를 냅니다. "좋은 함수명: calculateTotalPrice, fetchUserData / 나쁜 함수명: func1, doStuff, tmp"처럼 좋은 예와 나쁜 예를 나란히 보여 주면 기댓값을 더 정확히 잡습니다.

지식을 제공하는 Skills와 태스크를 위임하는 서브에이전트 중 무엇을 고를지는 Skills vs 서브에이전트에서, 서브에이전트가 완료됐을 때 독자적인 처리를 붙이는 방법은 SubagentStop 훅에서 다룹니다.

정리

• 정의 파일은 .claude/agents/에 Markdown으로 두고 Git으로 팀과 공유합니다
• description에 사용 장면과 when 절을 적어야 자동 호출이 정확해집니다
• 1에이전트 1책임을 지키고, tools는 필요 최소한만 명시합니다
• 작성은 Claude Code에 부탁하거나 파일을 직접 두는 두 가지이며, 추가한 정의는 다음 실행부터 유효합니다