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

앞 글에서 서브 에이전트가 무엇이고 언제 쓰는지 봤다면, 이 글은 그것을 파일로 고정하는 법입니다. 같은 지시를 매번 프롬프트에 다시 쓰는 대신 .claude/agents/ 아래 Markdown 파일 하나에 역할, 도구, 모델을 적어 두면 Claude가 상황에 맞춰 스스로 그 에이전트를 부릅니다. 프론트매터 필드 전체를 공식 문서 기준으로 정리하고, 자동 호출이 잘 되는 description 작성법, 바로 붙여 쓸 수 있는 코드 리뷰어와 테스트 라이터 예제, 도구 권한을 어디까지 줄지의 기준을 다룹니다.

읽고 나면 우리 팀이 쓰는 방식, 즉 작성하는 에이전트와 검증하는 에이전트를 분리하고 검증 쪽은 읽기 전용으로 묶는 구조를 자기 프로젝트에 옮길 수 있습니다. 다음 글 「Context7 MCP로 시작하는 첫 MCP 서버」에서는 에이전트에 붙일 첫 외부 도구를 다룹니다.

핵심 요약

• 정의 파일은 프로젝트용 .claude/agents/ 또는 개인용 ~/.claude/agents/에 두는 Markdown이며, 필수 필드는 name과 description 둘뿐입니다.
• 본문은 그 에이전트의 시스템 프롬프트가 됩니다. 에이전트는 전체 Claude Code 시스템 프롬프트를 받지 않고 이 본문만 받습니다.
• description은 Claude가 "언제 이 에이전트에 맡길지"를 판단하는 유일한 근거입니다. 무엇을 하는지보다 언제 부르는지를 적습니다.
• tools를 생략하면 메인 대화의 모든 도구(MCP 포함)를 상속합니다. 리뷰어는 Read, Grep, Glob, Bash처럼 읽기 쪽으로 묶습니다.
• 파일을 추가하거나 고치면 몇 초 안에 감지되어 다음 위임부터 반영됩니다. 단, 세션 시작 시 없던 agents 디렉터리를 새로 만든 경우에는 재시작이 필요합니다.

정의 파일은 어디에 두나

같은 name이 여러 위치에 있으면 위 순서대로 높은 쪽이 이깁니다. 프로젝트 범위는 현재 작업 디렉터리에서 저장소 루트까지 올라가며 모든 .claude/agents/를 훑고, 두 디렉터리를 재귀적으로 읽으므로 agents/review/, agents/research/ 같은 하위 폴더로 정리해도 됩니다. 하위 폴더 경로는 식별자에 영향을 주지 않고, 식별자는 오직 name 필드입니다. Windows에서는 ~/.claude/agents/가 %USERPROFILE%\.claude\agents\입니다.

우리 기준은 단순합니다. 이 프로젝트의 규칙(예: "결제 금액은 서버가 정한다", "운영 DB는 성역")을 아는 리뷰어는 .claude/agents/에 커밋하고, 어느 레포에서나 쓰는 회의록 정리기 같은 것은 ~/.claude/agents/에 둡니다.

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

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

가장 빠른 길은 원하는 역할과 저장 위치를 설명하고 Claude에게 파일을 쓰게 하는 것입니다.

.claude/agents/ 에 읽기 전용 코드 리뷰어를 만들어 줘. 최근 변경분(git diff)만 보고,
이 레포의 CLAUDE.md 규칙 위반을 우선순위별로 보고하되 파일은 수정하지 않게.
모델은 inherit으로.

Claude가 name, description, tools, model과 시스템 프롬프트를 채운 파일을 작성합니다. 만든 뒤에는 파일을 열어 프론트매터가 요청과 맞는지 확인합니다. 특히 tools에 Edit이나 Write가 섞여 들어가지 않았는지 봅니다.

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

형식을 알면 손으로 쓰는 편이 정확합니다. 파일명은 아무거나 좋지만 name과 맞춰 두면 찾기 쉽습니다.

# macOS / Linux
mkdir -p .claude/agents
touch .claude/agents/code-reviewer.md

# Windows PowerShell
New-Item -ItemType Directory -Force .claude\agents | Out-Null
New-Item -ItemType File .claude\agents\code-reviewer.md

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

