description을 제목이 아닌 트리거 조건으로 만들어 서브에이전트 라우팅(routing)을 수정하세요. 이름 충돌에는 /doctor를 사용하고 tools 항목을 검증하세요. 이를 통해 커스텀 에이전트를 신뢰할 수 있는 전문가로 변모시킬 수 있습니다.

핵심 요약 (Key Takeaways)

• description을 제목이 아닌 트리거 조건으로 만들어 서브에이전트 라우팅(routing)을 수정하세요.
• 이름 충돌에는 /doctor를 사용하고 tools 항목을 검증하세요.
• 이를 통해 커스텀 에이전트를 신뢰할 수 있는 전문가로 변모시킬 수 있습니다.

문제점: 당신의 서브에이전트가 보이지 않습니다

당신은 .claude/agents/ 파일을 작성했지만, Claude Code는 이를 전혀 위임(delegate)하지 않습니다. 문서상으로는 YAML 프론트매터(frontmatter)가 포함된 마크다운(Markdown) 파일을 넣기만 하면 끝나는 아주 간단한 작업처럼 보입니다. 하지만 "내 서브에이전트가 작동하지 않는다"는 대부분의 불만 사항은 무심코 지나치기 쉬운 세 가지 세부 사항으로 거슬러 올라갑니다. 즉, description 필드가 라우터(router) 역할을 한다는 점, name 충돌이 발생하면 파일이 조용히 누락된다는 점, 그리고 잘못된 tools 항목 하나가 에이전트 실행을 완전히 중단시킨다는 점입니다.

현재 문서에 따라 검증된 전체 시스템을 소개하니, 몇 분 안에 문제를 해결해 보세요.

30초 요약 버전

서브에이전트는 YAML 프론트매터(frontmatter)가 포함된 하나의 마크다운(Markdown) 파일입니다:

---
name: code-improver
description: "파일을 스캔하고 가독성, 성능 및 베스트 프랙티스(best practices)를 위한 개선 사항을 제안합니다. 코드를 작성하거나 수정할 때 사용하세요."
...

파일을 어디에 두느냐에 따라 누가 사용할지가 결정됩니다:

• 프로젝트 내의 .claude/agents/ → 해당 프로젝트 (보통 커밋되므로 팀원과 공유됨)
• ~/.claude/agents/ → 머신 내의 모든 프로젝트

두 위치 모두 재귀적으로 스캔되므로 agents/review/와 같은 하위 폴더로 파일을 정리할 수 있습니다. 하위 폴더 경로는 에이전트 식별 방식에 아무런 영향을 주지 않습니다. 식별은 파일명이나 경로가 아닌 오직 name 필드에서만 이루어집니다. name과 description만 필수이며, 그 외의 모든 것은 선택 사항입니다.

위임은 단지 description 매칭일 뿐입니다

Claude는 모든 서브에이전트(subagent)의 description을 읽고, 작업이 그 내용과 일치할 때 위임(delegate)을 결정합니다. 이것이 라우팅(routing) 메커니즘의 전부입니다. 별도의 등록 단계나 설정 토글(config toggle)은 없습니다. 즉, description의 품질이 곧 트리거(trigger)입니다.

이는 가장 흔한 실패 사례가 description을 마치 제목처럼 작성하는 것임을 의미합니다:

# 절대 사용되지 않음
description: Database expert

...

두 번째 방식이 작동하는 이유는 단순히 에이전트가 무엇인지가 아니라, 언제 위임해야 하는지를 설명하기 때문입니다. 요청받지 않아도 위임이 일어나기를 원한다면 description에 명시하세요. "코드 변경 후 선제적으로 사용(use proactively after code changes)"과 같은 표현이 바로 공식 예제에서 사용하는 방식입니다.

라우팅을 우회하여 명시적으로 호출할 수도 있습니다: "방금 내가 변경한 파일들에 대해 code-improver 서브에이전트를 사용해줘."

실제로 중요한 필드들

전체 프론트매터(frontmatter) 목록은 더 길지만, 실제로 자주 사용하게 될 필드들은 다음과 같습니다:

tools에는 두 가지 주의할 점(sharp edges)이 있습니다. 첫째, 항목들은 반드시 실제 도구 이름으로 해결(resolve)되어야 합니다. 만약 일치하는 이름이 없다면, 서브에이전트는 잘못된 항목을 지칭하는 오류와 함께 실행에 실패합니다. 둘째, 특정 스킬(Skill)을 미리 로드(preload)하고 싶다면 skills 필드를 사용해야 합니다. tools에 Skill을 나열하는 것은 호출 도구(invocation tool)만 부여할 뿐, 아무것도 로드하지 않습니다.

name에는 한 가지 주의할 점이 있습니다. 소문자와 하이픈(-)만 사용해야 하며 콜론(:)은 사용할 수 없습니다. 콜론은 my-plugin:reviewer와 같이 플러그인 범위 식별자(plugin-scoped identifiers)를 위해 예약되어 있습니다. 현재 버전에서는 이름에 콜론이 포함된 파일을 로드하는 것을 거부하며, 유일한 증상은 디버그 로그에 한 줄이 남는 것뿐입니다.

우선순위: 이름이 충돌할 때 누가 승리하는가

여러 서브에이전트가 동일한 이름을 공유할 경우, 우선순위가 더 높은 위치의 정의가 승리합니다. 관리형(managed, 조직 배포) 정의가 프로젝트 정의보다 우선하며, 프로젝트 정의는 사용자 정의보다, 사용자 정의는 플러그인 에이전트보다 우선합니다. 중첩된 프로젝트 디렉터리 사이에서는 작업 디렉터리(working directory)와 가장 가까운 정의가 승리합니다.

위험한 경우는 서브폴더를 포함하여 동일한 .claude/agents/ 트리 아래에 name이 같은 두 파일이 존재하는 경우입니다. Claude Code는 문서화된 규칙이 아니라 파일 시스템의 읽기 순서에 따라 단 하나만 로드합니다. 런타임(runtime) 중에 아무런 경고도 주지 않으므로, 정성껏 업데이트한 정의가 단순히 실행되고 있는 것이 아닐 수도 있습니다. /doctor는 동일 디렉터리 내의 중복을 보고하므로, 서브에이전트가 이전 버전처럼 동작할 때마다 이를 실행하세요.

또한 알아두어야 할 점은, Explore라는 이름의 프로젝트 또는 사용자 서브에이전트는 내장된 읽기 전용(read-only) Explore 에이전트를 덮어쓴다는 것입니다. 이는 가끔 유용할 수 있지만(예를 들어, model: haiku를 사용하여 탐색 작업을 더 저렴한 모델로 고정하는 경우), 누군가 일반 에이전트의 이름을