Claude Code 서브 에이전트: 설정, 구성 및 사용 시점

대부분의 Claude Code 세션이 느려지고 지저분해지는 이유는 동일합니다. 탐색적인 grep 실행, 로그 덤프, 그리고 “하나 더 확인해 보자"는 식의 파일 확인 작업들이 모두 메인 대화 창에 영구적으로 남기 때문입니다.

서브 에이전트(Subagent)는 정확히 이 문제를 해결하기 위해 존재합니다. 이는 Claude Code에 내장된 에이전트 원시(primtive) 중 하나로, 소음이 많거나 병렬 처리 가능한 작업을 처리하기 위해 사용됩니다. 즉, 지저분한 작업을 격리된 창으로 밀어내고, 중요한 요약 정보만 가져오는 방식입니다.

서브 에이전트는 더 똑똑한 Claude가 아니며, Skill(스킬)과도 동일하지 않습니다. 이는 고유한 컨텍스트 윈도우, 고유한 도구 허용 목록(tool allowlist), 그리고 명시적으로 포크(fork)하지 않는 한 현재 대화의 기억이 없는 별도의 추론 에이전트입니다. 이러한 구분을 이해하는 것이 서브 에이전트 설정이 조용히 컨텍스트 예산을 아껴주는 것과 아무런 이득 없이 지연 시간만 추가하는 것 사이의 차이를 만듭니다.

서브 에이전트 vs Skill vs MCP

Claude Code는 서로 다른 문제를 해결하는 세 가지 확장 지점을 제공하며, 세 가지 모두 기술적으로 “작업에 도움을 줄 수” 있기 때문에 종종 혼동됩니다.

유용한 경험칙은 다음과 같습니다: 훅(hook)은 결정론적으로 강력한 제약 조건을 강제하고, Skill은 메인 에이전트에 인라인 기능을 제공하며, 서브 에이전트는 완전히 위임하고 메인 컨텍스트에서 제외하려는 작업을 위한 것입니다. 만약 Skill의 역할이 아직 존재하지 않는 도구를 조정하는 것이라면, 이는 일반적으로 서브 에이전트가 아닌 MCP 서버가 필요하다는 신호입니다. Claude Code만이 이러한 구조를 가진 것은 아닙니다 — OpenCode 생태계에는 전문화된 에이전트라는 유사한 개념이 있으며, 이는 계획, 연구, 검토를 전용 역할로 나누는 방식이 유사합니다.

서브 에이전트의 실제 정의

Claude Code 서브 에이전트를 정의하는 세 가지 속성이 있으며, 이 세 가지 모두 사용 방법에 중요합니다:

• 격리된 컨텍스트. 서브 에이전트는 새로운 창에서 시작됩니다. 명시적으로 포크하지 않는 한 대화 기록을 볼 수 없으므로, 세 턴 전에 논의했던 내용으로 인해 출력이 오염되지 않습니다.
• 제한된 도구 허용 목록. 서브 에이전트는 부모 세션이 이미 가지고 있는 도구들의 하위 집합만 사용할 수 있습니다 — 스스로 새로운 기능을 부여할 수 없으며, 잘 설계된 서브 에이전트는 작업에 필요한 도구만 가져야 합니다(예를 들어, 연구 에이전트의 경우 읽기 전용 도구).
• 서브 에이전트 간 가시성 부재. 서브 에이전트는 서로의 진행 상황을 볼 수 없습니다. 작업 B가 작업 A의 출력을 실제로 필요로 한다면, 이는 두 개의 서브 에이전트 간에 병렬 처리할 수 없는 순차적 의존성입니다.

서브 에이전트를 사용하기 위한 트리거는 “이 작업이 어렵다"가 아닙니다. “이 작업이 소음이 많다"는 것입니다 — 중간 출력이 많게 생성되는 작업(수십 개의 파일 읽기, 긴 로그, 전체 리포지토리에 대한 탐색적인 grep)로, 그 중간 자료들이 다음 대화 턴으로 남아야 할 필요가 없는 경우를 말합니다.

서브 에이전트 사용 시기와 비사용 시기

적합한 경우: 대규모 변경 전의 코드베이스 탐색, 통과/실패 및 실패 요약만 중요한 자동화된 테스트 실행, 보안 또는 스타일 검토, 그리고 원본 출력이 메인 세션을 범람하게 할 다단계 연구 작업 등.