Claude Code는 .claude/agents/와 ~/.claude/agents/를 감시합니다. 파일을 추가하거나 편집하면 몇 초 안에 감지되어 다음 위임부터 새 정의를 씁니다. 이미 실행 중인 에이전트는 영향을 받지 않습니다. 재시작이 필요한 경우는 두 가지입니다. 세션 시작 시 존재하지 않던 agents 디렉터리를 새로 만들어 첫 파일을 넣은 경우(감시 대상은 시작 시점에 있던 디렉터리뿐), 그리고 --disable-slash-commands로 시작한 세션입니다.

정의 파일의 기본 구조

---
name: code-reviewer
description: 코드 품질과 보안을 검토합니다. 코드를 작성하거나 수정한 직후에 사용하세요.
tools: Read, Grep, Glob, Bash
model: inherit
---

당신은 시니어 코드 리뷰어입니다. 호출되면 git diff로 최근 변경분을 확인하고
품질, 보안, 유지보수성 관점에서 구체적이고 실행 가능한 피드백을 냅니다.

위쪽 YAML이 메타데이터와 설정, 아래 본문이 시스템 프롬프트입니다. 에이전트는 이 본문과 작업 디렉터리 같은 기본 환경 정보만 받고, 전체 Claude Code 시스템 프롬프트는 받지 않습니다. CLAUDE.md와 git 상태는 커스텀 에이전트에도 로드됩니다(내장 Explore와 Plan만 건너뜀).

프론트매터 필드

name과 description만 필수이고 나머지는 선택입니다.

tools와 disallowedTools에는 정확한 도구 이름 외에 MCP 서버 단위 패턴도 됩니다. mcp__github(또는 mcp__github__*)는 그 서버의 모든 도구를 뜻하고, disallowedTools의 mcp__*는 모든 MCP 도구를 뺍니다. 둘 다 있으면 disallowedTools가 먼저 적용되고 tools는 남은 풀에서 해석됩니다.

모델 해석 순서는 CLAUDE_CODE_SUBAGENT_MODEL 환경 변수 → 호출 시 넘긴 model 매개변수 → 프론트매터 model → 메인 대화의 모델입니다. 우리 운영 규칙(effort 기본 high, 서브에이전트는 low)을 파일에 박고 싶으면 effort: low를 적습니다.

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

Claude는 요청 내용, 각 에이전트의 description, 현재 맥락을 놓고 위임 여부를 정합니다. 따라서 description은 "무엇을 하는가"가 아니라 "언제 부르는가"를 적어야 합니다. 공식 문서는 적극적인 위임을 유도하려면 "use proactively" 같은 문구를 넣으라고 안내합니다.

세 가지를 지킵니다. 첫째, 트리거 조건을 명시합니다("~한 직후", "~파일이 바뀌면"). 둘째, 다른 에이전트와 겹치지 않게 경계를 둡니다. 리뷰어와 디버거의 설명이 비슷하면 엉뚱한 쪽이 불립니다. 셋째, 한 문장 안에 역할과 시점을 모두 넣되 길게 늘어놓지 않습니다. description은 항상 컨텍스트에 실리므로 길수록 매 턴 비용입니다.

완성 예제 1: 코드 리뷰어

우리 팀이 실제로 쓰는 구조를 옮긴 것입니다. 읽기 전용이고, 이 레포의 CLAUDE.md 규칙을 검토 기준으로 삼으며, 결과를 심각도 순으로 냅니다.

---
name: code-reviewer
description: 코드를 작성하거나 수정한 직후 품질, 보안, 프로젝트 규칙 준수를 검토합니다. 변경이 끝나면 커밋 전에 먼저 사용하세요. 파일을 수정하지 않습니다.
tools: Read, Grep, Glob, Bash
model: inherit
effort: low
color: blue
---

당신은 이 프로젝트의 시니어 코드 리뷰어입니다. 파일을 수정하지 않고 보고만 합니다.

시작하면:
1. `git diff`와 `git diff --cached`로 변경된 파일 목록을 확인합니다.
2. 변경된 파일만 읽습니다. 관련 코드는 Grep으로 필요한 만큼만 찾습니다.
3. 레포 루트의 CLAUDE.md를 읽고, 거기 적힌 규칙을 검토 기준의 최우선으로 둡니다.

