대부분의 Claude Code 세션이 느려지고 지저분해지는 이유는 동일합니다. 모든 탐색적 grep, 모든 로그 덤프, 그리고 모든 "파일 하나만 더 확인해 볼게요"라는 요청이 메인 대화(main conversation)에 영원히 남아 있기 때문입니다.

서브에이전트(Subagents)는 바로 그 문제를 해결하기 위해 존재합니다. 이는 Claude Code에 내장된 에이전트 프리미티브(agent primitives) 중 하나로, 소음이 많고 병렬화 가능한 작업을 처리하기 위한 것입니다. 즉, 혼란스러운 작업을 격리된 창으로 밀어 넣고 중요한 요약 정보만을 다시 가져오는 방법입니다.

서브에이전트는 더 똑똑한 Claude가 아니며, 스킬(Skill)과도 같은 것이 아닙니다. 서브에이전트는 자체적인 컨텍스트 윈도우(context window), 자체적인 도구 허용 목록(tool allowlist)을 가진 별도의 추론 에이전트이며, 사용자가 명시적으로 포크(fork)하지 않는 한 현재 대화에 대한 기억이 없습니다. 이 차이를 이해하는 것이 컨텍스트 예산(context budget)을 조용히 절약해 주는 서브에이전트 설정과, 아무런 이득 없이 지연 시간(latency)만 추가하는 설정 사이의 차이를 만듭니다.

서브에이전트(Subagents) vs 스킬(Skills) vs MCP

Claude Code는 서로 다른 문제를 해결하는 세 가지 확장 지점(extension points)을 제공하며, 이 세 가지 모두 기술적으로 "작업을 도와줄 수" 있기 때문에 끊임없이 혼동되곤 합니다.

유용한 경험 법칙(rule of thumb)은 다음과 같습니다: 훅(hook)은 결정론적으로 엄격한 제약 조건을 강제하고, 스킬(Skill)은 메인 에이전트에게 인라인(inline)으로 능력을 부여하며, 서브에이전트(subagent)는 위임하고 메인 컨텍스트에서 완전히 제외하고 싶은 작업을 위한 것입니다. 만약 스킬의 역할이 아직 존재하지 않는 도구를 오케스트레이션(orchestrate)하는 것이라면, 그것은 대개 서브에이전트가 아니라 MCP 서버가 필요하다는 신호입니다. Claude Code만 이런 구조를 가진 것은 아닙니다. OpenCode의 생태계에도 이와 유사한 개념인 특화된 에이전트(specialised agents)가 있어, 계획(planning), 조사(research), 검토(review)를 유사한 방식으로 전담 역할에 따라 분리합니다.

서브에이전트(subagent)의 실제 정의

Claude Code 서브에이전트는 세 가지 속성으로 정의되며, 이 세 가지 모두 사용 방식에 있어 중요합니다.

• 격리된 컨텍스트 (Isolated context). 서브에이전트는 새로운 창(fresh window)에서 시작합니다. 사용자가 명시적으로 포크(fork)하지 않는 한 이전 대화 기록을 볼 수 없으며, 이를 통해 세 번 전의 대화 내용이 출력 결과에 혼입(polluted)되는 것을 방지합니다.
• 제한된 도구 허용 목록 (A restricted tool allowlist). 서브에이전트는 부모 세션이 이미 보유한 도구 중 일부만 사용할 수 있습니다. 스스로 새로운 기능을 부여할 수 없으며, 잘 설계된 서브에이전트는 작업에 필요한 도구만 할당받아야 합니다 (예: 조사 에이전트의 경우 읽기 전용 도구만 할당).
• 서브에이전트 간 가시성 부재 (No cross-subagent visibility). 서브에이전트는 서로의 진행 중인 작업을 볼 수 없습니다. 만약 작업 B가 작업 A의 출력을 진정으로 필요로 한다면, 이는 순차적 의존성(sequential dependency)이지 두 서브에이전트 간에 병렬화(parallelize)할 수 있는 작업이 아닙니다.

서브에이전트를 사용해야 하는 트리거는 "이 작업이 어렵다"가 아닙니다. 그것은 "이 작업이 노이즈가 많다(noisy)"입니다. 즉, 중간 결과물(수십 번의 파일 읽기, 긴 로그, 전체 리포지토리에 대한 탐색적 grep 등)이 많이 생성되지만, 그 중간 자료들이 다음 대화 턴까지 유지될 필요가 없는 종류의 작업을 의미합니다.

