들어가며 — 혼자서 다 하던 에이전트, 이제 팀을 꾸린다

지난 4편(상)에서 우리는 Hooks를 통해 에이전트의 행동을 어디서 끊고, 어디서 통과시킬 것인가를 정밀하게 제어하는 방법을 살펴봤습니다. Hooks가 에이전트의 ‘신호등’이었다면, 오늘 다룰 Subagents는 에이전트의 ‘조직도’입니다. 하나의 Claude Code 세션 안에서 역할이 다른 여러 에이전트를 동시에 운용하고, 각자의 전문성을 살려 복잡한 작업을 분할 정복하는 구조 — 이것이 멀티 에이전트 오케스트레이션의 핵심입니다.

이번 글에서는 Named Subagents의 설계 원칙부터, 컨텍스트 격리 전략, 실전 오케스트레이션 패턴, 그리고 지난 편에서 배운 SubagentStop 훅과의 결합까지 한 번에 정리합니다.

Subagent란 무엇인가 — 기본 개념 정리

메인 에이전트와 서브 에이전트의 관계

Claude Code에서 Subagent는 메인 에이전트(사용자와 직접 대화하는 최상위 에이전트)가 특정 작업을 위임하기 위해 생성하는 독립적인 실행 컨텍스트입니다. 일반적인 함수 호출과 근본적으로 다른 점은, 서브 에이전트가 자체적인 시스템 프롬프트, 도구 세트, 모델 설정을 가진 별도의 페르소나로 동작한다는 것입니다.

기존에도 Claude Code는 내부적으로 서브 에이전트를 활용해왔습니다. 예를 들어 Explore 타입의 서브 에이전트는 코드베이스 탐색에 특화된 읽기 전용 에이전트로, 메인 에이전트의 컨텍스트를 소비하지 않으면서 파일 구조를 파악합니다. 하지만 2025년 하반기부터 도입된 Named Subagents는 이 개념을 한 차원 끌어올립니다. 사용자가 직접 서브 에이전트의 역할, 도구, 모델, 프롬프트를 정의할 수 있게 된 것입니다.

왜 서브 에이전트가 필요한가

단일 에이전트로 모든 것을 처리하는 방식에는 분명한 한계가 있습니다.

• 컨텍스트 오염: 코드 리뷰, 테스트 작성, 리서치를 하나의 세션에서 순차 수행하면, 앞선 작업의 맥락이 뒤 작업의 판단을 왜곡할 수 있습니다.
• 도구 과잉: 모든 도구를 한 에이전트에 열어두면 의도치 않은 부작용(예: 리서치 중 파일 수정)이 발생할 수 있습니다.
• 비용 비효율: 간단한 확인 작업에도 전체 컨텍스트를 로드하면 토큰 낭비가 심합니다.
• 역할 충돌: “코드를 작성한 에이전트가 자기 코드를 리뷰”하는 것은 인간 조직에서도 피하는 패턴입니다.

서브 에이전트는 이 모든 문제를 관심사의 분리(Separation of Concerns) 원칙으로 해결합니다.

Named Subagents 설계의 4축

Named Subagent를 정의할 때 고려해야 할 네 가지 축이 있습니다. 이 네 축의 조합이 서브 에이전트의 성격과 능력 범위를 결정합니다.

1축: 역할(Role) — “너는 누구인가”

역할은 서브 에이전트의 정체성을 정의합니다. 단순한 이름표가 아니라, 해당 에이전트가 어떤 관점에서 문제를 바라보고, 어떤 기준으로 판단할지를 결정하는 프레임입니다.

좋은 역할 정의의 핵심은 명확한 경계입니다. “코드를 잘 짜는 에이전트”보다 “TypeScript 타입 안전성을 검증하는 정적 분석 전문가”가 훨씬 효과적입니다. 역할이 구체적일수록 에이전트의 출력 품질이 올라갑니다.

settings.json 또는 .claude/settings.json에서 Named Subagent를 정의하는 기본 구조를 살펴보겠습니다.

{
  "namedSubagents": {
    "reviewer": {
      "description": "코드 리뷰 전문가. 버그, 보안 취약점, 성능 이슈를 찾아낸다.",
      "systemPrompt": "당신은 시니어 코드 리뷰어입니다. 코드를 읽고 버그, 보안 취약점, 성능 병목, 가독성 문제를 식별하세요. 수정은 하지 말고 발견 사항만 보고하세요.",
      "allowedTools": ["Read", "Grep", "Glob", "Agent"],
      "model": "claude-sonnet-4-6"
    }
  }
}

역할 정의 시 흔히 저지르는 실수들이 있습니다.

• 역할 과잉: “리뷰도 하고 수정도 하고 테스트도 작성하는” 만능 서브 에이전트는 메인 에이전트와 다를 바 없습니다.
• 역할 중첩: “보안 리뷰어”와 “코드 품질 리뷰어”의 경계가 모호하면 같은 파일에 대해 중복 피드백이 발생합니다.
• 역할 부재: description만 있고 systemPrompt가 없으면 에이전트가 범용적으로 동작합니다.

2축: 허용 도구(Allowed Tools) — “너는 무엇을 할 수 있는가”

허용 도구는 서브 에이전트의 행동 반경을 결정합니다. 이것은 단순한 기능 제한이 아니라 안전 경계입니다.

Claude Code에서 사용 가능한 주요 도구들을 역할별로 분류하면 다음과 같습니다.

• 읽기 전용: Read, Grep, Glob — 코드 탐색, 리서치, 리뷰 역할에 적합
• 쓰기: Edit, Write — 코드 작성, 수정 역할에 필요
• 실행: Bash — 빌드, 테스트, 배포 역할에 필요하지만 위험도 높음
• 위임: Agent — 다른 서브 에이전트를 호출하는 오케스트레이터 역할
• MCP 도구: mcp__서버명__도구명 — 외부 서비스 연동 역할

