클로드 코드 서브 에이전트: AI에게 일을 시키는 AI

클로드 코드로 작업하다 보면 하나의 요청이 여러 단계로 나뉘는 경우가 많습니다. 테스트를 돌려서 실패하는 항목을 파악하고 관련 코드를 탐색한 다음 수정 방안을 정리해서 실제 코드를 고치는 식이죠. 이 과정에서 Claude의 컨텍스트 윈도우에는 테스트 출력이며 탐색 결과며 온갖 정보가 쌓이면서 정작 중요한 맥락이 밀려나 버립니다. 🤯

이런 문제를 해결하려고 Claude Code는 서브 에이전트(Sub-agent)라는 구조를 도입했습니다. 메인 대화에서 특정 작업을 별도의 에이전트에게 위임하면 그 에이전트가 독립된 컨텍스트 윈도우에서 작업을 처리하고 결과만 돌려주는 방식인데요. 이 글에서는 서브 에이전트의 동작 원리와 직접 만들어서 활용하는 방법을 살펴보겠습니다.

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

서브 에이전트의 핵심은 컨텍스트 관리입니다. Claude Code의 메인 대화는 하나의 컨텍스트 윈도우 안에서 진행되는데, 작업이 복잡해질수록 이 공간이 빠르게 소모됩니다.

“테스트를 돌리고 실패하는 것들을 고쳐줘”라고 요청하면 어떻게 될까요? 테스트 출력 전체가 메인 컨텍스트에 들어옵니다. 수백 줄짜리 테스트 로그가 그대로 쌓이면서 이전에 논의했던 설계 방향이나 코드 구조 같은 맥락이 밀려나 버리죠. 서브 에이전트에게 이 작업을 맡기면 테스트 출력은 서브 에이전트 쪽에만 남고, 메인 대화에는 “3개 테스트 실패, 원인은 타입 불일치”처럼 요약된 결과만 돌아옵니다.

컨텍스트 보존 말고도 이점이 있습니다. 서브 에이전트마다 쓸 수 있는 도구를 제한할 수 있어서 읽기 전용 탐색 에이전트에게는 파일 수정 권한을 안 주는 식으로 안전하게 운용할 수 있고요. 서브 에이전트별로 다른 모델을 지정하는 것도 됩니다. 간단한 파일 탐색은 빠르고 저렴한 Haiku에게 맡기고, 복잡한 코드 리뷰는 Opus에게 시키는 거죠.

기본 제공 서브 에이전트

Claude Code에는 상황에 따라 자동으로 쓰이는 내장 서브 에이전트가 있습니다.

Explore는 코드베이스 탐색 전용입니다. Haiku 모델을 써서 빠르고 읽기 전용 도구만 쓸 수 있어서 파일이 수정될 걱정이 없죠. Claude가 코드베이스를 파악해야 할 때 알아서 위임합니다.

Plan은 설정 가이드에서 다룬 계획 모드를 켤 때 동작합니다. 메인 대화의 모델을 그대로 사용하고 역시 읽기 전용이에요. 코드베이스를 조사한 뒤 그 결과를 바탕으로 실행 계획을 세워줍니다.

General-purpose는 탐색과 코드 수정을 모두 할 수 있는 범용 서브 에이전트입니다. 여러 단계를 거쳐야 하거나 탐색 결과를 보고 곧바로 수정해야 하는 경우에 쓰여요.

이 밖에도 Bash 명령을 별도 컨텍스트에서 실행하는 Bash 에이전트나, Claude Code 기능에 대한 질문에 답하는 Claude Code Guide 에이전트가 있습니다.

대화형으로 서브 에이전트 만들기

기본 제공 에이전트만으로 부족하면 직접 만들면 됩니다. 가장 간단한 방법은 /agents 슬래시 커맨드를 쓰는 거예요. 실행하면 현재 등록된 서브 에이전트 목록과 기본 제공 에이전트를 한눈에 볼 수 있습니다. 아직 커스텀 에이전트를 만든 적이 없으면 Create new agent만 선택 가능하죠.

❯ /agents