서브에이전트 사용 시점 (및 사용하지 말아야 할 때)

적합한 경우: 대규모 변경 전의 코드베이스 탐색(codebase exploration), 통과/실패 여부 및 실패 요약만 확인하면 되는 자동화된 테스트 실행, 보안 또는 스타일 리뷰, 그리고 원본 출력이 메인 세션을 가득 채울 수 있는 모든 다단계 조사 작업.

부적합한 경우: 2초 내외의 짧은 조회("이 함수는 무엇을 반환하는가"), 긴밀한 피드백(back-and-forth)을 통한 정교화가 필요한 모든 작업, 그리고 두 번째 작업이 첫 번째 작업의 답변을 필요로 함에도 불구하고 무리하게 "병렬화"하려는 의존적 작업. 사소한 조회를 위해 서브에이전트를 사용하는 것은 실질적인 격리 이점 없이 새로운 컨텍스트 창을 띄우는 오버헤드만 추가할 뿐입니다.

효용 측정: 컨텍스트 및 비용 계산

서브에이전트(subagents)의 가치는 실제 작업에 숫자를 대입해 보기 전까지는 추상적입니다. 흔한 사례를 들어보겠습니다. 약 500개의 파일로 구성된 서비스에서 더 이상 사용되지 않는(deprecated) 설정 키가 여전히 읽히는 모든 지점을 grep으로 찾고, 정확한 파일:줄(file:line) 일치 항목을 보고하는 작업입니다.

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

비용 측면에서도 동일한 원리가 적용됩니다. Claude Code 가격 분석의 가격을 기준으로, 동일한 탐색 과정을 Opus(입력 $5/MTok, 출력 $25/MTok)로 실행하면 약 40K의 입력 토큰만으로도 대략 $0.20~$0.25가 소요됩니다. 이를 Haiku(입력 $1/MTok, 출력 $5/MTok)로 라우팅하면 $0.04~$0.05로 떨어집니다. 또한 메인 세션은 오직 ~2K 토큰의 요약본만 보기 때문에, 탐색 과정에서 발생한 토큰이 메인 세션의 Opus 예산을 전혀 건드리지 않습니다.

커스텀 서브에이전트 정의하기

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

---
name: code-reviewer
description: >
...

description 필드는 파일에서 가장 중요한 줄입니다. 이는 부모 세션(parent session)의 라우팅 로직이 이 서브에이전트가 현재 작업에 적합한지 결정하기 위해 읽는 정보입니다. 채용 공고를 쓰듯이 작성하세요. 단순히 "코드 작성을 도와줌"과 같이 모호하게 적지 말고, 트리거 조건(trigger condition)을 명시적으로 작성해야 합니다. 모호한 설명은 자동 배정(automatic dispatch) 과정에서 무시되거나 잘못 적용될 수 있습니다.

tools 필드는 격리 경계 (isolation boundary) 역할을 합니다. 리서치 서브에이전트(research subagent)에게는 Read, Grep, Glob만 부여하고 그 외의 것은 주지 마십시오. 사용 가능한 모든 도구를 부여하는 것은 제한된 샌드박스 (sandbox) 내에서 실행하는 목적 자체를 무색하게 만듭니다. 선택 사항인 skills 필드는 지정된 스킬 (Skills)의 전체 내용을 서브에이전트의 시작 컨텍스트 (startup context)에 미리 로드합니다. 이는 서브에이전트가 작업 중간에 지식을 발견하고 로드하는 데 턴 (turn)을 소비하지 않고도 도메인 지식 (domain knowledge)을 필요로 할 때 유용합니다.

모델 라우팅 (Model routing): 단순 작업에는 저렴한 모델을 사용하세요

서브에이전트는 비용 제어 (cost control)가 실제로 이루어지는 지점이기도 합니다. 파일 탐색, 로그 스캐닝 및 기타 검증 비용이 저렴한 작업은 Haiku로 라우팅하고, 아키텍처 결정, 모호한 디버깅, 틀렸을 때의 비용이 큰 작업 등 추론 집약적인 단계에는 Sonnet 또는 Opus를 예약해 두십시오. Haiku는 토큰당 Opus보다 대략 15배 저렴하며, 서브에이전트가 구축된 목적과 같은 노이즈가 많은 탐색 과정에서는 실제 작업 세션 전반에 걸쳐 그 차이가 빠르게 누적됩니다.

