Claude Code의 커스텀 서브 에이전트(.claude/agents/ 하위에 두는 Markdown 파일)는 형식 자체는 단순하지만, 사양의 세부 사항을 간과하면 "작동은 하지만 기대한 대로 위임되지 않음" 또는 "기동 시 에러 발생"과 같은 문제에 빠지기 쉽다. 본 기사에서는 공식 문서(Create custom subagents)에 명시된 사양을 바탕으로, 설계 시 자주 발생하는 실수 패턴 5가지를 정리하고 수정 사례를 제시한다.

실수 1: 동일한 디렉토리 내에서 name이 중복됨

.claude/agents/ 하위(서브 폴더 포함)에서 동일한 name을 가진 파일이 여러 개 있으면, 어느 것이 로드될지는 파일 시스템의 로드 순서에 의존하며 명문화된 우선순위는 없다. 의도치 않게 한쪽의 정의만 유효하게 되어 "설정을 변경했는데 반영되지 않는" 상태가 되기 쉽다.

# agents/reviewer.md
---
name: reviewer
...

# agents/legacy/reviewer.md ← 동일한 name이 중복
---
name: reviewer
...

수정 방법: name은 디렉토리 트리 전체에서 유니크(Unique)하게 설정한다. /doctor 명령을 실행하면 동일 디렉토리 내의 중복이 검출되어 리네임 또는 삭제가 제안된다.

실수 2: tools 관련 오해 ― "일부 오타라면 툴이 0개가 된다"도 "쓰기 계열을 빼면 읽기 전용이 된다"도 모두 틀림

tools · disallowedTools는 직관과 실제 동작이 어긋나기 쉬운 필드이다. 여기서는 임시 검증용 서브 에이전트를 Claude Code 2.1.221에서 실제로 기동하여, 두 가지 오해를 검증했다.

검증 1: 툴 이름의 오타는 "일부"인지 "전부"인지에 따라 동작이 완전히 다름

# 케이스 A: 일부만 오타 (Grap만 틀림)
---
name: safe-researcher
...

이 설정을 실제로 기동하면, Read와 Glob만 해결되고, 오타인 Grap은 묵묵히 무시된 채 에러 없이 정상적으로 기동되었다. "타이포가 하나라도 있으면 툴이 0개가 되어 기동에 실패한다"는 것은 흔한 오해이지만 틀린 것이며, 실제로는 에러도 경고도 없이 의도보다 적은 툴 세트로 동작해 버리는 편이 오히려 위험하다.

# 케이스 B: 모든 항목이 오타
---
name: safe-researcher
...

이 경우는 리스트의 어떤 항목도 해결할 수 없기 때문에, Claude Code는 서브 에이전트의 기동 자체를 거부한다 (v2.1.208 이후. 그 이전 버전에서는 툴 없이 기동하여 빈 값이나 불가해한 결과를 반환했었다). 실제로 검증했을 때 반환된 에러는 다음과 같았다.

Agent 'zero-tools-test' would be spawned with zero tools — refusing. Its tools list resolved to nothing:
unrecognized [Reed, Grap, Globb]. Fix the agent's tools frontmatter or pass a different subagent_type.

수정 방법: tools를 작성했다면 한 번 실제로 기동하여, 의도한 툴 목록과 일치하는지 육안으로 확인한다. 부분적인 오타는 기동될 수 있으므로, 리뷰 시 "에러가 나지 않으니까 올바르다"라고 판단해서는 안 된다.

검증 2: disallowedTools: Write, Edit는 "읽기 전용"이 되지 않음

"쓰기 계열의 툴만 제외하면 읽기 전용이 된다"라는 설계도 실제로 검증해 보면 성립하지 않는다.

# 오답: 이것은 읽기 전용이 되지 않음
---
name: safe-researcher
...

이 설정으로 서브 에이전트를 기동하고 실제로 사용할 수 있는 툴을 선언하게 한 결과, Write와 Edit는 확실히 제외되었지만, Bash · Agent (서브 에이전트를 추가로 기동할 권한) · NotebookEdit · WebFetch · WebSearch, 그리고 접속된 MCP 툴 그룹은 모두 남아 있었다. Bash