───────────────────────────────────────────────────
  Agents
  No agents found

  ❯ Create new agent

  No agents found. Create specialized subagents that Claude can delegate to.

  Each subagent has its own context window, custom system prompt, and specific tools.

  Try creating: Code Reviewer, Code Simplifier, Security Reviewer, Tech Lead, or UX Reviewer.

  ─────────────────────────────────────────────────

    Built-in (always available):
    claude-code-guide · haiku
    Explore · haiku
    general-purpose · inherit
    Plan · inherit
    statusline-setup · sonnet

  Press ↑↓ to navigate · Enter to select · Esc to go back

먼저 에이전트 파일을 어디에 저장할지 고릅니다. Project는 .claude/agents/에 저장되어 Git으로 팀과 공유할 수 있고, Personal은 ~/.claude/agents/에 저장되어 내 모든 프로젝트에서 쓸 수 있어요.

❯ /agents

────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  Create new agent
  Choose location

  ❯ 1. Project (.claude/agents/)
    2. Personal (~/.claude/agents/)

생성 방식은 두 가지입니다. Generate with Claude를 고르면 원하는 역할을 설명하기만 하면 Claude가 알아서 마크다운 파일을 만들어줍니다. Manual configuration은 이름, 모델, 도구 등을 직접 입력하는 방식이에요.

❯ /agents

───────────────────────────────────────────────────
  Create new agent
  Creation method

  ❯ 1. Generate with Claude (recommended)
    2. Manual configuration

   ↑↓ to navigate · Enter to select · Esc to go back

Generate with Claude를 선택하면 에이전트가 어떤 일을 해야 하는지 자연어로 설명하라는 프롬프트가 나옵니다. 여기에 구체적으로 적을수록 더 정확한 에이전트가 만들어져요.

❯ /agents

───────────────────────────────────────────────────
  Create new agent
  Describe what this agent should do and when it should be used (be comprehensive for best results)

  e.g., Help me write unit tests for my code...

   Enter to submit · ctrl+g to open in editor · Esc to go back

설명을 입력하면 Claude가 에이전트 설정을 자동 생성하고, 이어서 세부 옵션을 조정할 수 있습니다. 도구 선택 화면에서는 에이전트가 사용할 수 있는 도구를 카테고리별로 켜고 끌 수 있어요.

❯ /agents

───────────────────────────────────────────────────
  Create new agent
  Select tools


  ❯ [ Continue ]
  ────────────────────────────────────────
    ☒ All tools
    ☒ Read-only tools
    ☒ Edit tools
    ☒ Execution tools
    ☒ MCP tools
    ☒ Other tools
  ────────────────────────────────────────
    [ Show advanced options ]

모델은 에이전트의 추론 능력과 속도를 결정합니다. 대부분의 에이전트에는 Sonnet이 균형 잡힌 선택이고, 복잡한 추론이 필요하면 Opus, 단순 작업이면 Haiku를 고르면 됩니다.

❯ /agents

───────────────────────────────────────────────────
  Create new agent
  Select model

  Model determines the agent's reasoning capabilities and speed.

  ❯ 1. Sonnet ✔             Balanced performance - best for most agents
    2. Opus                 Most capable for complex reasoning tasks
    3. Haiku                Fast and efficient for simple tasks
    4. Inherit from parent  Use the same model as the main conversation

   ↑↓ to navigate · Enter to select · Esc to go back

배경 색상은 서브 에이전트가 동작할 때 터미널에 표시되는 색입니다. 여러 에이전트를 동시에 돌릴 때 어떤 에이전트가 작업 중인지 시각적으로 구분할 수 있어요.

❯ /agents

───────────────────────────────────────────────────
  Create new agent
  Choose background color

  ❯ Automatic color
      Red
      Blue
      Green
      Yellow
      Purple
      Orange
      Pink
      Cyan


  Preview:  @code-reviewer

   ↑↓ to navigate · Enter to select · Esc to go back

메모리를 켜면 서브 에이전트가 세션을 넘어서 학습한 내용을 기억합니다. 프로젝트 범위가 기본 권장이고, 개인 범위나 로컬 전용도 선택할 수 있어요.

