모두가 Claude Code 내부에서 AI "전문가(specialists)" 군단을 구축하고 있습니다. 하지만 그들 중 대부분은 실행되지 않거나, 서로 충돌하며, 보호하려 했던 바로 그 컨텍스트 윈도우(context window)를 조용히 팽창시킬 뿐입니다. 저는 공식 내장 에이전트, 대규모 커뮤니티 컬렉션, 그리고 제가 직접 만든 것들을 포함하여 100개의 서브에이전트(subagents)를 구축하고 스트레스 테스트를 진행하여, 진정으로 제 역할을 다하는 소수의 에이전트를 찾아냈습니다. 여기 제가 실제로 업무를 위임하는 12개와 삭제한 것들, 그리고 서브에이전트의 진짜 용도에 대한 불편한 진실이 있습니다.

내가 왜 이 토끼굴에 빠졌는가

이런 일을 스스로에게 저지른 것이 벌써 세 번째입니다. 첫 번째는 100 Claude Skills였고, 그다음은 100 MCP servers였습니다. 이제는 서브에이전트(subagents) 차례입니다. 이 세 가지는 Claude Code 스택의 세 가지 기둥입니다. 스킬(Skills)은 에이전트에게 _역량(competence)_을 부여하고, MCP 서버는 _기능(capability)_을 부여하며, 서브에이전트는 _위임(delegation)_을 가능하게 합니다. 저는 이미 두 가지를 다루었습니다. 이 3부작을 완성하려면 세 번째가 필요했습니다.

그리고 서브에이전트는 현재 가장 열기가 뜨거운 분야입니다. GitHub를 열어보면 수백 개의 에이전트가 모인 컬렉션들을 볼 수 있습니다. VoltAgent의 awesome-claude-code-subagents는 10개 카테고리에 걸쳐 154개 이상의 에이전트를 제공하며 22.9k stars를 보유하고 있고, wshobson의 마켓플레이스는 **194개의 에이전트, 158개의 스킬, 16개의 오케스트레이터(orchestrators)**를 묶어 37.5k stars를 기록하고 있습니다. 그 제안은 매우 매혹적입니다. security-auditor, react-specialist, kubernetes-specialist, quant-analyst와 같은 AI 전문가 _팀(team)_을 구성하고, Claude Code가 모든 작업에 적합한 전문가를 파견하도록 하는 것입니다.

그래서 저는 당연한 일을 했습니다. 코드 리뷰, 디버깅(debugging), 테스트 실행, 보안 감사(security audits), 데이터베이스 분석, 장애 대응(incident triage) 등 실제 업무 전반에 걸쳐 100개의 서브에이전트를 설치하고, 연결하고, 실제로 _사용_해 보았습니다. 저는 Claude가 실제로 어떤 에이전트에게 업무를 위임하는지, 어떤 에이전트가 아무런 반응 없이 가만히 있는지, 그리고 어떤 에이전트가 저의 메인 대화를 조용히 _악화_시키는지 지켜보았습니다.

대부분은 삭제되었습니다. 코드가 잘못 작성되었기 때문이 아니라 — 많은 것들이 훌륭했습니다 — 서브에이전트 (subagent)가 무엇을 '위한' 것인지 제가 근본적으로 오해했기 때문입니다. 그 오해를 바로잡는 것이 이 글의 핵심이며, 목록을 소개하기 전에 그 부분부터 다루겠습니다.

이것이 살아남은 최종 후보 명단입니다. 12개의 서브에이전트. 100개 중에서 말이죠.

요약 (TL;DR)