부적합한 경우: 2초 걸리는 조회(“이 함수는 무엇을 반환하는가”), 긴밀한 왕복 개정이 필요한 작업, 그리고 두 번째 작업이 첫 번째 작업의 답변을 필요로 함에도 불구하고 “병렬 처리"하고 싶은 유혹에 빠지는 의존성 작업. 사소한 조회에 서브 에이전트를 사용하면 실제 격리 이득 없이 새로운 컨텍스트 윈도우를 시작하는 오버헤드만 추가됩니다.

투자 대비 효과 측정: 컨텍스트 및 비용 계산

서브 에이전트의 장점은 실제 작업에 숫자를 대입하기 전까지는 추상적입니다. 일반적인 예시를 들어보겠습니다: 약 500개의 파일을 가진 서비스에서 더 이상 사용되지 않는(config key)이 여전히 읽히고 있는 모든 곳을 grep하여, 정확한 파일:라인 매칭을 보고합니다.

이는 메인 세션이 해당 단계에서 지탱해야 할 부담을 대략 15-20배 줄이는 것으로, “서브 에이전트가 세션을 더 빠르게 유지한다"는 말의 실제 메커니즘입니다 — 이는 마법이 아니라, 애초에 로드되지 않는 컨텍스트입니다.

비용 측면에서도 동일한 방식으로 누적됩니다. Claude Code 가격 분석의 가격 정보를 사용할 때, Opus(입력 $5/MTok, 출력 $25/MTok)로 동일한 탐색 단계를 실행하면 ~40K 입력 토큰만으로도 대략 $0.20-0.25가 비용으로 발생합니다. 이를 Haiku(입력 $1/MTok, 출력 $5/MTok)로 라우팅하면 $0.04-0.05로 감소하며 — 메인 세션의 Opus 예산은 탐색 토큰에 전혀 영향을 받지 않습니다. 메인 세션은 ~2K 토큰 분량의 요약만 보기 때문입니다.

커스텀 서브 에이전트 정의

커스텀 서브 에이전트는 YAML 프론트매터(frontmatter)가 있는 Markdown 파일로 존재하며, 프로젝트 범위인 .claude/agents/(리포지토리에 커밋되어 전체 팀이 공유) 또는 사용자 범위인 ~/.claude/agents/(모든 프로젝트에 가져오는 개인 도구)에 배치됩니다.

---
name: code-reviewer
description: >
  Reviews staged changes for bugs, security issues, and style violations
  before commit. Use when the user asks to review, audit, or check
  changes prior to committing or opening a PR.  
tools: Read, Grep, Glob
model: sonnet
skills:
  - security-checklist
---
You are a careful code reviewer. Read the staged diff, flag concrete
issues with file:line references, and end with a short pass/fail summary.
Do not modify any files.

description 필드는 파일에서 가장 중요한 줄입니다. 이는 부모 세션의 라우팅 로직이 이 서브 에이전트가 현재 작업에 적합한지 결정하기 위해 읽는 부분입니다. 구인 광고처럼 작성하세요 — 모호한 “코드 도움이 된다"가 아니라 트리거 조건을 명시적으로 명시하세요. 모호한 설명은 자동 배포에서 건너뛰거나 잘못 적용됩니다.

tools 필드는 격리 경계입니다. 연구 서브 에이전트에게 Read, Grep, Glob만 제공하고 나머지는 제공하지 마세요; 사용 가능한 모든 도구를 제공하면 제한된 샌드박스에서 실행하는 전체 의미가 무산됩니다. 선택적 skills 필드는 서브 에이전트의 시작 컨텍스트에 명명된 Skill의 전체 내용을 미리 로드합니다 — 서브 에이전트가 작업 중간에 발견하고 로드하는 턴을 소비하지 않고 도메인 지식이 필요할 때 유용합니다.

모델 라우팅: 값싼 모델로 잡일 처리

서브 에이전트는 또한 비용 통제가 실질적으로 이루어지는 곳입니다. 파일 발견, 로그 스캔, 기타 저렴하게 검증 가능한 작업을 Haiku로 라우팅하고, Sonnet 또는 Opus는 추론이 집중적인 단계 — 아키텍처 결정, 모호한 디버깅, 잘못하면 비용이 많이 드는 작업 — 에 예약하세요. Haiku는 Opus보다 토큰당 약 15배 저렴하며, 서브 에이전트가 구축된 소음이 많은 탐색 작업에서 이 격차는 실제 작업 세션 전반에 걸쳐 빠르게 누적됩니다.

탐색, 계획, 실행 패턴