❯ /agents

───────────────────────────────────────────────────
  Create new agent
  Configure agent memory

  ❯ 1. Enable (.claude/agent-memory/) (Recommended)
    2. None (no persistent memory)
    3. User scope (~/.claude/agent-memory/)
    4. Local scope (.claude/agent-memory-local/)

   ↑↓ to navigate · Enter to select · Esc to go back

마지막으로 전체 설정을 확인합니다. 이름, 저장 위치, 도구, 모델, 메모리 설정과 함께 Claude가 생성한 description과 시스템 프롬프트를 검토할 수 있어요. e를 누르면 저장 후 에디터에서 직접 수정할 수도 있습니다.

❯ /agents

───────────────────────────────────────────────────
  Create new agent
  Confirm and save

  Name: code-reviewer
  Location: .claude/agents/code-reviewer.md
  Tools: All tools
  Model: Sonnet
  Memory: Project (.claude/agent-memory/)

  Description (tells Claude when to use this agent):

    Use this agent when the user wants a code review on recently written or modified code. This includes reviewing pull requests, checking code quality, identifying bugs, suggesting
    improvements, or validating adherence to coding conventions.

    E…

  System prompt:

    You are a senior code reviewer with 15+ years of experience across multiple languages and paradigms. You combine deep technical expertise with a constructive, educational approach.
    You review code like a trusted tech lead — thorough, fair,…

  Warnings:
   • Agent has access to all tools
   • System prompt is very long (over 10,000 characters)


  Press s or Enter to save, e to save and edit

   s/Enter to save · e to edit in your editor · Esc to cancel

저장하면 .claude/agents/code-reviewer.md 파일이 생성됩니다. 실제로 만들어진 파일을 열어보면 이런 구조예요.

---
name: code-reviewer
description: "Use this agent when the user wants a code review
  on recently written or modified code. This includes reviewing
  pull requests, checking code quality, identifying bugs,
  suggesting improvements, or validating adherence to coding
  conventions. ..."
model: sonnet
memory: project
---

You are a senior code reviewer with 15+ years of experience
across multiple languages and paradigms. You combine deep
technical expertise with a constructive, educational approach.
You review code like a trusted tech lead — thorough, fair,
and focused on helping developers grow.

## Core Review Principles

1. **Focus on recently changed/written code** — Unless explicitly
   asked to review the entire codebase, focus your review on the
   most recently written or modified code.
2. **Prioritize issues by severity** — Bugs > Security >
   Performance > Maintainability > Style.
3. **Be specific and actionable** — Every comment should include
   what the issue is, why it matters, and how to fix it.
4. **Acknowledge good code** — Point out well-written patterns
   and smart decisions, not just problems.

description에 언제 이 에이전트를 쓸지가 상세하게 적혀 있는 게 보이죠? Claude가 이 설명을 보고 어떤 작업에 이 서브 에이전트를 쓸지 판단합니다. 시스템 프롬프트도 구체적인 리뷰 원칙과 함께 자동 생성되었고요. 물론 저장 후에 에디터에서 원하는 대로 수정할 수 있습니다.

마크다운 파일로 직접 만들기

대화형 방식이 편하긴 하지만 .claude/agents/ 디렉토리에 마크다운 파일을 직접 작성해도 됩니다. 오히려 간결하게 핵심만 담고 싶을 때는 직접 쓰는 게 나을 수 있어요.

---
name: code-reviewer
description: 코드 변경사항을 리뷰합니다. 코드 작성 직후 자동으로 사용합니다.
tools: Read, Grep, Glob, Bash
model: sonnet
---

시니어 코드 리뷰어로서 코드 품질과 보안을 검토합니다.

호출되면:

1. git diff로 최근 변경사항을 확인
2. 수정된 파일에 집중
3. 즉시 리뷰 시작

리뷰 항목:

- 코드가 명확하고 읽기 쉬운지
- 보안 취약점이 없는지
- 에러 처리가 적절한지
- 테스트 커버리지가 충분한지

