Claude Code의 서브 에이전트(.claude/agents/ 하위에 두는 커스텀 에이전트)는 "서브 태스크를 다른 문맥(Context)에서 처리하게 하는 메커니즘"으로 많은 기사에서 소개되고 있다. 하지만 "결국 언제 사용해야 하는가", "언제 사용하지 않는 것이 좋은가"를 판단 기준과 함께 정리한 정보는 적다. 본 기사에서는 공식 문서(Create custom subagents)의 기술을 바탕으로 이 판단 기준을 정리한다.

서브 에이전트란 무엇인가 (전제의 재확인)

• 독립된 컨텍스트 윈도우(Context Window)에서 동작한다. 대화 이력, 이미 읽은 파일, 호출된 스킬은 승계되지 않는다 (fork라는 특수한 기동 방법을 제외).
• Claude가 태스크 내용과 각 서브 에이전트의 description 필드를 대조하여, 자동으로 위임할지 여부를 판단한다. @ 멘션으로 명시적으로 지정할 수도 있다.
• 툴 액세스(Tool access), 권한 모드(Permission mode), 사용 모델을 에이전트마다 제한할 수 있다.

이를 바탕으로 실제 판단 기준을 5가지로 정리한다.

판단 기준 1: 출력 노이즈를 메인 흐름에 가져오고 싶지 않은가

테스트 실행 결과, 로그, 대량의 파일 내용 등 참조를 마친 후에는 불필요해지는 대량의 출력을 다루는 태스크는 전형적인 서브 에이전트용이다. "테스트 스위트를 실행해서 실패한 테스트만 보고해줘"와 같이 상세 정보는 자식 에이전트 측의 문맥에 가두고, 요약본만 메인 흐름으로 돌려보낼 수 있다.

반대로, 출력 그 자체를 지속적으로 참조하거나 편집해야 하는 작업(구현하면서 대화를 통해 세밀하게 조정하는 케이스 등)은 메인 흐름에서 진행하는 것이 재작업(Backtrack)을 줄이는 길이다.

판단 기준 2: 독립적으로 병렬 실행할 수 있는가

여러 조사 대상이 서로 의존하지 않는 경우, 서브 에이전트의 병렬 실행이 유효하게 작용한다. 예를 들어 "인증, DB, API 처리를 각각 별도의 서브 에이전트로 병렬 조사해줘"라는 요청에서는 각 에이전트가 독립적으로 탐색하고, 나중에 Claude가 결과를 통합한다.

반대로 계획 → 구현 → 검증과 같이 각 페이즈가 직전 페이즈의 문맥을 필요로 하는 경우에는 메인 흐름에서 연속적으로 대응하는 것이 빠르다. 서브 에이전트는 호출될 때마다 새로운 컨텍스트에서 시작하기 때문에, 매번 상황을 다시 설명해야 하는 오버헤드가 발생한다.

판단 기준 3: 툴 제한 및 권한 분리가 필요한가

"읽기 전용으로 만들고 싶다", "특정 MCP 서버만 사용하게 하고 싶다" 등 권한 자체를 설계하고 싶은 상황은 서브 에이전트용이다. tools 필드를 통한 허용 리스트(Allowlist)화, disallowedTools를 통한 제외, permissionMode를 통한 권한 모드 지정이 가능하다.

다만 2가지, 오해하기 쉬운 주의점이 있다. 첫째, 이 제한은 OS 레벨의 격리가 아니라 Claude Code가 해결하는 툴 목록의 제어에 그친다. 예를 들어 disallowedTools에서 Write와 Edit만 제외하더라도, Bash나 MCP 툴을 통한 파일 변경까지는 막을 수 없다. 정말로 읽기 전용으로 만들고 싶다면, 필요한 툴만 tools의 허용 리스트로 명시하고 Bash나 MCP 툴을 포함하지 않는 설계로 해야 한다 (허용 리스트와 제외 리스트가 동일한 안전성을 갖는 것은 아니라는 점은, 후술할 별도의 기사 ".claude/agents 설계에서 자주 하는 실수 5선"에서 실제로 검증하고 있다). 둘째, 메인 흐름(부모 대화)이 bypassPermissions나 acceptEdits 모드로 동작하고 있는 경우, 서브 에이전트 측에서 지정한 permissionMode는 이 부모 모드에 의해 덮어씌워지며, 서브 에이전트 단독으로 안전한 방향으로 설정할 수 없다. "권한 분리"라는 말이 가리키는 것은 어디까지나 이 범위 내에서의 툴 및 권한 모드 설계이며, 샌드박스(Sandbox)와 같은 강제력 있는 격리가 아니다.

판단 기준 4: 빠른 반복(Iteration)이 필요한가