도구 제한의 핵심 원칙은 최소 권한(Least Privilege)입니다. 리뷰어에게 Edit 권한을 주면 “리뷰하다가 직접 고치는” 상황이 발생합니다. 테스터에게 Write 권한을 주면 테스트 파일을 생성할 수 있지만, 소스 코드도 수정할 수 있게 됩니다. 도구 목록을 설계할 때는 항상 “이 도구가 없으면 역할 수행이 불가능한가?”를 기준으로 판단하세요.

{
  "namedSubagents": {
    "tester": {
      "description": "테스트 전문가. 기존 테스트를 실행하고 누락된 테스트 케이스를 제안한다.",
      "systemPrompt": "당신은 QA 엔지니어입니다. 코드 변경사항에 대해 기존 테스트를 실행하고, 누락된 엣지 케이스를 식별하세요. 테스트 코드 작성이 필요하면 제안만 하세요.",
      "allowedTools": ["Read", "Grep", "Glob", "Bash"],
      "model": "claude-sonnet-4-6"
    },
    "researcher": {
      "description": "기술 리서처. 코드베이스를 탐색하여 관련 패턴과 선례를 찾는다.",
      "allowedTools": ["Read", "Grep", "Glob"],
      "model": "claude-haiku-4-5-20251001"
    }
  }
}

3축: 모델(Model) — “너의 두뇌는 어떤 수준인가”

모든 서브 에이전트가 최고 성능의 모델을 사용할 필요는 없습니다. 오히려 역할에 맞는 모델을 배정하는 것이 비용 효율과 속도 모두에서 유리합니다.

모델 선택의 실전 가이드라인은 다음과 같습니다.

• Opus 4.6 (claude-opus-4-6): 복잡한 아키텍처 결정, 미묘한 버그 추적, 대규모 리팩토링 계획 — 메인 에이전트나 오케스트레이터에 적합
• Sonnet 4.6 (claude-sonnet-4-6): 코드 리뷰, 테스트 작성, 중간 수준의 코딩 — 대부분의 서브 에이전트에 적합
• Haiku 4.5 (claude-haiku-4-5-20251001): 파일 검색, 패턴 매칭, 단순 확인 — 리서처나 검증자에 적합

비용 차이는 상당합니다. Opus 대비 Sonnet은 약 1/5, Haiku는 약 1/30 수준입니다. 10번의 서브 에이전트 호출 중 7번을 Haiku로 처리할 수 있다면, 전체 비용을 60% 이상 절감할 수 있습니다.

그렇다고 무조건 저렴한 모델을 쓰라는 뜻은 아닙니다. 모델 수준이 역할의 판단 복잡도에 못 미치면 오히려 재호출이 발생하여 비용이 더 들 수 있습니다. 보안 리뷰처럼 미묘한 판단이 필요한 역할에 Haiku를 배정하면, 놓치는 취약점이 생기고 결국 메인 에이전트가 다시 검토해야 합니다.

4축: 시스템 프롬프트(System Prompt) — “너는 어떻게 행동하는가”

시스템 프롬프트는 서브 에이전트의 행동 규범입니다. 역할이 “누구인가”를 정의한다면, 시스템 프롬프트는 “어떻게 일하는가”를 정의합니다.

효과적인 시스템 프롬프트의 구성 요소를 정리하면 다음과 같습니다.

• 페르소나 선언: “당신은 ~입니다”로 시작하여 관점을 고정
• 작업 범위: 무엇을 해야 하고, 무엇을 하지 말아야 하는지 명시
• 출력 형식: 결과를 어떤 구조로 반환할지 지정 (JSON, Markdown 등)
• 판단 기준: 애매한 상황에서 어떤 방향으로 결정할지 가이드
• 에스컬레이션 조건: 자신의 역할을 벗어나는 문제를 발견했을 때 어떻게 보고할지

{
  "namedSubagents": {
    "security-auditor": {
      "description": "보안 감사관. OWASP Top 10 기준으로 코드를 검사한다.",
      "systemPrompt": "당신은 애플리케이션 보안 전문가입니다.\n\n## 검사 범위\n- SQL Injection, XSS, CSRF, SSRF 등 OWASP Top 10 취약점\n- 하드코딩된 시크릿, 약한 암호화, 불안전한 역직렬화\n- 의존성의 알려진 CVE\n\n## 출력 형식\n각 발견 사항을 다음 형식으로 보고하세요:\n- 심각도: Critical / High / Medium / Low\n- 위치: 파일:라인\n- 설명: 무엇이 왜 위험한지\n- 권고: 어떻게 수정해야 하는지\n\n## 행동 규칙\n- 코드를 절대 수정하지 마세요\n- 확실하지 않은 취약점도 보고하되, 확신 수준을 명시하세요\n- 민감한 값(API 키, 비밀번호)을 출력에 포함하지 마세요",
      "allowedTools": ["Read", "Grep", "Glob"],
      "model": "claude-sonnet-4-6"
    }
  }
}

좋은 시스템 프롬프트의 길이는 보통 200~800 토큰 사이입니다. 너무 짧으면 행동이 모호해지고, 너무 길면 핵심 지시가 묻힐 수 있습니다.

컨텍스트 격리의 메커니즘과 비용 분석

컨텍스트 격리란 무엇인가

서브 에이전트의 가장 중요한 특성 중 하나는 메인 에이전트와 컨텍스트가 격리된다는 점입니다. 이것이 단순 함수 호출과의 결정적 차이입니다.

격리의 의미를 구체적으로 풀어보겠습니다.