직접 쓸 때의 장점은 tools 필드로 서브 에이전트가 쓸 수 있는 도구를 세밀하게 제한할 수 있다는 겁니다. 위 예시처럼 코드 리뷰어에게는 Read, Grep, Glob, Bash만 허용하고 Write나 Edit는 빼서 읽기 전용으로 만드는 식이죠. model 필드에서는 sonnet, opus, haiku 같은 별칭이나 claude-opus-4-6 같은 전체 모델 ID를 지정할 수 있고, 생략하거나 inherit를 쓰면 메인 대화 모델을 그대로 씁니다. maxTurns로 최대 턴 수를 제한하는 것도 가능하고요. 사용 가능한 모든 필드는 글 끝의 레퍼런스 테이블에서 확인할 수 있습니다.

서브 에이전트의 저장 위치

서브 에이전트 파일은 어디에 저장하느냐에 따라 적용 범위가 달라집니다. 같은 이름의 서브 에이전트가 여러 위치에 있으면 우선순위가 높은 쪽이 적용돼요.

프로젝트 서브 에이전트 (.claude/agents/)는 Git에 커밋해서 팀 전체가 함께 쓸 수 있어서 프로젝트 전용 서브 에이전트를 공유하기 좋습니다.

사용자 서브 에이전트 (~/.claude/agents/)는 내 모든 프로젝트에서 쓸 수 있습니다. 개인적으로 자주 쓰는 서브 에이전트를 여기에 두면 돼요.

CLI 서브 에이전트는 --agents 플래그로 JSON 형태로 전달하면 해당 세션에서만 사용됩니다. 빠른 테스트나 자동화 스크립트에서 쓰기 좋아요.

claude --agents '{
  "db-reader": {
    "description": "읽기 전용 데이터베이스 쿼리 실행",
    "prompt": "SELECT 쿼리만 실행하여 데이터를 분석합니다.",
    "tools": ["Bash"],
    "model": "sonnet"
  }
}'

플러그인 서브 에이전트는 설치한 플러그인에서 제공됩니다. 보안상 플러그인 서브 에이전트에서는 hooks, mcpServers, permissionMode 필드가 무시되니 이 기능이 필요하다면 에이전트 파일을 .claude/agents/나 ~/.claude/agents/로 복사해서 써야 합니다.

서브 에이전트 호출 방식

서브 에이전트를 만들었으면 어떻게 실행되는 걸까요? 두 가지 방식이 있습니다.

첫 번째는 자동 위임입니다. Claude가 frontmatter의 description을 읽고 현재 작업에 맞는 서브 에이전트를 골라서 호출해요. “코드 작성 직후 자동으로 사용합니다”라고 적어두면 Claude가 코드 수정 후 알아서 리뷰를 맡기는 식이죠. 내장 에이전트도 마찬가지입니다. Explore 에이전트는 코드베이스를 파악해야 할 때, Plan 에이전트는 계획 모드를 켤 때 자동으로 동작합니다. description을 구체적으로 적을수록 Claude가 적재적소에 서브 에이전트를 활용합니다.

두 번째는 명시적 호출입니다. “code-reviewer 서브 에이전트로 인증 모듈을 리뷰해줘”처럼 대화에서 이름을 직접 지정하면 됩니다. 자동 위임이 잘 안 되거나 특정 서브 에이전트를 꼭 쓰고 싶을 때 이 방법이 확실해요.

혹시 /code-reviewer처럼 슬래시 커맨드로 서브 에이전트를 바로 호출할 수 있을까요? 안 됩니다. /agents 커맨드는 서브 에이전트를 조회하고 생성하는 관리 도구이지 특정 에이전트를 실행하는 명령이 아니에요. 이건 Skills와의 차이점이기도 합니다. Skills는 /commit이나 /review-pr처럼 슬래시 커맨드로 직접 트리거할 수 있지만 서브 에이전트는 Claude의 판단이나 자연어 지시를 통해서만 호출됩니다.