• 서브에이전트는 인격체가 아닙니다. 그것은 컨텍스트 방화벽 (context firewall)입니다. 각 에이전트는 자신만의 격리된 컨텍스트 창 (context window)에서 실행되며, 메인 스레드에는 요약본만을 반환합니다. 실제 가치는 '전문가 페르소나'가 아니라 바로 그 '격리'에 있습니다.
• 서브에이전트가 많을수록 더 나빠집니다. 중복되는 description 필드는 Claude가 잘못된 에이전트에게 작업을 위임하게 하거나(또는 아무에게도 위임하지 않게 함), 아예 위임을 못 하게 만듭니다. 100개의 에이전트가 모인 동물원보다는 정예로 구성된 10개의 에이전트가 더 신뢰성 있게 작동합니다.
• 서브에이전트의 세 가지 진짜 역할: (1) 장황한 출력물 격리, (2) 도구/권한 제한 강제, (3) 행동 특화 — 선택적으로 영구 메모리 (persistent memory) 활용.
• 모델 라우팅 (Model routing)은 비용 조절 레버입니다. 저렴한 작업은 Haiku로, 깊은 추론이 필요한 작업은 Opus로 (또는 가장 긴 호흡의 작업은 Fable로) 라우팅하세요. 잘 구성된 에이전트 함대는 모든 작업을 메인 모델로 실행하는 것보다 훨씬 저렴합니다.
• 아래 소개할 저의 12개 핵심 에이전트는 리뷰, 디버깅, 테스트, 보안, 아키텍처, 성능, 데이터, 문서화, 그리고 오케스트레이션 (orchestration) — 즉, 실제 엔지니어링 작업의 중추를 다룹니다.
• 이것으로 3부작이 완성됩니다: MCP = 능력 (capability), Skills = 역량 (competence), Subagents = 위임 (delegation). 이 세 가지 모두를 관통하는 메타 기술은 동일합니다: 무자비하게 큐레이션하라 (curate ruthlessly).

30초 요약: 서브에이전트란 무엇인가?

A subagent는 Claude Code가 작업을 넘겨줄 수 있는 특화된 조수입니다. 구조적으로는 YAML 프론트매터 (frontmatter)가 포함된 마크다운 (Markdown) 파일입니다:

---
name: code-reviewer
description: 전문 코드 리뷰 전문가. 코드를 작성하거나 수정 직후에 즉시 사용하십시오.
...

이 작은 파일이 강력한 힘을 발휘하는 네 가지 요소가 있으며, 이는 위에서 언급한 세 가지 역할과 정확히 일치합니다:

이 작은 파일은 강력한 힘을 발휘하는 네 가지 요소를 가지고 있으며, 이는 앞에서 언급된 세 가지 역할과 정확히 일치합니다:

1. 독립적인 컨텍스트 윈도우(context window). 이것이 핵심입니다. 서브에이전트는 사용자의 대화 기록, 이미 읽은 파일, 또는 로드한 스킬을 알지 못합니다. 독립적으로 새로 시작하여 작업을 수행하고 요약만 반환합니다. 메인 컨텍스트는 깨끗하게 유지됩니다.
2. 범위가 지정된 도구(Scoped tools). tools 필드는 허용 목록(allowlist)이며 (disallowedTools는 금지 목록, denylist입니다). 검토자에게는 Read, Grep, Glob만 부여되며 파일 편집은 물리적으로 할 수 없습니다. 이는 제안이 아니라 보안 경계입니다.
3. 독립적인 모델(Model). model 필드는 서브에이전트를 sonnet, opus, haiku, fable와 같은 전체 모델 ID로 라우팅합니다. 이것이 비용 조절기 역할을 합니다.
4. 집중된 시스템 프롬프트(Focused system prompt). Markdown 본문이 서브에이전트의 전체 시스템 프롬프트가 됩니다. Claude Code의 기본 설정에 추가되는 것이 아니라, 바로 그 프롬프트입니다. 좁은 전문성, 방해 요소 없음.

위치 (Where they live)

위치	범위	우선순위
관리형 설정(Managed settings)	조직 전체(Organization-wide)	가장 높음 (Highest)
...
Project 서브에이전트는 버전 관리에 속해야 팀 전체가 동일한 검토자에게 위임할 수 있습니다. 그리고 처음부터 직접 작성할 필요는 없습니다. Claude Code에게 작성하도록 요청하면 됩니다 (최근 버전 기준으로, /agents는 정확히 그 작업을 하도록 상기시켜 줍니다). 그런 다음 프론트매터(frontmatter)를 다듬으면 됩니다.

이미 가지고 있는 내장 기능 (The built-ins you already have)

무언가를 설치하기 전에, Claude Code는 사용자를 대신하여 작동하는 서브에이전트를 기본으로 제공합니다:

