Claude Code 서브에이전트 문제 해결

확인 날짜 안내

공식 문서 Claude Code 서브에이전트(원본 날짜 미상, 수집 2026-10-18)에 흩어진 원인과 확인 방법을 증상별로 모았다. 원본에는 독립된 문제 해결 절이 없고, 오류 메시지 세부는 원본이 Errors 문서로 넘긴다. 정의 형식은 서브에이전트 정의 파일 레퍼런스, 만드는 절차는 Claude Code 서브에이전트 만들기·운영.

공통 도구#

• 디버그 로그: 셸에서 claude --debug로 실행하고 ~/.claude/debug/<session-id>.txt를 본다. 건너뛴 파일, 신뢰 안 된 훅·MCP, 빠진 스킬, 틀린 필드가 여기 남는다. Claude Code 서브에이전트
• claude plugin validate <디렉터리>: 세션 전에 agents 디렉터리(예: .claude/agents, ~/.claude/agents)에서 frontmatter(용어 사전)가 파싱되지 않는 파일을 찾는다. 지정한 디렉터리만 보고, 파싱은 되지만 name이 없는 파일은 잡지 않는다. v2.1.233 이상. Claude Code 서브에이전트
• /doctor: 같은 디렉터리에서 이름이 겹치는 파일을 보고하고 하나만 남기도록 제안한다. Claude Code 서브에이전트
• /tasks: 도는 서브에이전트의 실제 모델과 effort를 본다(v2.1.242 이상). Claude Code 서브에이전트

증상별 점검#

새로 만든 서브에이전트를 Claude가 못 찾는다#

1. 세션 시작 때 그 agents 디렉터리가 있었는지 본다. 파일 감시는 시작 때 있던 디렉터리만 다루므로, 그 범위의 첫 파일을 새 디렉터리에 만들었다면 재시작한다. Claude Code 서브에이전트
2. --add-dir·/add-dir로 더한 디렉터리의 .claude/agents/는 감시하지 않는다. 고친 뒤 재시작한다. Claude Code 서브에이전트
3. --disable-slash-commands로 시작한 세션은 이 디렉터리들을 전혀 감시하지 않는다. Claude Code 서브에이전트
4. 파일이 조용히 건너뛰어졌는지 본다(다음 절). Claude Code 서브에이전트
5. (2026-10-21 기준) 권한 규칙에 막혔는지 본다. permissions.deny의 Agent(<이름>) 규칙이나 --disallowedTools로 그 서브에이전트를 끌 수 있고(/permissions에서 규칙과 출처 파일 확인), deny·ask의 Agent(model:…)·Agent(isolation:…) 파라미터 규칙이 특정 호출만 막을 수도 있다. Claude Code 권한 설정 → Claude Code 권한 규칙 문법

파일이 로드되지 않는다 (아무 알림 없음)#

원본 규칙: 프로젝트·사용자·managed agents 디렉터리(또는 --add-dir 아래)의 파일은 아래 경우 세션에 알리지 않고 건너뛴다. Claude Code 서브에이전트

플러그인 서브에이전트는 name이 없거나 파싱이 안 돼도 파일 이름으로 로드된다. Claude Code 서브에이전트

엉뚱한 정의가 쓰인다#

• 같은 이름이 여러 위치에 있으면 managed > --agents > 프로젝트 > 사용자 > 플러그인 순으로 이긴다. 중첩된 프로젝트 디렉터리끼리는 작업 디렉터리에 가장 가까운 것이 이긴다. Claude Code 서브에이전트
• 같은 .claude/agents/ 트리(하위 폴더 포함) 안에 같은 name이 둘이면 파일 시스템 읽기 순서로 하나만 로드된다. /doctor로 찾아 하나만 남긴다. Claude Code 서브에이전트
• 사용자·프로젝트 레벨의 Explore는 내장 Explore를 덮어쓴다. 의도하지 않았다면 이름을 바꾼다. Claude Code 서브에이전트

설정한 필드가 효과가 없다#