그렇다면 어떤 서브 에이전트가 함께 일하고 있는지는 어떻게 알 수 있을까요? /agents 커맨드를 실행하면 내장 에이전트와 커스텀 에이전트 목록이 한눈에 보입니다. 서브 에이전트가 실제로 작업을 시작하면 터미널 배경색이 바뀌어서 시각적으로 구분되고요. Claude도 “Explore 에이전트로 코드베이스를 탐색하겠습니다”처럼 어떤 에이전트를 쓰는지 알려줍니다.

권한 모드

서브 에이전트의 permissionMode 필드로 권한 처리 방식을 제어할 수 있습니다.

• default — 표준 권한 확인 방식으로, 필요할 때마다 사용자에게 승인을 요청합니다
• acceptEdits — 파일 편집을 자동 승인합니다
• dontAsk — 권한 프롬프트를 자동으로 거부합니다 (명시적으로 허용된 도구는 정상 동작)
• plan — 읽기 전용 탐색만 허용하는 계획 모드입니다
• bypassPermissions — 모든 권한 확인을 건너뜁니다

bypassPermissions는 모든 권한 검사를 우회하기 때문에 신중하게 써야 합니다. 보통은 dontAsk으로 설정하고 필요한 도구만 tools 필드에 명시하는 게 안전합니다.

도구 제어

tools가 허용 목록(allowlist)이라면 disallowedTools는 차단 목록(denylist)입니다. 모든 도구를 상속받되 위험한 도구만 빼고 싶을 때 tools를 일일이 나열하는 것보다 훨씬 편해요.

---
name: safe-researcher
description: 코드베이스를 탐색하되 수정은 하지 않는 연구 에이전트
disallowedTools: Write, Edit
---

이렇게 하면 Write와 Edit를 제외한 모든 도구를 쓸 수 있습니다. tools와 disallowedTools를 함께 쓰면 tools로 허용한 목록에서 disallowedTools로 지정한 도구가 제거됩니다.

MCP 서버 범위 지정

서브 에이전트에게 전용 MCP 서버를 연결할 수 있습니다. 메인 대화에는 MCP 도구 설명이 컨텍스트를 차지하는데, 특정 서브 에이전트에서만 쓰는 MCP 서버라면 인라인으로 정의해서 메인 대화의 컨텍스트를 아낄 수 있어요.

---
name: browser-tester
description: Playwright로 브라우저 테스트를 실행합니다.
mcpServers:
  # 인라인 정의: 이 서브 에이전트에서만 연결됨
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  # 이름 참조: 이미 설정된 MCP 서버를 공유
  - github
---

인라인 정의는 서브 에이전트가 시작될 때 연결되고 끝나면 해제됩니다. 문자열로 이름만 적으면 메인 세션에 이미 설정된 MCP 서버를 공유해서 씁니다.

Skills 주입

서브 에이전트에게 Skills를 미리 로드해줄 수 있습니다. skills 필드에 스킬 이름을 나열하면 서브 에이전트가 시작될 때 해당 스킬 내용이 통째로 컨텍스트에 들어갑니다.

---
name: api-developer
description: API 엔드포인트를 팀 컨벤션에 맞게 구현합니다.
skills:
  - api-conventions
  - error-handling-patterns
---

API 엔드포인트를 구현합니다. 주입된 스킬의 컨벤션과 패턴을 따릅니다.

주의할 점은 서브 에이전트가 메인 대화의 스킬을 상속받지 않는다는 겁니다. 필요한 스킬은 명시적으로 나열해야 해요. SKILL.md 작성 가이드에서 스킬을 만드는 방법을 참고하세요.

영속적 메모리

memory 필드를 설정하면 서브 에이전트에게 세션을 넘어서 유지되는 메모리 디렉토리가 생깁니다. 작업하면서 발견한 코드베이스 패턴이나 디버깅 노하우를 기록해두면 다음 세션에서 바로 써먹을 수 있죠.

---
name: code-reviewer
description: 코드 리뷰 전문 에이전트
memory: user
---

코드 리뷰를 수행합니다. 리뷰하면서 발견한 패턴, 컨벤션,
반복되는 이슈를 에이전트 메모리에 기록합니다.