• 대화 이력 분리: 서브 에이전트는 메인 에이전트의 이전 대화를 볼 수 없습니다. 메인 에이전트가 명시적으로 전달한 정보만 알 수 있습니다.
• 도구 호출 이력 분리: 서브 에이전트의 도구 호출 결과는 서브 에이전트의 컨텍스트에만 존재합니다. 메인 에이전트는 서브 에이전트가 반환한 최종 결과만 받습니다.
• 시스템 프롬프트 분리: 서브 에이전트는 자신만의 시스템 프롬프트로 동작합니다. 메인 에이전트의 CLAUDE.md 지시와 독립적입니다(단, 글로벌 설정은 상속될 수 있음).

이 격리 덕분에 각 서브 에이전트는 자신의 역할에 집중할 수 있습니다. 코드 리뷰어가 이전의 코드 작성 과정을 몰라도 되고, 테스터가 설계 논의를 알 필요도 없습니다. 오히려 이런 맥락이 없는 것이 편향 없는 평가에 도움이 됩니다.

위임의 비용 — 언제 이득이고 언제 손해인가

서브 에이전트 호출에는 비용이 따릅니다. 현명한 위임 결정을 위해 비용 구조를 이해해야 합니다.

서브 에이전트 호출의 고정 비용

• 시스템 프롬프트 토큰 (매 호출마다 소비)
• 작업 지시 전달 토큰 (메인 → 서브)
• 결과 반환 토큰 (서브 → 메인)
• 서브 에이전트 내부의 도구 호출 토큰

위임이 이득인 경우

• 작업이 메인 컨텍스트에 불필요한 대량의 중간 데이터를 생성할 때 (예: 100개 파일 스캔 후 요약 3줄 반환)
• 작업이 다른 관점의 독립적 판단을 요구할 때 (예: 코드 작성자와 리뷰어 분리)
• 저비용 모델로 처리 가능한 단순 반복 작업일 때 (예: Haiku로 파일 분류)
• 병렬 처리가 가능한 독립적 작업들일 때 (예: 여러 모듈 동시 검사)
• 메인 컨텍스트가 이미 많이 차 있어 compact 압박이 심할 때

위임이 손해인 경우

• 작업이 메인 컨텍스트의 깊은 이해를 요구할 때 (메인의 대화 맥락을 전부 전달해야 함)
• 작업이 아주 단순하여 고정 비용이 실제 작업보다 클 때 (예: 파일 하나 읽기)
• 서브 에이전트와 빈번한 상호작용이 필요할 때 (매번 새 호출 = 새 고정 비용)
• 결과의 정확도가 극도로 중요하여 최고 모델만 허용될 때 (Opus를 서브에이전트로도 써야 하면 비용 절감 효과 감소)

경험적으로, 서브 에이전트가 5회 이상의 도구 호출을 수행하거나, 10개 이상의 파일을 처리할 때 위임의 이득이 분명해집니다. 도구 호출 1~2회 수준이라면 메인 에이전트가 직접 처리하는 것이 효율적입니다.

컨텍스트 전달 전략

격리된 서브 에이전트에게 작업을 지시할 때, 어떤 정보를 얼마나 전달할지가 중요합니다.

최소 전달 원칙: 서브 에이전트가 작업을 수행하는 데 필요한 최소한의 정보만 전달합니다. 불필요한 맥락은 혼란을 야기하고 토큰을 낭비합니다.

// 비효율적 전달 — 불필요한 맥락 포함
"이 프로젝트는 React 18 기반이고, 지난주에 상태 관리를 Redux에서 
Zustand로 마이그레이션했고, CI/CD는 GitHub Actions를 쓰고 있어. 
src/components/UserProfile.tsx 파일의 보안 취약점을 찾아줘."

// 효율적 전달 — 필요한 정보만
"src/components/UserProfile.tsx 파일의 보안 취약점을 찾아줘. 
이 컴포넌트는 사용자 입력을 받아 API에 전달한다."

반면, 판단에 영향을 미치는 맥락은 반드시 포함해야 합니다. 보안 리뷰어에게 “이 코드는 내부 관리자만 사용한다”는 정보를 주면 심각도 평가가 달라질 수 있습니다.

멀티 에이전트 오케스트레이션 패턴

이제 실전에서 활용할 수 있는 멀티 에이전트 오케스트레이션 패턴들을 살펴보겠습니다. 각 패턴은 특정 상황에 최적화되어 있으며, 상황에 따라 조합하여 사용할 수 있습니다.

패턴 1: 리뷰어 / 테스터 / 리서처 분리

가장 기본적이면서도 강력한 패턴입니다. 코드 변경 작업을 세 단계로 나누어 각각의 전문 에이전트가 담당합니다.

구성

• 메인 에이전트 (Coder): 사용자의 요청을 받아 코드를 작성/수정 — Opus 4.6
• 서브: Researcher: 관련 코드, 패턴, 의존성을 사전 조사 — Haiku 4.5
• 서브: Reviewer: 완성된 코드의 품질, 버그, 스타일 검토 — Sonnet 4.6
• 서브: Tester: 테스트 실행 및 커버리지 확인 — Sonnet 4.6