1. 철자: 여러 단어 필드는 camelCase로 정확해야 하고, 틀린 필드는 오류 없이 무시된다. claude --debug의 로그에서 does not recognize or apply를 찾으면 알아보지 못한 최상위 필드를 최대 5개, 가까운 올바른 이름과 함께 보여 준다(v2.1.296 이상). Claude Code 서브에이전트
2. 플러그인 서브에이전트: hooks, mcpServers, permissionMode(그리고 initialPrompt)는 무시된다. 필요하면 파일을 .claude/agents/나 ~/.claude/agents/로 복사한다. Claude Code 서브에이전트
3. --agents JSON: color와 experimental은 무시된다. Claude Code 서브에이전트
4. permissionMode: 메인 대화가 bypassPermissions·acceptEdits·auto면 무시되고 메인 모드로 돈다. 메인이 default·dontAsk·plan이어도 bypassPermissions(v2.1.267 이상)나, 쓸 수 없는 auto(disableAutoMode, 모델 미지원)를 설정하면 메인 모드로 돈다. Claude Code 서브에이전트 → 권한 모드
5. model: CLAUDE_CODE_SUBAGENT_MODEL_FORCE가 켜져 있으면 무시된다. 조직 availableModels가 막으면 다른 모델로 대체되고 대화형 세션에 경고가 뜬다. opus 같은 계열 별칭은 메인 모델이 같은 계열이면 메인 모델로 풀린다. /tasks로 실제 모델을 확인한다. Claude Code 서브에이전트
6. effort: CLAUDE_CODE_EFFORT_LEVEL 환경 변수가 있으면 그쪽이 이긴다. Claude Code 서브에이전트
7. omitClaudeMd: --agent나 agent 설정으로 메인 세션 에이전트로 돌면 무시된다(CLAUDE.md가 일반 흐름으로 로드). 하위 디렉터리 CLAUDE.md와 경로별 규칙은 그 디렉터리 파일을 다룰 때 여전히 로드된다. v2.1.271 이상. Claude Code 서브에이전트
8. memory: 자동 메모리를 끄면(autoMemoryEnabled, CLAUDE_CODE_DISABLE_AUTO_MEMORY) 효과가 없다. Claude Code 서브에이전트
9. skills: disable-model-invocation: true 스킬(번들 /verify 포함)은 미리 로드되지 않는다. 없거나 정책으로 꺼진 스킬은 건너뛰고 디버그 로그에 경고. 33번째 이후 이름도 미리 로드되지 않는다. Claude Code 서브에이전트

autoCompactWindow가 안 먹는다#

• 200k처럼 쓰면 200으로 읽혀 범위(100000~1000000) 밖이 되고, 필드가 없는 것처럼 동작한다. 200000처럼 정수로 쓴다. 디버그 로그에서 invalid autoCompactWindow를 찾는다. Claude Code 서브에이전트
• 범위 안인데 변화가 없으면: 값이 원래 물려받을 자동 컴팩션 창보다 작지 않거나, --agent·agent 설정으로 세션 전체를 이 서브에이전트로 돌리는 경우다(거기서는 효과 없음). CLAUDE_CODE_AUTO_COMPACT_WINDOW를 양의 정수로 두면 그 값이 쓰이고 필드는 효과가 없다. v2.1.296 이상. Claude Code 서브에이전트

서브에이전트가 시작되지 않는다#

근거: Claude Code 서브에이전트

서브에이전트가 도구를 못 쓴다#

• 백그라운드(기본값)에서는 정해진 내장 도구만 남는다(포크와 재개된 포그라운드 서브에이전트는 예외). 포크 모드가 켜진 대화형 세션에서는 Claude가 포그라운드를 요청할 수 없다. 원본이 말하는 포그라운드 조건: CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1이면 모든 세션에서 포그라운드, 포크 모드를 끄면(CLAUDE_CODE_FORK_SUBAGENT=0) Claude가 결과가 있어야 계속할 때 포그라운드. Claude Code 서브에이전트
• AskUserQuestion, EnterPlanMode, ExitPlanMode(permissionMode: plan 제외), Workflow 등은 모든 서브에이전트에서 빠진다. Claude Code 서브에이전트
• disallowedTools: Bash(...)처럼 지정자를 쓰면 Bash 전체가 빠진다. 특정 명령만 막으려면 permissions.deny를 쓴다. Claude Code 서브에이전트

frontmatter 훅이나 인라인 MCP 서버가 안 돈다#