메모리 범위는 세 가지입니다. user는 ~/.claude/agent-memory/에 저장되어 모든 프로젝트에서 공유됩니다. project는 .claude/agent-memory/에 저장되어 프로젝트 전용이고 Git으로 팀과 공유할 수 있어요. local은 .claude/agent-memory-local/에 저장되는데 프로젝트 전용이지만 커밋은 안 합니다. 특별한 이유가 없다면 user를 권장해요.

Hooks와의 연동

서브 에이전트에도 Hooks를 걸 수 있습니다. 서브 에이전트 frontmatter에 직접 정의하거나 프로젝트 settings.json에서 라이프사이클 이벤트에 반응하게 설정하면 됩니다.

다음은 Bash 명령만 허용하되 읽기 전용 SQL 쿼리만 실행할 수 있도록 Hook으로 제한하는 예시입니다.

---
name: db-reader
description: 읽기 전용 데이터베이스 쿼리를 실행합니다.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

데이터베이스 분석가로서 읽기 전용 접근 권한만 가집니다.
SELECT 쿼리로 데이터를 분석하고 질문에 답합니다.

validate-readonly-query.sh 스크립트에서 INSERT, UPDATE, DELETE 같은 쓰기 작업이 감지되면 종료 코드 2를 반환해서 실행을 차단합니다.

프로젝트 settings.json에서는 SubagentStart와 SubagentStop 이벤트로 특정 서브 에이전트가 시작되거나 종료될 때 스크립트를 실행할 수도 있습니다.

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-reader",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ]
  }
}

포그라운드와 백그라운드

서브 에이전트는 포그라운드 또는 백그라운드에서 돌릴 수 있습니다.

포그라운드로 실행하면 작업이 끝날 때까지 메인 대화가 기다립니다. 권한 프롬프트나 질문이 사용자에게 직접 전달되니까 상호작용이 필요한 작업에 쓰기 좋아요.

백그라운드로 실행하면 메인 대화와 동시에 돌아갑니다. 시작 전에 필요한 도구 권한을 미리 확보하고 이후에는 사전 승인된 범위 안에서 자율적으로 동작해요. Ctrl+B를 눌러서 포그라운드 작업을 백그라운드로 보낼 수도 있습니다.

독립적인 조사를 여러 갈래로 진행해야 할 때 백그라운드 서브 에이전트가 빛을 발합니다.

인증 모듈, 데이터베이스 모듈, API 모듈을 각각 서브 에이전트로 병렬 탐색해줘

이렇게 요청하면 세 개의 서브 에이전트가 동시에 각 영역을 조사하고 Claude가 결과를 종합해줍니다.

항상 백그라운드에서 돌아야 하는 서브 에이전트라면 frontmatter에 background: true를 설정하면 됩니다. 린터나 테스트 감시처럼 메인 작업과 항상 병렬로 돌려야 하는 에이전트에 적합해요.

---
name: lint-watcher
description: 코드 변경 시 린트 검사를 백그라운드에서 실행합니다.
background: true
tools: Read, Glob, Grep, Bash
---

Git Worktree 격리

isolation: worktree를 설정하면 서브 에이전트가 임시 Git worktree에서 실행됩니다. 레포지토리의 격리된 복사본에서 작업하기 때문에 메인 작업 디렉토리에 영향을 주지 않아요. 서브 에이전트가 아무 변경도 하지 않으면 worktree는 자동으로 정리됩니다.

---
name: experimental-refactor
description: 실험적인 리팩토링을 격리된 환경에서 수행합니다.
isolation: worktree
---

여러 서브 에이전트가 동시에 서로 다른 파일을 수정해야 할 때 충돌 없이 병렬 작업할 수 있는 방법이기도 합니다.

서브 에이전트 재개

서브 에이전트는 기본적으로 매번 새 컨텍스트에서 시작합니다. 그런데 이전 작업을 이어서 하고 싶을 때가 있죠. 이때 재개(resume) 기능을 쓰면 됩니다. 재개된 서브 에이전트는 이전 대화 내용, 도구 호출 결과, 추론 과정까지 전부 유지한 채 작업을 이어갑니다.