{
  "namedSubagents": {
    "researcher": {
      "description": "코드베이스 리서처. 관련 파일, 패턴, 의존성을 조사한다.",
      "systemPrompt": "당신은 코드베이스 탐정입니다. 주어진 주제에 관련된 파일, 함수, 패턴, 의존성을 빠르게 찾아 정리하세요. 코드를 수정하지 마세요. 발견한 내용을 구조화된 형태로 보고하세요.",
      "allowedTools": ["Read", "Grep", "Glob"],
      "model": "claude-haiku-4-5-20251001"
    },
    "reviewer": {
      "description": "시니어 코드 리뷰어. 버그, 보안, 성능, 가독성을 검토한다.",
      "systemPrompt": "당신은 10년차 시니어 개발자입니다. 변경된 코드를 리뷰하고 다음을 검토하세요:\n1. 논리적 버그나 엣지 케이스\n2. 보안 취약점 (OWASP Top 10)\n3. 성능 병목\n4. 코드 스타일과 가독성\n\n각 이슈를 심각도(Critical/High/Medium/Low)와 함께 보고하세요. 코드를 수정하지 마세요.",
      "allowedTools": ["Read", "Grep", "Glob"],
      "model": "claude-sonnet-4-6"
    },
    "tester": {
      "description": "QA 엔지니어. 테스트를 실행하고 커버리지를 확인한다.",
      "systemPrompt": "당신은 QA 엔지니어입니다. 변경된 코드에 대해:\n1. 관련 기존 테스트를 실행하세요\n2. 실패하는 테스트가 있으면 원인을 분석하세요\n3. 누락된 테스트 케이스를 제안하세요\n\n테스트 실행 결과를 PASS/FAIL과 함께 보고하세요.",
      "allowedTools": ["Read", "Grep", "Glob", "Bash"],
      "model": "claude-sonnet-4-6"
    }
  }
}

워크플로우

1. 사용자가 기능 구현을 요청
2. 메인 에이전트가 Researcher에게 관련 코드 조사를 위임
3. Researcher의 조사 결과를 바탕으로 메인 에이전트가 코드 작성
4. 코드 작성 완료 후, Reviewer와 Tester에게 병렬로 위임
5. Reviewer의 피드백과 Tester의 결과를 종합하여 메인 에이전트가 수정
6. 필요시 2차 리뷰/테스트 반복

이 패턴의 핵심 가치는 “자기 코드를 자기가 리뷰하지 않는다”는 원칙입니다. 메인 에이전트가 작성한 코드를 별도의 컨텍스트를 가진 리뷰어가 검토하므로, 작성 과정에서의 편향(예: “이 방식이 맞다고 이미 결론 내림”)이 리뷰에 영향을 주지 않습니다.

패턴 2: 검증자 패턴 (Verifier Pattern)

검증자 패턴은 결과의 정확성이 특히 중요한 작업에서 사용합니다. 핵심 아이디어는 “생성과 검증을 분리”하는 것입니다.

구성

• 생성자 (Generator): 결과물을 만드는 에이전트
• 검증자 (Verifier): 결과물의 정확성을 독립적으로 확인하는 에이전트

{
  "namedSubagents": {
    "sql-generator": {
      "description": "SQL 쿼리 생성기. 자연어 요청을 SQL로 변환한다.",
      "systemPrompt": "당신은 SQL 전문가입니다. 사용자의 자연어 요청을 정확한 SQL 쿼리로 변환하세요. 스키마 정보를 먼저 확인한 후 쿼리를 작성하세요.",
      "allowedTools": ["Read", "Grep", "Glob"],
      "model": "claude-sonnet-4-6"
    },
    "sql-verifier": {
      "description": "SQL 검증기. 생성된 SQL의 정확성과 안전성을 검증한다.",
      "systemPrompt": "당신은 DBA입니다. 주어진 SQL 쿼리를 검증하세요:\n1. 의도한 결과를 정확히 반환하는가?\n2. SQL Injection 위험이 없는가?\n3. 성능 이슈가 없는가? (인덱스 활용, 풀 테이블 스캔 등)\n4. 데이터 무결성을 해치지 않는가?\n\n문제가 있으면 구체적으로 지적하고, 수정된 쿼리를 제안하세요.",
      "allowedTools": ["Read", "Grep", "Glob"],
      "model": "claude-sonnet-4-6"
    }
  }
}

검증자 패턴이 특히 효과적인 영역은 다음과 같습니다.

• 데이터베이스 마이그레이션: 마이그레이션 스크립트를 생성하고, 검증자가 데이터 손실 위험을 확인
• 정규표현식 작성: 생성자가 패턴을 만들고, 검증자가 엣지 케이스를 테스트
• 설정 파일 변경: YAML/JSON 설정을 수정하고, 검증자가 문법 오류와 의미적 오류를 확인
• 인프라 코드: Terraform/CloudFormation을 작성하고, 검증자가 보안 그룹, 권한 설정을 검토

패턴 3: Fan-out / Fan-in

대규모 작업을 여러 서브 에이전트에게 분산 처리하고 결과를 모으는 패턴입니다. MapReduce의 에이전트 버전이라고 볼 수 있습니다.

시나리오: 대규모 코드베이스의 전체 보안 감사

{
  "namedSubagents": {
    "scanner-frontend": {
      "description": "프론트엔드 보안 스캐너. XSS, CSRF 등 클라이언트 취약점을 검사한다.",
      "systemPrompt": "당신은 프론트엔드 보안 전문가입니다. src/frontend/ 디렉토리의 모든 파일을 검사하여 XSS, CSRF, 안전하지 않은 DOM 조작, 민감 데이터 노출 등을 찾으세요.",
      "allowedTools": ["Read", "Grep", "Glob"],
      "model": "claude-sonnet-4-6"
    },
    "scanner-backend": {
      "description": "백엔드 보안 스캐너. Injection, 인증/인가 취약점을 검사한다.",
      "systemPrompt": "당신은 백엔드 보안 전문가입니다. src/backend/ 디렉토리의 모든 파일을 검사하여 SQL Injection, Command Injection, 인증/인가 우회, SSRF 등을 찾으세요.",
      "allowedTools": ["Read", "Grep", "Glob"],
      "model": "claude-sonnet-4-6"
    },
    "scanner-infra": {
      "description": "인프라 보안 스캐너. 설정 파일의 보안 이슈를 검사한다.",
      "systemPrompt": "당신은 인프라 보안 전문가입니다. Docker, CI/CD, 환경 변수 설정 파일을 검사하여 하드코딩된 시크릿, 과도한 권한, 불안전한 베이스 이미지 등을 찾으세요.",
      "allowedTools": ["Read", "Grep", "Glob"],
      "model": "claude-haiku-4-5-20251001"
    },
    "security-aggregator": {
      "description": "보안 감사 종합 보고서 작성자.",
      "systemPrompt": "당신은 보안 감사 보고서 작성자입니다. 여러 스캐너의 결과를 받아 심각도별로 정리하고, 우선 수정 순서를 제안하는 종합 보고서를 작성하세요.",
      "allowedTools": ["Read"],
      "model": "claude-sonnet-4-6"
    }
  }
}