복잡하고 다단계인 작업의 경우, 실제로 견고하게 유지되는 패턴은 탐색(Explore), 계획(Plan), 실행(Execute) — 소음을 생성하는 부분에 저렴한 서브 에이전트를 사용하고, 실제로 중요한 한 곳에서 인간 검토 게이트를 유지하는 것입니다.

사람들이 흔히 반대로 이해하는 핵심 세부 사항은 검토 게이트가 어디에 있어야 하는가입니다. 탐색은 저렴하므로, 먼저 허가를 구하지 않고 서브 에이전트가 자유롭게 읽게 하세요. 계획은 분석적이므로, 에이전트가 자체적으로 접근 방식을 설계하게 하세요. 그러나 모든 에이전트가 파일을 수정하기 전에, 계획을 보고 승인해야 합니다 — 이것이 Claude Code의 계획 모드(permissionMode: plan)의 목적이며, 이는 적용되기 전에 모든 diff를 검토하는 더 넓은 vibe coding 모범 사례와 동일한 원칙입니다.

일반적인 실수

팀이 커스텀 서브 에이전트 작성을 시작하면 몇 가지 실수가 반복적으로 나타납니다:

• 모호한 설명. “코드 도움이 된다"는 표현은 결코 올바르게 라우팅되지 않습니다. 정확한 트리거 조건을 명시하세요.
• 지나치게 광범위한 도구 접근 권한. 읽기 전용 연구 서브 에이전트에게 쓰기 및 bash 접근 권한을 제공하면, 처음부터 만들어야 했던 격리 보장이 무너집니다.
• 의존성 작업의 병렬 처리. 작업 B가 작업 A의 완료된 출력을 필요로 한다면, 순차적으로 실행하세요 — 서브 에이전트는 공유 조정자가 할 수 있는 방식으로 작업 중간에 협상할 수 없습니다. 작업 중간에 에이전트가 서로 소통해야 하는 워크플로우의 경우, 이는 다른 형태의 문제입니다; 단일 리포지토리 워크플로우가 아닌 프로덕션 시스템을 구축 중이라면 멀티 에이전트 조정 패턴을 참조하세요.
• 사소한 작업에 서브 에이전트 사용. “이 JSON 포맷팅” 또는 “이 명령어 하나 실행"에는 새로운 컨텍스트 윈도우가 필요하지 않습니다; 직접 하세요.

작업 예제: 코드 리뷰 서브 에이전트 종단간

비중요한 모든 커밋이 적용되기 전에 검토되기를 원한다고 가정해 봅시다. 앞서 보여준 code-reviewer 정의를 .claude/agents/code-reviewer.md에 넣으세요, 팀 전체가 동일한 리뷰어를 공유하도록 커밋하고, “커밋하기 전에 스테이지된 변경 사항을 검토해 줘"와 같은 자연스러운 요청으로 호출하세요. Claude Code는 요청을 서브 에이전트의 description과 매칭하고, Read, Grep, Glob 접근 권한만 사용하여 시작하며, 파일:라인 참조된 발견 사항과 통과/실패 요약을 반환합니다 — 메인 세션에는 도달하는 과정의 파일별 소음이 전혀 닿지 않습니다.

주석이 달린 메인 트랜스크립트에서 이 모습이 어떻게 보이는지:

You:  review my staged changes before I commit

Main: [dispatches code-reviewer subagent — 6 files read, 1 grep pass,
       zero of it shown here]

Main: code-reviewer findings:
      - auth/session.go:142 — token refresh path doesn't handle expired
        refresh token; falls through to nil dereference
      - auth/session.go:203 — style: error wrapped without %w
      PASS/FAIL: FAIL (1 blocking issue)

6개의 파일 읽기와 1회의 grep 통과가 발생했으며, 메인 세션은 그중 네 줄만 지불했습니다. 이 격차 — 서브 에이전트가 한 모든 일과 실제로 보이는 세 줄의 요약 — 이 바로 한 트랜스크립트에서의 전체 가치 제안입니다.

팀이 Spec-Driven Development 스캐폴딩도 사용하는 경우, 리뷰 서브 에이전트는 검증 단계에 자연스럽게 슬롯됩니다; GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows에서 해당 리뷰 게이트가 휴대용 및 IDE 통합 SDD 설정 간에 어떻게 비교되는지 확인하세요.

커스텀 서브 에이전트 설정이 가치 있는가?