• 프로젝트 .claude/agents/(또는 --add-dir 디렉터리)의 파일이면 그 폴더의 작업 공간 신뢰를 수락해야 한다. 상위 폴더 신뢰와 -p 세션은 치지 않는다. 신뢰 전에는 서브에이전트는 돌되 훅·인라인 서버만 건너뛰고, 디버그 로그에 신뢰 방법(인라인 서버는 projects["<path>"].hasTrustDialogAccepted 키)이 남는다. Claude Code 서브에이전트 손으로 신뢰하려면 ~/.claude.json에서 그 키를 true로 둔다(<path>는 저장소 루트, 저장소 밖이면 그 폴더). 공식 권한 문서(2026-10-21)는 건너뛴 서브에이전트 훅의 디버그 로그 줄에도 이 키가 찍힌다고 적는다. Claude Code 권한 설정 → 작업 공간 신뢰
• 플러그인 서브에이전트면 두 필드 모두 무시된다. Claude Code 서브에이전트
• MCP 서버가 --strict-mcp-config, --bare, managed MCP, allowedMcpServers·deniedMcpServers에 막혔으면 건너뛰고 경고가 뜬다. Claude Code 서브에이전트
• 훅 스크립트에 실행 권한이 없으면(macOS·Linux) 막지 못하고 훅이 실패한다. chmod +x. Claude Code 서브에이전트 훅 쪽 일반 점검은 Claude Code 훅 문제 해결.

재개가 안 된다#

• Explore·Plan은 일회용이라 에이전트 ID가 없다. general-purpose나 커스텀 서브에이전트를 쓴다. Claude Code 서브에이전트
• 사용자가 x나 SDK stop_task로 멈춘 서브에이전트는 Claude의 메시지가 거부된다. 행이 패널에 남아 있는 동안 트랜스크립트에 직접 입력하면 재개되고, 그 뒤에는 Claude의 메시지로도 다시 재개된다. Claude Code 서브에이전트
• 이름으로 보냈는데 거부되면 더 새 에이전트가 그 이름을 가져간 것이다. 오류가 지금 그 이름이 가리키는 에이전트를 알려 주고, 이전 에이전트는 띄울 때 받은 ID로 부른다. 이 확인은 현재 대화 범위이고 /clear로 초기화된다. Claude Code 서브에이전트

결과가 이상하다#

• API 오류로 끊김: 포그라운드는 텍스트를 냈으면 부분 출력과 "끝내지 못했다"는 메모를, 아무것도 못 냈으면 Agent terminated early due to an API error를 돌려준다. 백그라운드는 실패로 표시되고 마지막 출력을 함께 전한다. 오류가 풀리면 다시 시키거나 재개한다. Claude Code 서브에이전트
• 보고서에 백슬래시나 [harness: subagent output matched instruction-shaped pattern(s): 줄이 보인다: 출력 검사가 Claude Code 출력을 흉내 낸 텍스트나 권한 설정 언급을 표시한 것이다(v2.1.210 이상). 내용을 지우거나 고쳐 쓰지 않고 백슬래시 삽입과 표시 줄 추가 두 가지만 하며, 악의 판단도 아니다. 서브에이전트가 무엇을 읽었는지 확인한다. Claude Code 서브에이전트
• maxTurns에서 멈춤: 출력이 부분으로 표시된다(v2.1.246 이상). 재개해 이어 간다. Claude Code 서브에이전트
• CLAUDE.md 규칙을 안 따른다: Explore·Plan과 omitClaudeMd 서브에이전트는 CLAUDE.md 없이 시작한다. 원본은 꼭 닿아야 하는 규칙(예: "ignore the vendor/ directory")을 위임할 때 프롬프트에 다시 적으라고 한다. Claude Code 서브에이전트 → 메모리(CLAUDE.md)
• 출력 스타일이 안 먹는다: 포크가 아닌 서브에이전트는 자기 시스템 프롬프트로 돌아 출력 스타일이 적용되지 않는다. Claude Code 서브에이전트

관련#

서브에이전트, 서브에이전트 정의 파일 레퍼런스, Claude Code 서브에이전트 만들기·운영, Claude Code 훅 문제 해결, 스킬 문제 해결