가 남아 있는 시점에서, 셸의 리다이렉트(redirect)나 스크립트를 통해 파일을 수정할 수 있으므로, "쓰기 계열 도구를 제거했으니 읽기 전용이다"라는 생각은 잘못된 것이다.

읽기 전용으로 만들고 싶다면, 필요한 도구만을 허용 목록(allowlist)으로 명시하는 것이 유일하고 확실한 방법이다.

# 수정: 허용 목록 방식으로 읽기 전용을 보장함
---
name: safe-researcher
...

동일한 절차로 검증하면, 유효한 도구는 Read · Grep · Glob 이 세 가지만이었으며, Bash · Agent · MCP 툴을 포함한 다른 도구들은 일절 사용할 수 없었다.

이 두 가지 검증을 통해 얻을 수 있는 일반 원칙은, 허용 목록(tools)과 제외 목록(disallowedTools)은 사고 발생 가능성이 대칭적이지 않다는 것이다. 제외 목록은 "현재 있는 도구에서 빼기"를 하는 방식이므로, 향후 도구가 추가되었을 때 권한이 자동으로 늘어난다. 반면 허용 목록은 "명시된 것만" 사용할 수 있으므로, 향후 도구가 늘어나더라도 의도치 않게 권한이 확장되지 않는다. 최소 권한(least privilege)을 목표로 한다면, 제외 목록이 아닌 허용 목록을 선택해야 한다(필자도 이전 버전에서 "제외 목록이 사고가 덜 난다"라고 반대로 설명했기에 여기서 정정한다).

실패 3: description이 모호하여 자동 위임이 작동하지 않음

Claude는 description 필드의 내용과 태스크 내용을 대조하여 자동 위임(automatic delegation) 여부를 판단한다. "코드 리뷰를 하는 에이전트"와 같이 모호한 설명은, 위임되어야 할 상황에서 위임되지 않거나, 반대로 관계없는 상황에서 호출되는 결과를 초래한다.

# 모호함
description: 코드 리뷰를 하는 에이전트

# 구체적: 언제 사용해야 하는지를 명시하고, 능동적 위임을 촉구하는 어구도 포함
description: 코드 변경 후 코드 품질, 보안, 유지보수성을 전문적으로 리뷰한다. 코드를 작성하거나 변경한 직후에 적극적으로 사용한다 (use proactively).

실패 4: 컨텍스트(context)가 계승된다는 전제로 설계함

서브 에이전트는 fork(본류의 대화를 통째로 계승하는 특수한 기동 방식)를 제외하면, 본류의 대화 이력, 읽은 파일, 호출된 스킬을 계승하지 않는 독립된 신규 컨텍스트에서 시작한다. "아까 했던 조사의続き(계속)를 부탁해"와 같은 전제로 태스크를 전달해도, 그 "아까"의 정보는 서브 에이전트 측에 존재하지 않는다. 위임 시 Claude가 요약한 태스크 메시지만이 전달될 뿐이다.

한편, CLAUDE.md 파일과 본류의 git status 스냅샷은 (내장된 Explore/Plan을 제외하고) 계승되므로, "에이전트는 아무것도 모른다"라고 단정 지어 원래 CLAUDE.md에 적으면 될 규칙을 매번 프롬프트에 장황하게 다시 쓸 필요는 없다. 반대로 출력 스타일이나 자동 메모리(auto memory)는 계승되지 않으므로, 이러한 동작을 기대하는 설계는 성립하지 않는다.

해결 방법: 필요한 전제 정보는 태스크 설명(위임 프롬프트)에 명시적으로 포함한다. 연속 작업이 전제인 에이전트에는 동일 인스턴스를 재개하는 메커니즘을 사용한다.

실패 5: 백그라운드 실행 시의 도구 제한을 고려하지 않음