• Explore — 코드베이스를 검색하고 이해하기 위한 빠르고 읽기 전용(read-only) 에이전트입니다. 저렴하게 유지하기 위해 의도적으로 CLAUDE.md와 git status는 건너뛰며, 모든 검색 결과 출력을 메인 컨텍스트에 포함하지 않습니다.
• Plan — 계획을 제안하기 전에 컨텍스트를 수집하는 데 사용되는 읽기 전용 연구 에이전트입니다.
• general-purpose — 탐색과 행동 모두가 필요한 복잡하고 다단계적인 작업을 위한 만능 에이전트입니다.

만약 Plan 모드를 사용했거나 Claude가

우회로: 서브에이전트(Subagents)에 대한 불편한 진실

제가 언급했던 오해가 바로 이것입니다. 과거의 저를 포함한 대부분의 사람들은 서브에이전트를 하나의 '캐릭터(character)', 즉 성격과 직함을 가진 작은 AI 전문가로 생각합니다. 이러한 사고 모델 아래에서는 에이전트가 많을수록 = 전문성이 높아질수록 = 더 낫다고 믿게 됩니다. 그래서 154개의 에이전트 모음을 설치하고 마치 회사를 고용한 것 같은 기분을 느낍니다.

하지만 그 모델은 틀렸으며, 바로 그 점 때문에 그러한 설치 방식들이 실망을 안겨주는 것입니다. 서브에이전트의 진정한 산출물은 성격이 아니라 컨텍스트 격리 (context isolation)입니다.

테스트 스위트 (test suite)를 실행하거나, 세 페이지 분량의 API 문서를 가져오거나, 거대한 모노레포 (monorepo)를 grep 할 때 실제로 어떤 일이 일어나는지 생각해 보십시오. 그 모든 장황한 출력물들이 메인 대화창을 뒤덮어, 당신이 실제로 신경 써야 할 내용들을 밀어내고 모델의 집중력을 저하시킵니다. 이를 서브에이전트에게 위임하면 그 혼란은 그것의 컨텍스트 창 (context window) 안에 머물게 되며, 당신은 단 두 줄의 요약본을 돌려받게 됩니다. 서브에이전트가 가치 있는 이유는 그것이 'QA 전문가'이기 때문이 아닙니다. 그것이 5,000 토큰에 달하는 테스트 쓰레기 데이터를 당신의 메인 스레드로부터 차단하는 방화벽 (firewall) 역할을 하기 때문입니다.

이 점을 내재화하고 나면, 100개의 에이전트 동물원이 가진 실패 모드 (failure modes)가 명확해집니다:

• 설명 충돌 (Description collisions). Claude는 당신의 작업과 각 에이전트의 description 필드를 매칭하여 어떤 서브에이전트를 사용할지 결정합니다. 모호하고 중복되는 설명을 가진 에이전트 15개를 설치하면, 라우터 (router)는 잘못된 것을 선택하거나, 더 나쁜 경우에는 아무것도 선택하지 못하고 인라인 (inline)으로 작업을 수행해 버립니다. 명확한 설명 10개가 모호한 설명 100개보다 언제나 낫습니다.
• 컨텍스트 역풍 (Context blowback). 서브에이전트를 훌륭하게 만드는 바로 그 기능 — 결과를 메인 스레드로 반환하는 것 — 이 규모가 커지면 당신에게 불리하게 작용합니다. 각각 상세한 보고서를 반환하는 6개의 병렬 연구 에이전트를 생성한다면, 당신은 보호하려고 했던 컨텍스트에 방금 6개의 보고서를 쏟아부은 셈이 됩니다.
• 페르소나 세금 (The persona tax).

서브에이전트(subagents)를 통해 실제 가치를 창출하는 팀은 가장 많은 인원을 보유한 팀이 아닙니다. 그들은 각각 날카로운 설명(description), 최소한의 도구(tools), 그리고 해당 작업을 수행할 수 있는 가장 저렴한 모델을 갖춘 소수의 '컨텍스트 방화벽(context firewalls)'을 구축한 팀입니다. 핵심 기술은 제가 Skills 및 MCP 관련 글에서 언급했던 것과 동일합니다. 바로 무자비하게 큐레이션(curate ruthlessly)하는 것입니다. 빼는 것이 게임의 전부입니다.

이러한 관점에서, 컨텍스트를 사용할 가치가 있는 12개를 소개합니다.

100개의 서브에이전트를 평가한 방법