실행 흐름

1. Fan-out: 메인 에이전트가 세 스캐너를 동시에 호출 (각각 담당 영역 검사)
2. 수집: 세 스캐너의 결과를 메인 에이전트가 수집
3. Fan-in: 수집된 결과를 security-aggregator에게 전달하여 종합 보고서 생성

이 패턴의 장점은 명확합니다. 100개 파일을 순차 검사하면 한 에이전트의 컨텍스트가 빠르게 소진되지만, 3개 에이전트가 33개씩 나눠 처리하면 각자의 컨텍스트 내에서 여유 있게 분석할 수 있습니다. 또한 처리 시간도 단축됩니다.

패턴 4: 파이프라인 패턴 (Pipeline)

작업을 순차적 단계로 나누어 각 단계를 전문 에이전트가 처리하는 패턴입니다. 이전 단계의 출력이 다음 단계의 입력이 됩니다.

시나리오: API 엔드포인트 추가

사용자 요청
    ↓
[1. API 설계자] → OpenAPI 스펙 초안
    ↓
[2. 구현자] → 컨트롤러 + 서비스 코드
    ↓
[3. 테스트 작성자] → 단위 테스트 + 통합 테스트
    ↓
[4. 문서 작성자] → API 문서 업데이트
    ↓
메인 에이전트가 전체 결과 통합

파이프라인 패턴에서 주의할 점은 단계 간 인터페이스를 명확히 정의하는 것입니다. 각 서브 에이전트의 출력 형식이 다음 서브 에이전트의 기대 입력과 일치해야 합니다. 이를 위해 시스템 프롬프트에 출력 형식을 엄격히 지정하는 것이 중요합니다.

패턴 5: 경쟁 패턴 (Racing / Best-of-N)

같은 작업을 여러 에이전트에게 독립적으로 수행시키고, 가장 좋은 결과를 선택하는 패턴입니다.

{
  "namedSubagents": {
    "solver-a": {
      "description": "접근법 A로 문제를 해결한다.",
      "systemPrompt": "성능 최적화 관점에서 문제를 해결하세요. 시간 복잡도를 최소화하는 것이 최우선입니다.",
      "allowedTools": ["Read", "Grep", "Glob", "Edit", "Write"],
      "model": "claude-sonnet-4-6"
    },
    "solver-b": {
      "description": "접근법 B로 문제를 해결한다.",
      "systemPrompt": "가독성과 유지보수성 관점에서 문제를 해결하세요. 코드가 직관적이고 확장 가능한 것이 최우선입니다.",
      "allowedTools": ["Read", "Grep", "Glob", "Edit", "Write"],
      "model": "claude-sonnet-4-6"
    }
  }
}

비용이 2배 이상 들지만, 설계 결정이 프로젝트에 장기적 영향을 미치는 경우(예: 핵심 알고리즘 선택, 아키텍처 패턴 결정)에는 충분히 투자할 가치가 있습니다. 메인 에이전트가 두 결과를 비교 평가하여 더 나은 접근을 선택하거나, 양쪽의 장점을 결합한 최종안을 만들 수 있습니다.

실전 설정 예시 — 프로젝트별 서브 에이전트 구성

예시 1: 풀스택 웹 프로젝트

// .claude/settings.json
{
  "namedSubagents": {
    "frontend-specialist": {
      "description": "React/Next.js 프론트엔드 전문가",
      "systemPrompt": "당신은 React/Next.js 전문가입니다. 컴포넌트 설계, 상태 관리, SSR/SSG, 접근성(a11y)에 집중하세요. 백엔드 코드는 건드리지 마세요.",
      "allowedTools": ["Read", "Grep", "Glob", "Edit", "Write"],
      "model": "claude-sonnet-4-6"
    },
    "backend-specialist": {
      "description": "Node.js/Express 백엔드 전문가",
      "systemPrompt": "당신은 백엔드 API 전문가입니다. RESTful 설계, 데이터베이스 쿼리 최적화, 인증/인가, 에러 핸들링에 집중하세요. 프론트엔드 코드는 건드리지 마세요.",
      "allowedTools": ["Read", "Grep", "Glob", "Edit", "Write", "Bash"],
      "model": "claude-sonnet-4-6"
    },
    "db-expert": {
      "description": "데이터베이스 전문가. 스키마 설계와 마이그레이션을 담당한다.",
      "systemPrompt": "당신은 DBA입니다. 스키마 설계, 인덱스 전략, 마이그레이션 스크립트 작성, 쿼리 성능 분석을 담당하세요. 마이그레이션은 항상 롤백 가능하게 작성하세요.",
      "allowedTools": ["Read", "Grep", "Glob", "Edit", "Write"],
      "model": "claude-sonnet-4-6"
    },
    "e2e-tester": {
      "description": "E2E 테스트 전문가. Playwright/Cypress 테스트를 작성하고 실행한다.",
      "systemPrompt": "당신은 E2E 테스트 전문가입니다. 사용자 시나리오 기반 테스트를 작성하고 실행하세요. 테스트는 독립적이고 반복 가능해야 합니다.",
      "allowedTools": ["Read", "Grep", "Glob", "Edit", "Write", "Bash"],
      "model": "claude-sonnet-4-6"
    }
  }
}