code-reviewer 서브 에이전트로 인증 모듈을 리뷰해줘
[에이전트 완료]

이어서 인가 로직도 분석해줘
[Claude가 이전 컨텍스트를 유지한 채로 서브 에이전트를 재개]

서브 에이전트 대화 기록은 ~/.claude/projects/{프로젝트}/{세션ID}/subagents/에 파일로 저장됩니다. 메인 대화가 압축되더라도 서브 에이전트 기록은 영향을 받지 않습니다.

활용 패턴

서브 에이전트를 잘 활용하는 패턴을 몇 가지 소개합니다.

가장 흔한 건 대량 출력 격리입니다. 테스트 실행이나 로그 분석처럼 출력이 많은 작업을 서브 에이전트에게 맡기면 메인 컨텍스트를 깔끔하게 유지할 수 있어요. “서브 에이전트로 테스트를 돌리고 실패한 것만 에러 메시지와 함께 알려줘”라고 요청하면 되죠.

독립적인 탐색을 동시에 돌리는 병렬 조사도 유용합니다. 서브 에이전트가 각각 다른 영역을 탐색한 뒤 Claude가 결과를 종합하는 방식인데 탐색 경로가 서로 의존하지 않을 때 잘 동작해요.

여러 서브 에이전트를 순서대로 연결하는 순차 체인도 있습니다. “code-reviewer 에이전트로 성능 이슈를 찾고 optimizer 에이전트로 수정해줘”처럼 요청하면 첫 번째 결과를 바탕으로 두 번째가 이어서 작업하죠. 참고로 서브 에이전트가 또 다른 서브 에이전트를 생성할 수는 없습니다. 중첩 위임이 필요하다면 메인 대화에서 순차적으로 체인을 구성해야 해요.

서브 에이전트 vs 메인 대화

모든 작업을 서브 에이전트에게 넘기는 게 항상 좋은 건 아닙니다.

반복적인 피드백이 필요하거나 계획-구현-테스트가 하나의 흐름으로 이어지는 작업은 메인 대화에서 직접 하는 게 낫습니다. 한두 줄 빠르게 고치는 작업도 마찬가지고요. 서브 에이전트는 새로 시작할 때 컨텍스트를 다시 수집해야 해서 오버헤드가 좀 생기거든요.

반면 출력이 많거나 도구 제한이 필요하거나 독립적으로 완결되는 작업은 서브 에이전트에게 위임하는 게 좋습니다. 결과 요약만 돌려주니까 메인 대화 컨텍스트를 아낄 수 있어요.

Frontmatter 필드 한눈에 보기

지금까지 다룬 서브 에이전트 설정 필드를 한 테이블로 정리합니다. name과 description만 필수이고 나머지는 모두 선택 사항이에요.

마치며

서브 에이전트는 Claude Code의 컨텍스트 한계를 넘어서 복잡한 작업을 잘 나누는 방법입니다. 기본 제공되는 Explore, Plan, General-purpose 에이전트만으로도 Claude Code가 알아서 활용하지만 프로젝트에 맞는 커스텀 서브 에이전트를 만들면 워크플로우가 확 달라질 겁니다.

Claude Code에 대해 더 알고 싶다면 소개 포스팅을 참고하세요. AI 에이전트에게 절차적 지식을 전달하는 방법은 Agent Skills에서, 에이전트 동작을 세밀하게 제어하는 방법은 Hooks에서 다루고 있습니다. 코드를 작성하기 전에 설계를 검토하는 계획 모드도 내부적으로 서브 에이전트를 활용합니다. 대화 중 위임이 아니라 세션 전체를 하나의 에이전트로 전환하고 싶다면 —agent 플래그를 확인해보세요. 서브 에이전트를 넘어 여러 Claude 인스턴스가 팀으로 협업하는 구조가 궁금하다면 에이전트 팀도 살펴보세요. 서브 에이전트에게 작업을 체계적으로 분배하고 의존성을 관리하는 방법은 Tasks 가이드에서 다루고 있습니다. 공식 문서에서 더 자세한 내용을 확인할 수 있습니다.