각 서브에이전트는 다섯 가지 축을 기준으로 점수를 매겼습니다.

1. 트리거 정밀도 (Trigger precision) — Claude가 적절한 순간에 작업을 위임하고, 그렇지 않을 때는 내버려 두는가? (이는 description에 의해 결정됩니다.)
2. 컨텍스트 경제성 (Context economy) — 장황한 작업을 격리함으로써 메인 스레드(main-thread)의 컨텍스트를 절약하는가, 아니면 거대한 보고서를 다시 쏟아붓는가?
3. 도구 위생 (Tool hygiene) — 최소한으로 필요한 권한만 가지는가? 리뷰어(reviewer)가 Write 권한을 가질 이유는 없습니다.
4. 모델 적합성 (Model fit) — 작업을 잘 수행하면서도 가장 저렴한 모델로 라우팅되는가?
5. 실제 주간 업무 적합성 (Real weekly fit) — 직함의 이력서 같은 것이 아니라, 제가 실제로 수행하는 업무와 매칭되는가?

두 개 이상의 축에서 3/5점 미만을 받은 항목은 모두 제외되었습니다. 이 과정에서 제가 시도했던 것의 약 80%가 탈락했습니다. 여기에는 실제로는 메인 모델이 이미 충분히 잘 처리하는 거의 모든 초특화된 "언어 전문가(language specialist)"들이 포함되었습니다.

유지할 가치가 있는 12개의 Claude Code 서브에이전트 (순위별)

1. code-reviewer — 매일 제값을 하는 에이전트

읽기 전용(Read-only) · Sonnet · 모든 변경 사항 이후 실행

가장 전형적인 서브에이전트이며, 모든 진지한 컬렉션이 그만한 이유가 있어 포함하는 에이전트입니다. git diff를 실행하고, 수정된 파일에 집중하며, 우선순위(critical / warnings / suggestions)에 따라 정리된 피드백을 반환합니다. 결정적으로 이 에이전트는 **읽기 전용(read-only)**입니다. Read, Grep, Glob, Bash 권한만 가지며 Write나 Edit 권한은 없습니다. 따라서 리뷰 도중에 "도움이 되겠다며" 코드를 멋대로 다시 쓰는 일 없이 비평만 수행합니다. description을 "코드를 작성하거나 수정한 직후에 즉시 사용(use immediately after writing or modifying code)"으로 설정하면, Claude가 별도의 요청 없이도 선제적으로 작업을 위임합니다.

사용 시점: 의미 있는 변경 후, PR을 열기 전에. 이 서브에이전트는 제가 가장 먼저 설치할 것입니다.

2. debugger — 증상이 아닌 근본 원인 파악

읽기 + 편집 · 상속 · 실패 및 스택 트레이스용

리뷰어가 읽기 전용(read-only)일 때, 디버거는 편집(Edit) 권한을 갖습니다. 왜냐하면 버그를 수정하는 것은 코드를 변경하는 것을 의미하기 때문입니다. 이 서브에이전트의 프롬프트는 실제 워크플로우를 인코딩합니다: 오류와 스택 트레이스를 캡처하고, 실패 지점을 격리하며, 가설을 수립 및 테스트하고, 최소한의 수정 사항을 구현하며, 검증하는 것입니다. 이 서브에이전트의 가치는 바로 규율(discipline)입니다. 단순히 증상에 패치를 붙이는 대신 근본적인 원인을 추적하며, 모든 잡다한 로그 분석 작업(log-spelunking)을 자체 컨텍스트 내에 유지합니다.

사용 시점: 테스트가 실패하거나, 예외가 급증하거나, 동작이 엉뚱하게 흘러갈 때, 단순히 임시방편이 아니라 왜 그런지 알고 싶을 때.

3. test-runner — 가장 순수한 컨텍스트 방화벽

Bash + 읽기 · 하이쿠 또는 소네트 · 장황한 출력을 격리

이 서브에이전트는 전체 논지를 가장 잘 구현합니다. 테스트 스위트를 실행하면 메인 스레드에서 원하지 않는 엄청난 양의 출력이 생성됩니다. 사용자는 _

사용 시점: 인증(auth) 검토, 신뢰할 수 없는 입력(untrusted input) 처리, 보안 민감 사항을 배포하기 전.