예시 2: 데이터 파이프라인 프로젝트

{
  "namedSubagents": {
    "data-modeler": {
      "description": "데이터 모델링 전문가. 스키마와 변환 로직을 설계한다.",
      "allowedTools": ["Read", "Grep", "Glob", "Edit", "Write"],
      "model": "claude-sonnet-4-6"
    },
    "pipeline-builder": {
      "description": "ETL 파이프라인 구축 전문가.",
      "allowedTools": ["Read", "Grep", "Glob", "Edit", "Write", "Bash"],
      "model": "claude-sonnet-4-6"
    },
    "data-validator": {
      "description": "데이터 품질 검증 전문가. 스키마 일관성과 데이터 무결성을 확인한다.",
      "allowedTools": ["Read", "Grep", "Glob", "Bash"],
      "model": "claude-haiku-4-5-20251001"
    }
  }
}

SubagentStop 훅과의 결합 — 자율성과 통제의 균형

4편(상)에서 다룬 Hooks와 서브 에이전트를 결합하면, 자율적으로 동작하면서도 통제 가능한 정교한 시스템을 구축할 수 있습니다. 핵심은 SubagentStop 훅입니다.

SubagentStop 훅의 동작 원리

SubagentStop은 서브 에이전트가 작업을 완료하고 결과를 메인 에이전트에게 반환하기 직전에 실행되는 훅입니다. 이 훅은 서브 에이전트의 출력을 검사하고, 필요하면 수정하거나 차단할 수 있습니다.

// .claude/settings.json — hooks 섹션
{
  "hooks": {
    "SubagentStop": [
      {
        "matcher": "reviewer",
        "command": "node .claude/hooks/review-quality-gate.js"
      },
      {
        "matcher": "tester",
        "command": "node .claude/hooks/test-coverage-gate.js"
      }
    ]
  }
}

SubagentStop 훅에서 접근 가능한 환경 변수들은 다음과 같습니다.

• CLAUDE_SUBAGENT_NAME: 서브 에이전트의 이름 (예: “reviewer”)
• CLAUDE_SUBAGENT_RESULT: 서브 에이전트의 반환 결과 텍스트
• 표준 입력(stdin)으로 전체 페이로드 JSON 수신

실전 결합 사례: 품질 게이트

리뷰어 서브 에이전트의 결과에 Critical 이슈가 포함되어 있으면, 메인 에이전트에게 자동으로 수정을 강제하는 흐름을 만들어 보겠습니다.

// .claude/hooks/review-quality-gate.js
const fs = require('fs');

// stdin에서 서브 에이전트 결과를 읽어옴
let input = '';
process.stdin.on('data', chunk => { input += chunk; });
process.stdin.on('end', () => {
  const payload = JSON.parse(input);
  const result = payload.subagent_result || '';
  
  // Critical 이슈가 있는지 확인
  const hasCritical = result.toLowerCase().includes('critical');
  const criticalCount = (result.match(/심각도:\s*Critical/gi) || []).length;
  
  if (hasCritical) {
    // 종료 코드 0 + stdout으로 추가 지시 전달
    const instruction = JSON.stringify({
      decision: "block",
      reason: `리뷰에서 Critical 이슈 ${criticalCount}건 발견. 반드시 수정 후 재리뷰 필요.`
    });
    process.stdout.write(instruction);
    process.exit(2); // 비정상 종료로 메인 에이전트에게 경고
  }
  
  // Critical 없으면 통과
  process.exit(0);
});

이 설정이 적용되면 다음과 같은 자동 워크플로우가 만들어집니다.

1. 메인 에이전트가 코드를 작성하고 reviewer에게 위임
2. reviewer가 리뷰 결과를 반환
3. SubagentStop 훅이 결과를 검사
4. Critical 이슈가 있으면 훅이 메인 에이전트에게 “수정 필수” 신호를 전달
5. 메인 에이전트가 자동으로 수정 후 다시 reviewer에게 위임
6. Critical이 해소될 때까지 반복

이것이 바로 “자율성과 통제를 동시에 잡는 설계”입니다. 서브 에이전트는 자유롭게 리뷰하되, 훅이 품질 기준을 강제합니다. 메인 에이전트는 자동으로 수정 루프를 돌되, 훅이 완료 조건을 판단합니다.

보안 게이트 결합

보안 감사 서브 에이전트의 결과를 훅으로 검증하는 더 정교한 예시입니다.

// .claude/hooks/security-gate.js
let input = '';
process.stdin.on('data', chunk => { input += chunk; });
process.stdin.on('end', () => {
  const payload = JSON.parse(input);
  const result = payload.subagent_result || '';
  
  // 보안 감사 결과 파싱
  const findings = {
    critical: (result.match(/심각도:\s*Critical/gi) || []).length,
    high: (result.match(/심각도:\s*High/gi) || []).length,
    medium: (result.match(/심각도:\s*Medium/gi) || []).length,
    low: (result.match(/심각도:\s*Low/gi) || []).length
  };
  
  // 감사 로그 기록
  const logEntry = {
    timestamp: new Date().toISOString(),
    subagent: process.env.CLAUDE_SUBAGENT_NAME,
    findings: findings,
    passed: findings.critical === 0 && findings.high === 0
  };
  
  fs.appendFileSync(
    '.claude/security-audit.log',
    JSON.stringify(logEntry) + '\n'
  );
  
  // Critical 또는 High가 있으면 차단
  if (findings.critical > 0 || findings.high > 0) {
    process.stdout.write(JSON.stringify({
      decision: "block",
      reason: `보안 감사 실패: Critical ${findings.critical}건, High ${findings.high}건`,
      findings: findings
    }));
    process.exit(2);
  }
  
  process.exit(0);
});