검토 항목:
- 프로젝트 규칙 위반(예: 클라이언트가 보낸 금액을 신뢰하는 코드, 가격 하드코딩)
- 시크릿, 토큰, API 키 노출
- 입력 검증 누락과 에러 처리 부재
- 중복 코드와 불명확한 이름
- 테스트 없는 신규 분기

출력 형식(이 형식만 사용):
## 치명(반드시 수정)
- 파일:줄 · 문제 · 근거 · 최소 수정 제안
## 경고(수정 권장)
## 제안(고려)
## 확인한 것
- 실행한 명령과 결과 요약(예: `git diff --stat` 출력)

추측으로 지적하지 않습니다. 코드에서 확인한 줄만 인용합니다.

포인트는 셋입니다. tools에 Edit과 Write가 없어 실수로 고칠 수 없고, Bash는 git diff와 테스트 실행을 위해 남겼으며, 출력 형식을 고정해 메인 컨텍스트로 돌아오는 양을 통제합니다. "확인한 것" 절은 우리 원칙인 "정지 규칙은 증거"를 에이전트에 적용한 것입니다.

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

파일을 써야 하므로 Write와 Edit이 필요하지만, 대상을 테스트 디렉터리로 한정하고 구현 코드는 손대지 않게 프롬프트로 묶습니다.

---
name: test-writer
description: 새 함수나 API 라우트가 추가됐는데 테스트가 없을 때 테스트 파일을 작성합니다. 구현이 끝나고 커밋하기 전에 사용하세요.
tools: Read, Grep, Glob, Bash, Write, Edit
model: sonnet
maxTurns: 30
---

당신은 이 프로젝트의 테스트 작성자입니다. 테스트 파일만 만들고 구현 코드는 수정하지 않습니다.

절차:
1. 프로젝트의 테스트 러너와 기존 테스트 파일의 위치, 이름 규칙을 먼저 파악합니다(package.json의 test 스크립트, 기존 *.test.* 파일).
2. 위임받은 대상 함수나 라우트를 읽고, 정상 경로 1개, 경계값 1개 이상, 실패 경로 1개 이상을 설계합니다.
3. 기존 규칙과 같은 위치·이름으로 테스트 파일을 작성합니다.
4. 테스트를 실행하고, 실패하면 테스트 쪽 문제인지 구현 쪽 문제인지 구분합니다.
   구현 쪽 문제로 보이면 고치지 말고 재현 조건과 함께 보고합니다.

금지:
- 구현 파일 수정
- 테스트를 통과시키기 위한 `skip`, `only`, 빈 테스트
- 외부 네트워크나 운영 데이터베이스 접근

보고 형식:
- 생성한 파일 경로
- 실행한 명령과 통과/실패 수(실제 출력 인용)
- 구현 쪽 결함으로 의심되는 항목(있으면)

maxTurns를 둔 이유는 테스트가 계속 실패할 때 무한히 고치려 드는 것을 끊기 위해서입니다. 우리 규칙에서 test.skip이나 빈 테스트는 완료 증거가 아니라 차단 사유이므로 금지 목록에 명시했습니다.

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

원칙은 "그 역할을 수행하는 데 필요한 최소"입니다. 판단 기준을 표로 두면 이렇습니다.

tools 목록이 모두 잘못된 이름이거나 에이전트에서 쓸 수 없는 도구뿐이면 Claude Code는 에이전트 시작을 거부하고 해결되지 않은 항목을 오류로 돌려줍니다(v2.1.208 이후). 도구 이름 오타를 초기에 잡을 수 있는 셈입니다.

권한 모드도 도구만큼 중요합니다. permissionMode: plan은 읽기 전용 탐색을 강제하고, acceptEdits는 작업 디렉터리 안의 파일 편집을 자동 승인합니다. bypassPermissions는 프롬프트를 건너뛰므로 격리된 worktree(isolation: worktree)나 샌드박스 밖에서는 쓰지 않는 것이 우리 기준입니다. 메인 세션의 모드가 더 엄격하면 그쪽이 우선합니다.

MCP 서버는 mcpServers에 인라인으로 정의하면 그 에이전트가 시작할 때만 연결되고 끝나면 끊깁니다. 메인 대화에는 도구 설명이 실리지 않으므로, 브라우저 자동화처럼 도구가 많은 서버를 붙일 때 컨텍스트를 아끼는 방법입니다.

mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  - github

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

에이전트끼리 직접 대화하지는 않습니다. 협조는 메인 Claude가 순서를 잡거나, 한 에이전트가 하위 에이전트를 띄우는 방식입니다.

1. 체인: "code-reviewer로 성능 문제를 찾고, 그다음 optimizer로 고쳐 줘." 메인이 첫 결과를 받아 다음 에이전트에 필요한 맥락만 넘깁니다.
2. 병렬 후 종합: "auth, db, api를 각각 별도 에이전트로 조사해 줘." 결과를 메인이 합칩니다. 조사 경로가 독립적일 때만 씁니다.
3. 코디네이터: claude --agent coordinator로 메인 스레드 자체를 한 에이전트로 띄우고 tools: Agent(worker, researcher), Read, Bash처럼 생성 가능한 하위 유형을 허용 목록으로 제한합니다. 괄호 안 목록은 --agent로 띄운 메인 에이전트에서만 적용되고, 일반 서브에이전트 정의에서는 Agent의 유무만 봅니다.

우리 팀의 기본형은 "작성 패스와 검증 패스를 분리"입니다. 작성한 에이전트가 자기 결과를 승인하지 않고, 읽기 전용 리뷰어나 검증 에이전트가 별도 컨텍스트에서 봅니다. 중첩 깊이는 메인 아래 5단계까지이며, 특정 에이전트가 하위를 못 만들게 하려면 tools에서 Agent를 빼거나 disallowedTools에 넣습니다.

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

세 단계가 있습니다.

• 자동 위임: 요청과 description이 맞으면 Claude가 스스로 부릅니다. 가장 흔한 경로이며, 그래서 description이 중요합니다.
• 명시 요청: 프롬프트에 이름을 적습니다("code-reviewer 서브에이전트로 최근 변경을 봐 줘"). 보통 위임하지만 보장은 아닙니다. 보장하려면 @를 입력해 자동완성에서 (agent) 항목을 고르거나 @agent-code-reviewer처럼 직접 적습니다. 이 경우 어느 에이전트가 실행될지는 보장되지만, 에이전트가 받는 작업 프롬프트는 여전히 Claude가 작성합니다.
• 세션 전체: claude --agent code-reviewer로 시작하면 메인 스레드가 그 에이전트의 시스템 프롬프트, 도구 제한, 모델을 그대로 씁니다. 프로젝트 기본값으로 만들려면 .claude/settings.json에 "agent": "code-reviewer"를 둡니다.

특정 에이전트를 막으려면 permissions.deny에 Agent(code-reviewer)를 넣습니다.

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

첫째, 한 에이전트는 한 가지 일만. 리뷰도 하고 고치기도 하고 테스트도 짜는 만능 에이전트는 어느 것도 잘하지 못하고, description도 흐려져 자동 호출이 어긋납니다. 역할이 둘이면 파일도 둘입니다.

둘째, 본문은 절차와 출력 형식으로. "당신은 전문가입니다" 같은 수사보다 "1. git diff 확인, 2. 변경 파일만 읽기, 3. 이 형식으로 보고"가 결과를 안정시킵니다. 우리 5주차 교재의 좋은 요청 황금 문장 "원인 분석 → 최소 수정 → 변경 정리"가 에이전트 본문에도 그대로 적용됩니다. 출력 형식을 고정하면 메인으로 돌아오는 양이 통제되고, "확인한 것" 절을 요구하면 보고가 증거를 동반합니다.

정리

• 정의 파일은 .claude/agents/(프로젝트) 또는 ~/.claude/agents/(개인)의 Markdown이며 name과 description만 필수입니다.
• 본문이 시스템 프롬프트입니다. 절차와 출력 형식을 적습니다.
• description에는 "언제 부르는지"를 적고, 적극 호출을 원하면 그 취지의 문구를 넣습니다.
• tools는 최소 권한으로. 리뷰어는 읽기 전용, 편집이 본업인 에이전트만 Write와 Edit을 줍니다.
• 작성과 검증은 다른 에이전트가 맡고, 보고에는 실행 명령과 출력을 포함시킵니다.

자주 묻는 질문