"그 자리에서 바로 수정해줘", "상황을 보면서 세밀하게 조정해줘"와 같이 즉시성이 요구되는 태스크는 메인 흐름이 적합하다. 서브 에이전트는 새로 문맥을 수집해야 하는 만큼 레이턴시(Latency)가 발생하기 쉽기 때문이다.

판단 기준 5: 여러 프로젝트에서 재사용하고 싶은가

특정 리뷰 관점이나 코딩 규약 체크 등, 프로젝트를 가로질러 반복적으로 사용하는 정형 작업은 ~/.claude/agents/에 두는 유저 레벨(User level)의 서브 에이전트로 키울 가치가 있다. 프로젝트 고유의 정형 작업은 .claude/agents/에 두고, 버전 관리를 통해 팀과 공유한다.

실무에서 유용한 작은 포인트

• 모델은 생략 시 inherit

（본류와 동일한 모델）이 된다. 저비용 모델로 고정하고 싶은 경우에만, model: haiku와 같이 명시적으로 지정한다.

• v2.1.198 이후, 서브 에이전트(Sub-agent)는 기본적으로 백그라운드(Background)에서 실행되며, 포그라운드(Foreground)보다 제한된 툴셋(Tool-set)으로 동작한다. 포그라운드를 전제로 하는 툴을 사용하게 하려는 설계에서는 이 동작을 의식할 필요가 있다.
• 서브 에이전트는 기본적으로 최대 3계층까지 중첩(Nest) 가능하다 (환경 변수 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH로 변경 가능). 무한히 중첩할 수 있는 것은 아니다.

구체적인 상황에 대입해 보기

판단 기준을 실제 요청 문구에 대입해 보면 이해하기 쉽다.

서브 에이전트가 적합한 예:

• "테스트 스위트(Test suite)를 실행해서, 실패한 테스트와 에러 메시지만 보고해줘" → 대량의 테스트 로그라는 노이즈(Noise)를 본류로 가져오지 않아도 된다 (기준 1).
• "인증 관련, DB 관련, API 관련을 각각 별도의 서브 에이전트로 병행 조사해줘" → 의존 관계가 없는 독립적인 조사를 병렬화할 수 있다 (기준 2).
• "읽기 전용으로 리포지토리 전체를 스캔해서 의존 관계를 파악하는 에이전트를 만들어줘" → 쓰기 권한을 부여하고 싶지 않은 상황 (기준 3).

본류에서 수행하는 것이 좋은 예:

• "이 UI의 외관을 확인하면서 조금씩 조정해줘" → 매번 피드백을 반영하는 반복 작업 (기준 4).
• "방금 계획한 내용을 바탕으로 그대로 구현을 진행해줘" → 계획 단계의 문맥(Context)을 그대로 계속 사용할 필요가 있으며, 서브 에이전트로 분리하면 문맥을 재설명하는 비용이 발생한다 (기준 2·4).

요약표

마치며

"서브 에이전트를 사용하는 것" 자체가 목적이 되면, 오히려 문맥 단절로 인한 오버헤드(Overhead)만 늘어나게 된다. 판단 기준을 깊이 파고들면, "본류의 문맥을 더럽히고 싶지 않은가·지키고 싶은가"와 "즉시성·연속성을 우선시하는가"라는 저울질에 도달하게 된다.

설정 파일 작성의 번거로움을 줄이기

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

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

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

본 기사에서 다룬 판단 기준은 "언제 사용하는가"의 첫 단계에 불과하다. 실제로 .claude/agents/를 설계할 때는 권한 분리, 병렬 실행, 컨텍스트 관리(Context management)를 체계적으로 조합해야 하며, 단편적인 기사의 지식만으로는 판단에 어려움을 겪는 경우가 많다.

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

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

• tools / disallowedTools / permissionMode를 조합한 권한 설계 패턴 모음. 무엇을 허용 리스트(Allowlist)로 만들고, 무엇을 부모의 permission mode에 맡길지에 대한 판단표
• 의존 관계가 없는 조사를 안전하게 병렬화하기 위한, 중첩 깊이 및 동시 실행 수의 상한을 고려한 설계 지침
• 실제로 기동 에러나 의도치 않은 권한 누출이 발생하는 설정 예시와, 그 수정본을 실기 검증을 포함하여 수록한 장애 진단표

본 기사는 공식 문서(docs.claude.com / code.claude.com)의 기재 내용을 확인하며, AI 어시스턴트(Claude)의 지원을 받아 집필하였다. 기재 내용은 집필 시점(2026년 8월)의 문서를 바탕으로 한다. 공개 전 제3자 리뷰를 거쳐 권한 관련 설명을 실기 동작에 맞춰 수정하였다. 최신 동작은 공식 문서에서 확인하기 바란다.

Discussion