이렇게 하면 모든 보안 감사 결과가 로그 파일에 기록되어 추적 가능하고, Critical이나 High 수준의 취약점이 있으면 자동으로 수정 루프가 시작됩니다.

고급 활용: 오케스트레이터 패턴

메타 에이전트 — 에이전트를 관리하는 에이전트

복잡한 프로젝트에서는 메인 에이전트가 직접 여러 서브 에이전트를 조율하는 것이 부담이 될 수 있습니다. 이때 오케스트레이터라는 중간 계층을 도입합니다.

{
  "namedSubagents": {
    "orchestrator": {
      "description": "작업 오케스트레이터. 복잡한 작업을 분해하고 적절한 서브 에이전트에게 위임한다.",
      "systemPrompt": "당신은 프로젝트 매니저입니다. 주어진 작업을 분석하여:\n1. 필요한 단계를 식별하세요\n2. 각 단계에 적합한 서브 에이전트를 호출하세요\n3. 결과를 종합하여 최종 보고서를 작성하세요\n\n사용 가능한 서브 에이전트: researcher, reviewer, tester, security-auditor\n\n병렬 처리가 가능한 작업은 동시에 위임하세요.",
      "allowedTools": ["Read", "Grep", "Glob", "Agent"],
      "model": "claude-sonnet-4-6"
    }
  }
}

오케스트레이터에게 Agent 도구를 허용하면, 오케스트레이터가 다시 다른 Named Subagent를 호출할 수 있습니다. 이렇게 하면 메인 에이전트는 “이 기능 추가해줘”라고 한 번만 말하면, 오케스트레이터가 알아서 리서치 → 구현 → 테스트 → 리뷰 → 보안 감사의 전체 파이프라인을 관리합니다.

단, 서브 에이전트 계층이 깊어지면 비용과 지연이 급격히 증가합니다. 실전에서는 최대 2계층(메인 → 오케스트레이터 → 실행 에이전트)까지가 적절합니다.

조건부 위임 전략

모든 작업에 서브 에이전트를 동원하는 것은 낭비입니다. CLAUDE.md에 조건부 위임 규칙을 정의하면 메인 에이전트가 상황에 따라 적절히 판단합니다.

# CLAUDE.md 서브 에이전트 위임 규칙

## 필수 위임 (항상 서브 에이전트 사용)
- 5개 이상의 파일을 수정할 때 → reviewer 서브 에이전트로 리뷰
- 보안 관련 코드(인증, 암호화, 세션) 수정 시 → security-auditor 호출
- 데이터베이스 스키마 변경 시 → db-expert 호출

## 권장 위임 (복잡도가 높을 때)
- 새로운 API 엔드포인트 추가 → frontend-specialist + backend-specialist 분업
- 성능 최적화 작업 → researcher로 벤치마크 데이터 수집 후 진행

## 직접 처리 (서브 에이전트 불필요)
- 단일 파일의 간단한 수정 (오타, 스타일, 주석)
- 기존 패턴을 따르는 반복적 코드 추가
- 설정 값 변경

서브 에이전트 디버깅 — 무엇이 잘못되었는가

흔한 문제와 해결법

문제 1: 서브 에이전트가 역할을 벗어나는 행동을 한다

원인: 시스템 프롬프트의 제약이 약하거나, 허용 도구가 과도하게 열려 있음
해결: “~하지 마세요” 지시를 추가하고, 불필요한 도구를 제거

문제 2: 서브 에이전트의 결과가 메인 에이전트의 기대와 다른 형식이다

원인: 출력 형식이 시스템 프롬프트에 명시되지 않음
해결: 시스템 프롬프트에 구체적인 출력 형식 (JSON 스키마, Markdown 템플릿 등)을 지정

문제 3: 서브 에이전트가 필요한 파일을 찾지 못한다

원인: 메인 에이전트가 작업 지시에 충분한 위치 정보를 포함하지 않음
해결: 위임 시 관련 파일 경로를 명시적으로 전달. “src/auth/ 디렉토리의 인증 로직을 리뷰해줘”처럼 구체적으로

문제 4: 비용이 예상보다 많이 든다

원인: 서브 에이전트가 불필요하게 많은 파일을 읽거나, 재호출이 빈번함
해결: 시스템 프롬프트에 “최대 N개 파일만 검사하세요”와 같은 범위 제한을 추가하고, 작업 지시를 더 구체적으로

서브 에이전트 성능 모니터링

SubagentStop 훅을 활용하면 서브 에이전트의 성능을 추적할 수 있습니다.

// .claude/hooks/subagent-metrics.js
const fs = require('fs');

let input = '';
process.stdin.on('data', chunk => { input += chunk; });
process.stdin.on('end', () => {
  const payload = JSON.parse(input);
  
  const metric = {
    timestamp: new Date().toISOString(),
    subagent: process.env.CLAUDE_SUBAGENT_NAME,
    result_length: (payload.subagent_result || '').length,
    // 결과 품질의 간접 지표
    has_actionable_items: /수정|변경|추가|삭제|개선/.test(
      payload.subagent_result || ''
    )
  };
  
  fs.appendFileSync(
    '.claude/subagent-metrics.jsonl',
    JSON.stringify(metric) + '\n'
  );
  
  process.exit(0);
});

이 데이터를 축적하면, 어떤 서브 에이전트가 유용한 결과를 내고 있는지, 어떤 서브 에이전트가 비용 대비 효과가 낮은지를 파악할 수 있습니다.

서브 에이전트 vs. 다른 접근법 — 언제 무엇을 쓸 것인가

멀티 에이전트가 항상 최선은 아닙니다. 상황에 따른 적합한 접근법을 정리합니다.

단일 에이전트 + 순차 실행

• 적합: 작업이 선형적이고, 전체 맥락이 필요한 경우
• 장점: 컨텍스트 유지, 낮은 오버헤드
• 단점: 컨텍스트 오염 위험, 역할 전환 비용