첫날에는 아닙니다. 내장된 범용 서브 에이전트는 이미 단일 YAML 파일도 작성하지 않고 대부분의 탐색 및 연구 위임을 다루며, 단일 탐색-계획-실행 패스는 대부분의 일상 작업에 충분합니다. 동일한 작업을 세 번 수동으로 위임한 후에만 커스텀 .claude/agents/*.md 파일을 작성하세요 — 코드 리뷰어, 테스트 러너 트리아저, 특정 내부 라이브러리를 위한 문서 조회 에이전트 등. 첫 주에 다섯 개의 서브 에이전트를 작성하는 팀은 실제로 트리거 조건이 변경될 때 아무도 업데이트하지 않는 다섯 개의 오래된 description 필드로 끝나게 되며, 이는 몇 달 뒤 자동으로 라우팅을 조용히 깨뜨립니다. 커스텀 서브 에이전트 0개부터 시작하고, 한 번에 하나씩 추가하며, 반복이 — 이론적인 유용성이 아닌 — 그것을 요구할 때만 추가하세요.

알려진 한계

서브 에이전트를 둘러싼 시스템을 구축하기 전에 알아두어야 할 몇 가지 거친 모서리가 있습니다:

• 재귀 위임 불가. 서브 에이전트는 자체 서브 에이전트를 생성할 수 없습니다. 작업이 실제로 두 번째 수준의 위임을 필요로 한다면, 이는 다른 조정 구조가 필요하다는 신호입니다 — 단일 Claude Code 세션 외부에서 이것이 어떻게 보이는지 멀티 에이전트 조정 패턴을 참조하세요.
• 호출 간 기억 부재. 모든 배포는 0부터 시작합니다. 관련 작업에서 5분 전에 동일한 서브 에이전트를 호출했더라도, 서브 에이전트가 마지막 실행을 기억하는 내장 메커니즘은 없습니다.
• 격리는 도구 허용 목록이며, 샌드박스가 아님. Bash 접근 권한을 가진 서브 에이전트는 여전히 다른 도구 호출과 마찬가지로 파일 시스템과 네트워크에 접근할 수 있습니다. tools 제한은 폭발 반경을 줄이지만, 강력한 보안 경계를 생성하지는 않습니다.

문제 해결

서브 에이전트가 절대 트리거되지 않음. 거의 항상 설명이 문제입니다. 일반적인 기능 진술 대신 특정 트리거 조건을 중심으로 다시 작성하고, 파일이 .claude/agents/(프로젝트) 또는 ~/.claude/agents/(개인)에 올바른 확장자와 함께 있는지 다시 확인하세요.

서브 에이전트가 여전히 너무 많은 컨텍스트를 소모함. tools 허용 목록을 확인하세요 — 지나치게 광범위한 도구 세트는 지나치게 광범위한 탐색을 초래합니다. 또한 작업이 하나를 대신에 두 개의 서브 에이전트로 나누어야 하는지 확인하세요.

리스트된 Skill이 서브 에이전트 내부에서 로드되지 않음. Claude Code는 skills 필드에 명명된 누락되거나 비활성화된 Skill을 건너뛰며 실행을 실패하지 않고, 디버그 출력(/debug 메인 세션에서, 이후 배포 재현)에 해당 내용을 로그로 기록합니다 — skill "security-checklist" not found, skipping과 유사합니다. 이후 /doctor를 실행하여 나머지 설정이健全한지 확인하세요.

실행 간 결과가 일관되지 않게 느낌. 이는 종종 모델 라우팅 문제이며, 서브 에이전트 설계 문제가 아닙니다 — 저렴한 모델에 할당된 추론 집중 작업은 더 다양하게 변합니다. Sonnet 또는 Opus로 이동하고, Haiku는 결정론적이고 모호성이 낮은 단계에 유지하세요.

서브 에이전트는 훨씬 더 큰 도구상자의 한 부분입니다; 이 워크플로우에 커밋하기 전에 Claude Code를 AI 개발 도구 생태계의 나머지 부분과 비교 중이라면, 그 개요가 좋은 다음 단계입니다.

유용한 링크

• Claude Code 설치 및 Ollama, llama.cpp, 가격 구성
• Claude Skills 및 개발자를 위한 SKILL.md
• GitHub Spec Kit vs Kiro vs Claude Code SDD 워크플로우
• Vibe Coding이란 무엇인가?
• 멀티 에이전트 조정 패턴: 실용적인 가이드
• Oh My Opencode 전문 에이전트 심층 분석
• AI 개발 도구: 완전 가이드