Claude Code를 사용하면 자신만의 서브에이전트(subagents)를 정의할 수 있습니다. 이는 Claude가 위임할 수 있는 전문가 역할을 하는 Markdown 파일로, 고유한 시스템 프롬프트(system prompt), 고유한 도구 액세스(tool access), 그리고 고유한 컨텍스트 윈도우(context window)를 가집니다. 메커니즘은 간단하지만, "내 서브에이전트가 작동하지 않는다"는 대부분의 문제는 문서에서 한 번 언급되지만 사람들이 대충 지나치는 세 가지 세부 사항에서 발생합니다. 즉, 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는 모든 서브에이전트의 description을 읽고, 작업이 그 설명과 일치할 때 위임 여부를 결정합니다. 이것이 전체 라우팅(routing) 메커니즘입니다. 별도의 등록 단계나 설정 토글은 없습니다. description의 품질이 곧 트리거(trigger)입니다.

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

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

...

두 번째 방식이 작동하는 이유는 에이전트가 무엇인지뿐만 아니라, '언제' 위임해야 하는지를 설명하기 때문입니다. 요청받지 않아도 위임이 일어나기를 원한다면, 설명에 그렇게 명시하세요. "코드 변경 후 선제적으로 사용"과 같은 문구는 공식 예제에서 정확히 사용하는 방식입니다.

언제든지 라우팅(routing)을 우회하여 명시적으로 호출할 수 있습니다: "방금 제가 수정한 파일들에 대해 code-improver 서브에이전트를 사용하세요."

실제로 중요한 필드들

전체 프론트매터(frontmatter) 목록은 더 길지만, 제가 주로 사용하는 것들은 다음과 같습니다:

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

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

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

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

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

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

/agents 명령에 관한 참고 사항

이전 글들은 대화형 생성 마법사(interactive creation wizard)를 실행하기 위해 /agents를 사용하라고 안내합니다. 현재 버전에서는 해당 마법사가 사라졌습니다. 이제 /agents는 단순히 .claude/agents/ 디렉터리를 직접 편집하도록 안내하거나, Claude에게 해당 파일을 작성해 달라고 요청하는 역할을 합니다. 파일 형식과 위치는 변경되지 않았으므로, 기존의 에이전트 파일들은 계속해서 정상적으로 작동합니다.

디버그 체크리스트 (Debug checklist)

서브에이전트가 사용되지 않을 때, 다음 순서대로 확인하는 것이 가장 빠릅니다:

1. 파일이 아예 로드됩니까? 이름에 콜론(:)이 포함되어 있거나 YAML 형식이 잘못된 경우 → 조용히 건너뛰어집니다. 디버그 로그(debug log)를 확인하십시오.
2. 실행 중인 정의가 본인이 작성한 것입니까? 트리 내 어디에서든 name이 중복되는 경우 → /doctor를 실행하십시오.
3. 설명(description)에 언제 사용해야 하는지 명시되어 있습니까? 직함(job title)이 아닌 트리거 조건(trigger condition)으로 다시 작성하십시오.
4. tools 항목이 제대로 해석됩니까? Greps와 같은 오타가 있으면 도구가 0개라는 오류와 함께 실행에 실패합니다.
5. 여전히 안 됩니까? 이름을 통해 명시적으로 한 번 호출해 보십시오. 명시적 호출은 작동하지만 자동 위임(automatic delegation)이 작동하지 않는다면, 원인은 항상 설명(description)에 있습니다.

저는 Bluesky에서 Claude Code, Cursor, Codex에 관한 실용적인 노트를 매일 게시하고 있습니다 — @ai-shop.bsky.social. 제가 관리하는 테스트된 기술 및 규칙 팩은 Rulestack에서 확인할 수 있습니다.