v2.1.198 이후, 서브 에이전트는 기본적으로 백그라운드에서 실행되며, 포그라운드(foreground)보다 좁은 도구 세트만 사용할 수 있다. 백그라운드 실행 시 허용되는 내장 도구는 Read · Grep · Glob · Bash · PowerShell · Edit · Write · NotebookEdit · WebFetch · WebSearch · TodoWrite · Skill · ToolSearch · EnterWorktree · ExitWorktree · Monitor · TaskStop · SendMessage · Artifact로 제한된다. tools 필드에 다른 도구를 나열해 두었더라도, 백그라운드에서 실행될 때는 자동으로 제거된다.

"포그라운드에서 동작 확인을 마쳤는데, 실제 운용 시에는 도구를 사용할 수 없는 것처럼 보인다"라는 버그는 대부분 이 차이 때문에 발생할 수 있다.

해결 방법: 포그라운드 고정이 필요한 상황에서는 포그라운드 실행을 명시적으로 지시한다. 또는 태스크 설계 자체를 백그라운드에서도 완결될 수 있는 내장 도구의 범위 내로 맞춘다.

요약

5가지 실패는 모두 "서브 에이전트(Sub-agent)는 독립된 컨텍스트(Context)와 실행 단위로 동작하며, 메인 흐름과는 전제가 다르다"라는 한 점으로 집약된다. 공식 문서(Official documentation)가 보장하는 것은 독립된 컨텍스트 윈도우(Context window), 시스템 프롬프트(System prompt), 권한 설정(Permission settings)이며, OS 프로세스로서의 격리를 명시하고 있는 것은 아니다 ("독립된 별도 프로세스"라는 표현은 부정확하므로 여기서 정정한다). .claude/agents/ 의 YAML 자체는 형식이 단순하지만, 이름(name) 해결 순서, 도구(Tool) 해결, 위임(Delegation) 판단, 컨텍스트 경계, 실행 모드라는 5가지 사양을 바탕으로 해야 비로소 의도한 대로 동작하는 서브 에이전트를 설계할 수 있다.

설정 파일 작성의 수고를 덜기

본 기사에서 다룬 .claude/agents/*.md 의 프론트매터(frontmatter)를 폼 입력으로부터 생성할 수 있는 무료 도구를 공개하고 있다 → https://subagent-lab.pages.dev/tools/agent-generator/

브라우저 내에서만 처리되므로, 입력 내용은 서버로 전송되지 않는다.

유료 도서에서 읽을 수 있는 내용

본 기사의 실패 사례는 모두 일시적인 검증용 에이전트로 실제로 재현 및 수정 확인을 거친 것이지만, 이는 "흔히 발생하는 실패의 입구"에 불과하다.

유료 도서 『Claude Code 서브 에이전트 설계 실전 가이드』는 무료 공개 범위(제1~2장)만으로도 본 기사보다 상세한 설계 기초를 읽을 수 있다 → https://zenn.dev/subagent_lab/books/claude-code-subagents/viewer/agent-design-patterns

무료 공개 범위에 포함되지 않는, 유료 범위 고유의 내용은 다음 3가지이다.

• 허가 목록(Allowlist)・제외 목록(Denylist)・permissionMode・부모 대화의 권한 모드와의 우선 관계를 조합한, 사고를 방지하는 권한 설계 패턴 모음
• 중첩 에이전트(Nested agents, 중첩 깊이·동시 실행 수의 상한)를 고려한 병렬 실행 설계와, 실패하기 쉬운 구성의 진단표
• 본 기사에서 다룬 것 이외의 설정 예시에 대해서도, claude doctor 상당의 검증을 포함하여 실기 확인을 거친 장애 진단표

본 기사는 공식 문서(docs.claude.com / code.claude.com)의 기재 내용을 확인하고, 일시적인 검증용 서브 에이전트를 통한 실기 확인을 수행하며, AI 어시스턴트(Claude)의 지원을 받아 집필하였다. 동작은 버전에 따라 달라질 수 있으므로, 실제로 설계할 때는 반드시 공식 문서의 최신 버전을 확인하기 바란다. 공개 전 제3자 리뷰를 받았으며, 본 기사의 핵심 사례를 실기에서 재검증한 후 수정하였다.

Discussion