Explore, Plan, Execute 패턴

복잡하고 다단계인 작업을 수행할 때, 실무에서 유효한 패턴은 Explore, Plan, Execute입니다. 노이즈를 생성하는 부분에는 저렴한 서브에이전트를 사용하고, 인간의 검토 게이트 (human review gate)는 실제로 중요한 단 한 곳에만 유지하는 방식입니다.

sequenceDiagram
    participant You
    participant Main as Main session
...

사람들이 거꾸로 이해하는 핵심적인 디테일은 검토 게이트 (review gate)가 어디에 위치해야 하는가입니다. 탐색 (Exploration)은 비용이 저렴하므로, 서브에이전트가 먼저 허가를 요청하지 않고 자유롭게 읽도록 두십시오. 계획 (Planning)은 분석적인 과정이므로, 에이전트가 스스로 접근 방식을 설계하도록 두십시오. 하지만 어떤 에이전트라도 파일을 수정하기 전에는 계획을 확인하고 승인해야 합니다. 이것이 바로 Claude Code의 계획 모드 (permissionMode: plan)의 용도이며, 모든 디프 (diff)가 반영되기 전에 검토해야 한다는 더 넓은 범위의 vibe coding best practices에서 논의되는 원칙과 동일합니다.

흔한 실수

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

• 모호한 설명 (Vague descriptions). "코드를 도와줌"과 같은 설명은 결코 올바르게 라우팅(routing)되지 않습니다. 정확한 트리거 조건(trigger condition)을 명시하세요.
• 지나치게 광범위한 도구 권한 (Over-broad tool access). 읽기 전용(read-only) 리서치 서브에이전트에게 쓰기(write) 및 bash 권한을 부여하는 것은, 애초에 서브에이전트를 만들 가치가 있었던 격리(isolation) 보장을 무너뜨리는 행위입니다.
• 의존적인 작업의 병렬화 (Parallelizing dependent tasks). 만약 작업 B가 작업 A의 완료된 출력을 필요로 한다면, 작업을 순차적으로 실행하세요. 서브에이전트는 공유된 오케스트레이터(orchestrator)처럼 작업 중간에 서로를 조정할 수 없습니다. 작업 중간에 에이전트 간의 대화가 진정으로 필요한 워크플로우는 문제의 형태가 다릅니다. 단일 리포지토리(single-repo) 워크플로우가 아닌 프로덕션 시스템을 구축 중이라면 멀티 에이전트 오케스트레이션 패턴 (multi-agent orchestration patterns)을 참조하세요.
• 사소한 작업에 서브에이전트 사용 (Using a subagent for trivial work). "이 JSON을 포맷해줘" 또는 "이 명령어를 하나 실행해줘"와 같은 작업은 새로운 컨텍스트 윈도우(context window)가 필요하지 않습니다. 그냥 직접 수행하세요.

실제 사례: 코드 리뷰 서브에이전트 엔드 투 엔드 (end to end)

모든 중요도가 있는 커밋(commit)이 반영되기 전에 리뷰를 거치게 하고 싶다고 가정해 봅시다. 앞서 보여준 code-reviewer 정의를 .claude/agents/code-reviewer.md에 넣고 커밋하여 팀 전체가 동일한 리뷰어를 공유하게 만드세요. 그다음 "커밋하기 전에 스테이징된 변경 사항을 리뷰해줘"와 같은 자연스러운 요청으로 이를 호출합니다. Claude Code는 사용자의 요청을 서브에이전트의 description과 대조하고, Read, Grep, Glob 권한만 가진 상태로 서브에이전트를 실행합니다. 그러면 서브에이전트는 파일:라인(file:line)이 참조된 결과와 통과/실패(pass/fail) 요약을 가지고 돌아옵니다. 이 과정에서 발생하는 파일별 노이즈는 메인 세션(main session)에 전혀 영향을 주지 않습니다.

주석이 달린 메인 트랜스크립트(transcript)에서의 모습은 다음과 같습니다:

사용자: 커밋하기 전에 스테이징된 변경 사항을 리뷰해줘