서브 에이전트 위임

• 적합: 독립적 판단이 필요하거나, 대량 데이터 처리가 필요한 경우
• 장점: 컨텍스트 격리, 병렬 처리 가능, 모델 비용 최적화
• 단점: 고정 비용, 맥락 전달 오버헤드

Hooks만으로 처리

• 적합: 외부 도구로 검증 가능한 규칙 기반 체크 (린트, 포맷, 정적 분석)
• 장점: 결정론적, 빠름, 비용 없음 (외부 도구 실행)
• 단점: 유연한 판단 불가

MCP 서버 호출

• 적합: 외부 API, 데이터베이스, 서비스와의 연동
• 장점: 도구 확장, 외부 시스템 접근
• 단점: 서버 관리 필요, 네트워크 지연

최적의 아키텍처는 이들을 적재적소에 조합하는 것입니다. 예를 들어: 메인 에이전트가 코드를 작성 → PostToolUse 훅이 린트를 자동 실행 → 완성 후 서브 에이전트(리뷰어)에게 위임 → SubagentStop 훅이 리뷰 품질을 검증 → MCP 서버를 통해 Jira 티켓에 결과를 기록.

실전 팁 모음 — 현장에서 배운 것들

이름 짓기의 중요성

서브 에이전트의 이름은 단순한 식별자가 아닙니다. 메인 에이전트가 어떤 서브 에이전트에게 위임할지 판단하는 근거이기도 합니다. description 필드와 함께, 역할을 직관적으로 드러내는 이름을 사용하세요.

• 좋은 예: security-auditor, frontend-specialist, data-validator
• 나쁜 예: agent1, helper, sub

시스템 프롬프트에 예시를 포함하라

서브 에이전트의 행동을 가장 효과적으로 제어하는 방법은 원하는 출력의 예시를 시스템 프롬프트에 포함하는 것입니다.

"systemPrompt": "... 다음과 같은 형식으로 보고하세요:\n\n### 발견 사항 1\n- 심각도: High\n- 위치: src/auth/login.ts:42\n- 설명: SQL Injection 가능. 사용자 입력이 쿼리에 직접 삽입됨\n- 권고: Parameterized query 사용\n\n### 발견 사항 2\n..."

점진적 도입 전략

처음부터 5개의 서브 에이전트를 정의할 필요는 없습니다. 다음 순서로 점진적으로 도입하는 것을 추천합니다.

1. 1단계: reviewer 하나만 추가. 코드 작성 후 자동 리뷰
2. 2단계: tester 추가. 리뷰 통과 후 테스트 자동 실행
3. 3단계: researcher 추가. 작업 전 사전 조사 자동화
4. 4단계: 도메인 특화 에이전트 추가 (security, performance 등)
5. 5단계: SubagentStop 훅으로 품질 게이트 추가

각 단계에서 실제로 품질이나 효율이 개선되는지 확인한 후 다음 단계로 넘어가세요.

CLAUDE.md에 위임 정책 명문화

서브 에이전트를 설정해도, 메인 에이전트가 언제 위임할지 모르면 제대로 활용되지 않습니다. CLAUDE.md에 명확한 위임 정책을 작성하세요.

# 서브 에이전트 위임 정책

## reviewer
- 트리거: Edit 또는 Write 도구로 .ts, .tsx, .js 파일을 3개 이상 수정한 후
- 위임 내용: 변경된 파일 목록과 각 파일의 변경 요약을 전달
- 기대 결과: 이슈 목록 (심각도별 분류)

## security-auditor  
- 트리거: 인증, 권한, 암호화, 세션, 쿠키 관련 코드를 수정할 때
- 위임 내용: 변경된 파일과 관련 컨텍스트 (어떤 보안 기능인지)
- 기대 결과: OWASP Top 10 기준 취약점 목록

## researcher
- 트리거: 새로운 기능을 구현하기 전, 기존 코드의 관련 패턴을 파악해야 할 때
- 위임 내용: 구현하려는 기능의 설명
- 기대 결과: 관련 기존 코드, 사용 중인 패턴, 참고할 파일 목록

마무리 — 1인 개발에서 팀 개발로의 전환

서브 에이전트는 단순한 기술적 기능이 아닙니다. 이것은 소프트웨어 개발의 근본적인 패러다임 전환을 의미합니다. 한 명의 개발자가 Claude Code를 사용하더라도, 서브 에이전트를 통해 리서처, 코더, 리뷰어, 테스터, 보안 전문가로 구성된 가상 팀을 운영할 수 있습니다.

핵심 원칙을 다시 정리합니다.

• 4축 설계: 역할 · 도구 · 모델 · 프롬프트를 독립적으로 최적화
• 최소 권한: 각 서브 에이전트에게 역할 수행에 필요한 최소한의 도구만 허용
• 비용 인식: 위임의 이득과 비용을 따져 현명하게 결정
• 훅 결합: SubagentStop으로 자율성과 통제의 균형
• 점진적 도입: 한 번에 하나씩, 효과를 확인하며 확장

이번 편에서 다룬 로컬 환경의 멀티 에이전트 오케스트레이션은 강력하지만, 여전히 개발자의 로컬 머신에 묶여 있다는 한계가 있습니다. 다음 최종편에서는 이 한계를 넘어, Remote Control로 어디서든 에이전트를 조종하고, Cloud 환경에서 24/7 무인 운영하며, OpenTelemetry로 모든 것을 추적하는 운영급 아키텍처를 다룹니다. 로컬 개발 도구에서 엔터프라이즈 플랫폼으로 — Claude Code의 진정한 완성편을 기대해주세요.

이미지는 Leonardo AI 로 생성되었습니다.

이미지는 Claude AI 로 생성되었습니다.

---