이 글에 대하여
직접 만든 서브 에이전트(.claude/agents/에 위치하는 정의 파일)를 Agent 툴로 호출할 때, 다음과 같은 오류가 발생할 수 있습니다.
Agent type 'zz-probe-f2-file' not found. Available agents: claude, Explore, general-purpose, Plan, statusline-setup, zz-probe-f2-name
이 글은 이 오류의 원인을 '위치(置き場所)', '작성 방식(書き方)', '생성 시기(作った時期)' 중 어느 것에 초점을 맞춰야 하는지 단계별 절차와 확인된 결과를 정리한 것입니다. 정의의 위치나 작성 방식을 하나씩 변경하는 임시 프로젝트를 사용하여, 정의가 로드되는지 여부를 측정했습니다.
이 글에서 알 수 있는 것
- 오류 메시지에 나오는
Available agents: 목록을 통해 무엇을 파악할 수 있는지 - '위치', '작성 방식', '생성 시기' 중 어떤 것이 원인인지 구분하는 3단계 절차
claude plugin validate와 --debug-file이 각각 어떤 원인의 이유를 알려주고, 어떤 원인에서는 침묵하는지 - 복사하여 사용할 수 있는 체크리스트
대상 독자
.claude/agents/에 사용자 정의 서브 에이전트를 두고 사용하고 있는 사람 - Agent type '…' not found 오류가 발생했지만 원인을 알 수 없는 사람
전제 환경 및 이 글의 조건
- Claude Code 2.1.305, Windows 11 Home, Node.js v24.18.0 (2026-11-04 측정)
- 이 글의 모든 측정 결과와 결론은 이 조건을 기준으로 읽어주세요. 다른 버전이나 OS에서는 측정하지 않았습니다.
claude -p
(대화형 모드가 아닌 비대화 모드. --output-format stream-json 포함)에서의 상기 환경 결과입니다. - 측정은 %TEMP%\cc-agent-nf-*라는 임시 폴더(git init 완료됨)에서 진행했습니다. 설정 로드는 --setting-sources project,local로 한정하여, 사용자용(~/.claude/agents/) 정의가 섞이지 않도록 했습니다. 모델은 haiku입니다 - 목록에 표시되는지 확인(2-1 및 2-2절)은 각 케이스를 1회씩 진행했습니다. 실제로 호출을 확인하는 경우에는 P1을 지시문 문구를 바꿔 여러 번, M1을 대기 시간 3초로 2번, 30초로 1번 실행했습니다. 동일한 조건을 반복하여 불안정성을 조사하지는 않았습니다.
이 글에서 다루지 않는 것
정의가 발견된 이후에 발생하는 실패(시작 불가, 도중에 멈춤 등)는 다루지 않습니다. 이는 Claude Code의 서브 에이전트 시작 오류 분류 글에 작성했습니다.
결론부터: 3단계로 원인 구분하기
| 단계 | 할 일 | 알 수 있는 것 |
|---|
| ① | 오류 메시지의 Available agents: 목록에 자신의 정의 이름이 있는지 확인한다. | 있다면, 정의는 로드된 것입니다. 호출명이나 호출 후의 문제를 의심합니다. 없다면, 로드되지 않은 것입니다. |
| ② | claude plugin validate .claude/agents와 --debug-file로, 로드되지 않는 이유를 본다. | 작성 방식 오류의 일부는 이유가 나옵니다. 나오지 않는 원인도 있습니다 (후술). |
| ③ | 이유가 없고, 위치나 작성 방식도 맞다면, 정의를 만든 시기를 의심한다. | 실행 중에 최초 파일을 만들었을 경우, 새로운 프로세스로 재시작하기 전까지 호출할 수 없었습니다. |
①에서 이름이 목록에 있음에도 실패하는 경우에는, 정의의 로드 문제가 아니라 그 이후의 문제입니다. 위에 작성된 시작 오류 글의 분류로 넘어가 주세요.
1. 오류 메시지 읽는 법
오류는 다음 형태였습니다.
Agent type '<호출한 이름>' not found. Available agents: <로드된 이름 목록>
<호출한 이름>은 Agent 툴의 subagent_type에 전달한 문자열입니다 - 목록에는 내장된 5가지( claude, Explore, general-purpose, Plan, statusline-setup)
）와, 로드된 사용자 정의 정의의 이름이 나열됩니다. 사용자 정의 정의의 이름은 파일 이름이 아니라, 정의 시작 부분에 있는 것입니다. 파일 이름과 name: 값(name:)이 다른 정의(케이스 F2)를 파일 이름으로 호출하면 맨 처음에 오류가 발생했습니다. 목록의 끝에는 name: 값이 나와 있습니다. 즉, 호출명은 name: 값입니다. 공식 문서에서도 name을 식별자(identifier)로 설명하고 있습니다 (출처: Create custom subagents. 2026-11-04 확인). 따라서, 목록에서 자신의 정의의 name: 값이 있는지 확인하는 것이 첫 번째 분기점입니다.
2. 목록에 표시되거나 표시되지 않는 조건
목록에 나타나는지 여부는 모델을 사용하지 않고 확인했습니다. claude -p를 stream-json의 입출력으로 실행하고, 표준 입력에 다음 한 줄을 작성한 후 표준 입력을 닫으면 응답(control_response)의 agents 항목에 로드된 이름이 들어갑니다 (비용은 0).
claude -p --input-format stream-json --output-format stream-json --verbose --setting-sources project,local --no-session-persistence --max-budget-usd 0.05
{"type":"control_request","request_id":"t2-init-1","request":{"subtype":"initialize"}}
--max-budget-usd 0.05는 만약 모델이 작동할 경우의 상한선으로 추가했습니다. 이 한 줄만으로는 비용이 0이었습니다. 필자는 Node.js의 spawnSync의 input에서 이 한 줄을 전달했습니다 (작성 후 표준 입력이 닫힙니다). 쉘(Shell)에서는, 한 줄을 작성한 파일을 <로 리다이렉트하는 것과 같은 방식입니다. 이 명령어는 기사에서와 동일한 인자 순서로 실행하여 동일한 결과를 얻었음을 확인했습니다.
응답에는 계정 관련 항목(account)이 포함되어 있습니다. 기록으로 남기거나 다른 사람에게 보여주기 전에 반드시 제거해야 합니다.
측정한 정의는 다음과 같은 형태입니다 (<id>는 케이스별 이름).
---
name: zz-probe-<id>
description: Probe for case <id>. Use only when explicitly asked to call zz-probe-<id>.
...
2-1. 배치 방법 (置き場所)
| 케이스 | 배치 방법 | 목록에 표시되었는지 |
|---|
| P1 (대조) | .claude/agents/<이름>.md | 표시됨 |
| P2 | .claude/agents/team/의 서브 폴더 | 표시됨 |
| P3 | .claude/agent/ (s가 없음) | 표시되지 않음 |
| P4 | 프로젝트 직하단의 agents/ | 표시되지 않음 |
| P5 | 작업 폴더는 서브 폴더, 정의는 프로젝트 직하단의 .claude/agents/ | 표시됨 |
| P6 | 확장자가 .txt | 표시되지 않음 |
| O1 | --agents 옵션에 JSON으로 전달 | 표시됨 |
P3, P4, P6은 디렉토리 이름이나 확장자 철자의 차이입니다. 이유는 어디에서도 나오지 않았습니다.
- P3, P4, P6에 대해서는 공식 문서에서 동일한 내용의 기술을 찾을 수 없었습니다. 이 표의 '표시되지 않음'은 측정 결과만을 근거로 합니다.
- P2와 P5는 공식 문서에도 서브 폴더의 재귀적 읽기(recursive reading)와 작업 폴더로부터 상위로 탐색하는 것이 명시되어 있으며, 이는 측정 결과와 일치합니다 (상동 출처).
- O1은 목록에 표시되는 것까지 확인했습니다. 호출하는 것은 시도하지 않았습니다.
2-2. 작성 방식 (書き方)
⚠️ [IMG:N]
| 케이스 | 작성 방식 | 목록에 표시되었는지 여부 |
|---|
| F1 | name: 행이 없음 | 안 됨 |
| F2 | 파일명과 name: 값이 다름 | name: 값만 표시됨 (파일명은 표시되지 않음) |
| F3 | description의 따옴표를 닫지 않음 (YAML 오류) | 안 됨 |
| F4 | description이 없음 | 안 됨 |
| F5 | name에 대문자/공백/밑줄(총 3가지 케이스) 사용 | 표시됨 (작성한 대로 이름으로) |
| F6 | 맨 앞의 ---로 둘러싸인 정의부가 없음 (본문만 있음) | 안 됨 |
| F7 | 줄바꿈이 CRLF | |
| 출력됨 | | |
| F8 | UTF-8 BOM(파일 시작 부분의 표시 바이트) 포함 | |
| 출력됨 | | |
| F9 | 같은 name을 가진 파일이 2개 (직하와 team/) | |
1개만 출력됨 (description은 직하 파일의 것) | | |
name과 description이 필수적이라는 것은 공식 문서에 명시되어 있습니다(위와 동일한 출처). F5는 목록에 표시되었을 뿐입니다. 공백을 포함하는 이름 등을 실제로 호출할 수 있는지는 시험해 보지 않았습니다. 목록에 표시된다고 해서 어떤 이름이라도 사용할 수 있다는 의미는 아닙니다.
- F7과 F8은 2.1.305 버전에서는 문제없이 읽혔습니다. BOM이 포함된 파일이 조용히 무시되는 버그는 CHANGELOG의 2.1.239에서 수정되었다고 명시되어 있습니다(출처: CHANGELOG. 2026-11-04 확인). 오래된 버전에서는 다른 결과가 나올 수 있습니다.
- F9의 경우, 목록에는 단 하나만 표시되었으며,
--debug-file 로그에서는 직하 파일이 사용된다고 나왔습니다(제3장). 공식 문서에는 같은 .claude/agents/(서브 폴더 포함) 내에서 동일한 name을 가진 것이 2개 있을 경우 로드되는 것은 1개뿐이며, 어느 쪽이 될지는 정해진 우선순위가 아닌 파일 시스템의 읽기 순서에 따른다고 명시되어 있습니다(출처: Create custom subagents. 2026-11-08 확인). 이번 환경에서 직하가 선택된 것은 우연일 수 있으므로, 동일한 name을 여러 개 두지 않는 것이 안전합니다. 같은 페이지에는 /doctor를 사용하면 이 중복이 보고된다고도 되어 있지만, 본 문서에서는 시험하지 않았습니다. 다른 배치 조합은 확인하지 못했습니다.
2-3. 실제로 호출했을 때의 결과 (모델 사용 시)
목록에 표시된 결과가 실제 호출에서도 동일한지 haiku를 사용하여 확인해 보았습니다.
Call the Agent tool once with subagent_type "<이름>", prompt "go", and run_in_background set to false, so that it runs in the foreground and you wait for its result. Then reply with the exact text of the Agent tool result, or the exact error message if it failed. Do not retry and do not use any other tool.
run_in_background: false는 지정하지 않고 요청했을 때 비동기 시작 알림(Async agent launched successfully.)이 반환되어 결과를 받을 수 없었기 때문에 추가했습니다(단 1회의 관찰로, 기본 동작이라고 단정할 수는 없습니다).
| 케이스 | 결과 |
|---|
| P1 (대조군) | 호출됨 (응답 PROBE-OK-P1 ) |
| P3 | not found. 목록에 사용자 정의 이름이 없음 |
| F1 | not found. 목록에 사용자 정의 이름이 없음 |
| F2 (파일명으로 호출) | not found. 목록 끝 부분에 name: 값이 표시됨 |
| F4 | not found. 목록에 사용자 정의 이름이 없음 |
호출한 케이스(P3, F1, F4, 파일명으로 호출한 F2)에서는 목록에 나타나지 않는 이름은 실제 호출에서도 not found였습니다. 그 외의 케이스(P4, P6, F3, F6 등)는 목록 확인까지만 진행했습니다. 목록은 원인 범위를 좁히는 데 사용될 수 있습니다.
3. 오류가 발생하는 경우와 그렇지 않은 경우
로드되지 않는 이유를 확인할 수 있는 도구가 두 가지 있습니다. 둘 다 모델을 사용하지 않습니다.
claude plugin validate .claude/agents
claude -p --input-format stream-json --output-format stream-json --verbose --setting-sources project,local --no-session-persistence --max-budget-usd 0.05 --debug-file <사용 가능한 폴더 내의 로그 경로>
두 번째 표준 입력에는 챕터 2의 initialize 한 줄을 작성한 후 닫습니다. (plugin validate를 통해 agents 폴더를 확인할 수 있는 기능은 (v2.1.233 이상) 공식 문서의 서브 에이전트 페이지, '로드되지 않는 정의'에 관한 항목에 설명되어 있습니다. (출처: Create custom subagents. 2026-11-04 확인)).
| 케이스 | plugin validate | --debug-file |
|---|
F1 (name 없음) | 종료 코드 0. "passed". 에이전트 검사 라인 없음 | 해당 라인 없음 |
| F2 (파일명이 다름) | 종료 코드 0. passed | 해당 라인 없음 |
| F3 (YAML이 손상됨) | 종료 코드 1. YAML frontmatter failed to parse | |
[WARN] 및 [ERROR] 라인 (파싱 실패로 무시된 경우) |
| F4 (description 없음) | 종료 코드 0. "passed with warnings" (No description 경고) | [DEBUG]의 2줄 (필수 description 누락) |
| F6 (정의부 없음) | 종료 코드 0. passed. 에이전트 검사 라인 없음 | 해당 라인 없음 |
| F9 (같은 이름이 2개) | passed. 중복 경고는 발생하지 않음 | [DEBUG]에서 Duplicate agent name 및 사용된 파일 |
읽을 때의 핵심 포인트는 세 가지입니다.
- F3는 출력에 다음과 같은 내용도 포함되어 있었습니다.
validate의 종료 코드가 1이 되고, 그 이유도 표시됩니다. name을 읽을 수 없기 때문에 실행 시 이 에이전트가 전혀 로드되지 않는다는 내용입니다 -
- F4는 종료 코드만 보고 '합격'이라고 판단하면 놓치게 됩니다. 경고 문구를 읽어주세요.
validate가 실패가 아니라 "passed with warnings" (종료 코드 0)로 끝나더라도, 실제로는 로드되지 않습니다. -
- F1・F6은 "passed"라고 나와도 로드될 것이라는 보장은 되지 않습니다. 목록에 나타나지 않는 경우,
validate와 --debug-file 모두 이유를 표시하지 않습니다. name: 라인과 맨 앞의 ---을 눈으로 확인해 주세요.
--debug-file의 로그 발췌는 다음과 같습니다 (경로는 <tmp>로 대체했습니다).
[WARN] Failed to parse YAML frontmatter in <tmp>\...\.claude\agents\zz-probe-f3.md: YAML Parse error: Unexpected character
[ERROR] YAML frontmatter in <tmp>\...\.claude\agents\zz-probe-f3.md failed to parse and was ignored: YAML Parse error: Unexpected character
[DEBUG] Agent file <tmp>\...\.claude\agents\zz-probe-f4.md is missing required 'description' in frontmatter
...
- F4의 라인은
[DEBUG]입니다. 로그가 1회당 약 150~180줄(실행마다 약간씩 달랐습니다) 있었기 때문에, 'Failed to parse agent'
자신의 에이전트 이름으로 필터링하면 찾기 쉽습니다.
로그를 사람에게 보여주기 전에, 인증 및 계정 관련 줄과 홈 디렉토리 경로를 반드시 가려주세요. 측정된 로그에는 그러한 줄들이 포함되어 있었습니다.
4. 실행 중에 생성한 정의 (Definition)
'위치와 작성 방식이 모두 맞는데도, 만든 직후에 호출할 수 없다'는 경우입니다. claude -p
하나의 프로세스 안에서 첫 번째 파일을 작성하고 기다린 후, 두 번째 프로세스로 에이전트를 호출했습니다. 정의 파일은 모델이 아니라 측정용 스크립트에 의해 작성되었습니다 (첫 번째 결과를 받은 후에 작성하여 정해진 시간만큼 기다린 후, 두 번째를 전송했습니다).
| 경우 | 작업 |
|---|
| M1 | .claude/agents/가 없는 상태에서 실행하고 첫 파일을 생성한다 |
| M2 | .claude/agents/가 있는 상태에서 실행하고 다른 정의를 추가한다 |
| M3 | 기존 정의의 내용을 수정한다 |
| M4 | M1 이후에, 새로운 프로세스로 동일한 호출을 한다 |
- 공식 문서에도 같은 취지의 설명이 있습니다. 실행 시점에 없었던 agents 폴더에 첫 파일을 만든 경우, 재시작할 때까지 반영되지 않습니다. 그 외의 변경 사항은 모니터링되고 있어 몇 초 만에 반영됩니다 (출처: Create custom subagents. 2026-11-04 확인). 측정 결과는 이 설명과 모순되지 않았습니다.
- 대기 시간은 3초와 30초만 측정했습니다. 반영까지의 일반적인 길이는 알 수 없습니다.
- M4는 새로운
-p 프로세스에서 호출이 가능했다는 결과까지만입니다.
5. 복사하여 사용할 체크리스트
- 에러 메시지
Available agents:에 자신의 정의의 name: 값이 있는지 (있음 → 로딩 문제가 아니라, 호출명 또는 호출 후 문제일 수 있음)
- 호출명은 파일명이 아니라
name: 값이어야 함
- 위치는
.claude/agents/여야 함 (agent가 아니고 agents, 프로젝트 직하단의 agents/도 아님)
- 확장자는
.md여야 함
- 첫 줄이
---로 시작하고, 정의부를 ---로 닫았는지 확인
name:과 description:이 있는지 (description이 없으면, validate는 경고만으로 통과함)description 등의 값에 닫히지 않은 따옴표나 YAML 구조를 깨뜨리는 문자가 없는지claude plugin validate .claude/agents의 출력을 종료 코드뿐만 아니라 경고까지 읽었는지--debug-file 로그에서 Failed to parse agent 또는 자신의 에이전트 이름으로 필터링했는지 (공유하기 전에, 인증 및 계정 관련 줄과 홈 경로를 가릴 것)- 동일한
name의 정의가 여러 곳에 없는지
- 실행 중에 첫 파일을 생성했다면 (
.claude/agents/가 없었음), 새로운 프로세스로 다시 시작하여 호출했는지
6. 확인하지 못한 사항
- 대화 모드 (예:
/agents와 같은 작업, 재시작 절차)는 측정하지 않았습니다. 반영까지의 시간은 3초와 30초 두 지점만입니다. 그 외는 알 수 없습니다.
- 사용자용 (
~/.claude/agents/)이나 플러그인 정의, --add-dir로 추가한 폴더, --disable-slash-commands로 실행했을 경우에는 측정하지 않았습니다. 공식 문서에는 후자의 두 경우에 재시작이 필요할 때가 있다고 되어 있으나, 본 기사에서는 확인하지 못했습니다. 다른 버전 및 Windows 외 OS는 측정하지 않았습니다.
- F5 (대문자/공백/언더스코어 이름)와 O1 (
--agents)은 목록에 나타나는 것까지입니다. 호출 가능한지는 확인하지 못했습니다. - 목록 확인은 각 경우 1회만 했습니다. 동일한 조건을 반복했을 때의 측정 편차는 보지 않았습니다.
- 공식 문서의 설명은 2026-11-04 시점의 것을 재해석한 것입니다. 최신 정보는 각 페이지에서 확인하시기 바랍니다.
- 'not found'
이곳에 언급된 것들이 그 원인 전부라고는 할 수 없습니다. 이 표에 없는 원인이 있을 수도 있습니다.
필자가 운영하며 겪은 경험
필자 역시 운영 중에 이 not found 오류를 겪었습니다. 세션 도중에 새로 만든 서브 에이전트를 이름으로 호출할 수 없었고, 다른 방법으로 대행한 경위는 Claude Code 서브에이전트 조직 실습 가이드의 실패 사례 장(2-2절)에 적어두었습니다. 제 2장은 무료로 읽을 수 있습니다.
요약
Available agents: 목록에 자신의 name: 값이 있는지 여부가 첫 번째 분기점입니다. 목록에 없다면, 위치・작성 방식・생성 시기 순으로 하나씩 확인해야 합니다.validate가 'passed'여도 로드된다는 보장은 없습니다. name이 없는 정의와, 정의 부분이 없는 정의는 어떤 도구도 이유를 제시하지 않았습니다. - 위 내용은 Claude Code 2.1.305, Windows 11, claude -p에서의 결과입니다.
본 기사는 Claude Code(AI)가 실제 측정 기록과 샘플을 바탕으로 작성했습니다. 실측은 Claude Code의 서브에이전트(builder)가 임시 폴더에서 진행했습니다. 공개 여부 판단은 사람이 합니다.
Discussion