메인: [code-reviewer 서브에이전트 배정 — 6개 파일 읽음, 1개 grep 통과,
...

6개의 파일 읽기와 1개의 grep 통과가 발생했지만, 사용자의 메인 세션은 정확히 그중 4줄에 대해서만 비용을 지불했습니다. 서브에이전트가 수행한 모든 작업과 사용자가 실제로 보는 3줄 요약 사이의 그 격차 — 이것이 바로 하나의 트랜스크립트가 제공하는 전체 가치 제안(value proposition)입니다.

만약 귀하의 팀이 명세 기반 개발 (Spec-Driven Development, SDD) 스캐폴드 (scaffolds)를 사용하고 있다면, 리뷰 서브에이전트 (review subagent)는 검증 (validation) 단계에 자연스럽게 배치됩니다. 이 리뷰 게이트 (review gate)가 이식 가능한 (portable) SDD 설정과 IDE 통합형 SDD 설정 간에 어떻게 비교되는지는 GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows를 참조하십시오.

커스텀 서브에이전트를 설정할 가치가 있을까요?

첫날부터 그럴 필요는 없습니다. 내장된 범용 서브에이전트 (general-purpose subagent)가 이미 단 하나의 YAML 파일도 작성하지 않고도 대부분의 탐색 (exploration) 및 조사 (research) 위임 (delegation)을 처리하며, 대부분의 일상적인 업무에는 단 한 번의 탐색-계획-실행 (Explore-Plan-Execute) 패스 (pass)만으로도 충분합니다. 커스텀 .claude/agents/*.md 파일을 작성하는 것은 동일한 작업을 수동으로 세 번 위임했을 때 — 예를 들어 코드 리뷰어 (code reviewer), 테스트 실행기 분류기 (test-runner triager), 특정 내부 라이브러리를 위한 문서 조회 에이전트 (docs-lookup agent) 등 — 비로소 고려하십시오. 첫 주에 5개의 서브에이전트를 작성하는 팀은 대개 실제 트리거 조건 (trigger condition)이 변할 때 아무도 업데이트하지 않는 5개의 오래된 description 필드를 갖게 되며, 이는 몇 달 후 자동 라우팅 (automatic routing)을 조용히 망가뜨립니다. 커스텀 서브에이전트 없이 시작하여, 이론적인 유용성이 아닌 반복성 (repetition)이 요구될 때 한 번에 하나씩 추가하십시오.

알려진 제한 사항

서브에이전트를 기반으로 구축하기 전에 알아두어야 할 몇 가지 미흡한 점들이 있습니다:

• 재귀적 위임 불가 (No recursive delegation). 서브에이전트는 자체적인 서브에이전트를 생성할 수 없습니다. 만약 작업에 진정으로 두 번째 계층의 위임이 필요하다면, 이는 다른 오케스트레이션 형태 (orchestration shape)가 필요하다는 신호입니다. 단일 Claude Code 세션 외부에서의 모습은 멀티 에이전트 오케스트레이션 패턴 (multi-agent orchestration patterns)을 참조하십시오.
• 호출 간 메모리 공유 불가 (No memory across invocations). 모든 디스패치 (dispatch)는 0에서 시작합니다. 설령 5분 전에 관련 작업으로 동일한 서브에이전트를 호출했더라도 마찬가지입니다. 서브에이전트가 자신의 마지막 실행을 기억하도록 하는 내장된 메커니즘은 없습니다.
• 격리는 툴 허용 목록 (tool allowlist)이지, 샌드박스 (sandbox)가 아닙니다. Bash 접근 권한이 있는 서브에이전트는 다른 툴 호출과 마찬가지로 파일 시스템과 네트워크에 접근할 수 있습니다. tools를 제한하는 것은 영향 범위 (blast radius)를 줄이는 것이지, 강력한 보안 경계 (security boundary)를 만드는 것이 아닙니다.

문제 해결 (Troubleshooting)

서브에이전트가 전혀 트리거되지 않음. 거의 항상 설명 (description)이 문제입니다. 일반적인 능력에 대한 진술 대신 구체적인 트리거 조건에 맞춰 설명을 다시 작성하십시오. 또한 해당 파일이 올바른 확장자와 함께 .claude/agents/ (프로젝트) 또는 ~/.claude/agents/ (개인)에 존재하는지 다시 확인하십시오.

서브에이전트가 여전히 너무 많은 컨텍스트 (context)를 소모함. tools 허용 목록을 확인하십시오. 지나치게 광범위한 툴 세트는 지나치게 광범위한 탐색을 유도합니다. 또한 하나의 서브에이전트가 모든 것을 수행하는 대신, 작업을 두 개의 서브에이전트로 나누었어야 했는지도 확인하십시오.