서브에이전트(Subagents)

[!tldr] 한줄 요약 서브에이전트는 메인 대화에서 독립된 컨텍스트 윈도우로 작업을 위임받는 전문 AI 어시스턴트로, 마크다운 파일이나 Agent SDK 코드로 정의하며 도구 제한, 모델 라우팅, 영구 메모리를 지원한다.

핵심 내용

서브에이전트란?

메인 에이전트가 Task 도구를 통해 생성하는 독립 실행 단위다. 각 서브에이전트는 별도의 컨텍스트 윈도우에서 커스텀 시스템 프롬프트, 제한된 도구, 독립 권한으로 동작한다.

핵심 가치 4가지:

• 컨텍스트 보존 — 탐색/구현 결과가 메인 대화를 오염시키지 않음
• 도구 제한 — 특정 도구만 허용해서 안전하게 격리
• 비용 제어 — Haiku 같은 저렴한 모델로 라우팅 (Cost 최적화)
• 전문화 — 도메인별 시스템 프롬프트로 특화된 행동

빌트인 서브에이전트

커스텀 서브에이전트 정의

.claude/agents/ 또는 ~/.claude/agents/에 마크다운 파일로 정의한다:

---
name: code-reviewer
description: Expert code review specialist. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit
model: sonnet
permissionMode: default
maxTurns: 20
memory: user
skills:
  - api-conventions
mcpServers:
  - slack
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate.sh"
---

시스템 프롬프트 내용...

frontmatter 필드

4가지 정의 방식과 우선순위

같은 name의 서브에이전트가 여러 위치에 있으면, 높은 우선순위가 낮은 것을 덮어쓴다. 프로젝트마다 같은 이름의 에이전트를 다르게 커스터마이즈할 수 있다.

실행 모드

Ctrl+B로 실행 중인 태스크를 백그라운드로 전환 가능. 백그라운드에서 권한 부족으로 실패하면 포그라운드로 resume하여 재시도할 수 있다.

영구 메모리(Persistent Memory)

서브에이전트에 세션을 넘나드는 학습 능력을 부여한다:

활성화 시 MEMORY.md 첫 200줄이 시스템 프롬프트에 자동 포함되고, Read/Write/Edit 도구가 자동 활성화된다.

Agent SDK에서의 서브에이전트

CLI 마크다운 파일 외에 프로그래밍 방식으로도 정의할 수 있다:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Review the auth module",
  options: {
    allowedTools: ["Read", "Grep", "Glob", "Task"],
    agents: {
      "code-reviewer": {
        description: "Expert code reviewer",
        prompt: "You are a code review specialist...",
        tools: ["Read", "Grep", "Glob"],
        model: "sonnet"
      }
    }
  }
})) {
  if ("result" in message) console.log(message.result);
}

Task 도구가 allowedTools에 있어야 서브에이전트 호출이 가능하다. 프로그래밍 방식 정의가 같은 이름의 파일 기반 정의보다 우선한다.

서브에이전트 vs Agent Teams

[!tip] 선택 기준 서브에이전트: 독립 단일 작업, 결과만 반환하면 되는 경우, 도구 격리 필요 시 Agent Teams: 장시간 협업, 컨텍스트 윈도우를 초과하는 큰 작업, 에이전트 간 소통 필요 시

주요 활용 패턴

1. 대량 출력 격리 — 테스트 실행, 로그 분석을 서브에이전트에 위임하면 메인에는 요약만 반환
2. 병렬 리서치 — 인증/DB/API 모듈을 각각 별도 서브에이전트로 동시 탐색
3. 체이닝 — code-reviewer → optimizer 순서로 연쇄 위임
4. 도구 허용 제어 — Task(worker, researcher)로 생성 가능한 서브에이전트 종류를 제한하거나, permissions.deny에 Task(agent-name)을 추가하여 특정 에이전트를 비활성화

예시

---
name: til-saver
description: TIL 저장 요청 시 사용. Daily/MOC/백로그 일괄 업데이트와 git commit 수행
tools: Read, Write, Edit, Glob, Grep, Bash
model: haiku
skills:
  - save
permissionMode: acceptEdits
---

TIL 저장 프로세스를 수행한다.
save 스킬의 워크플로우를 따라 TIL 파일, Daily 노트, MOC, 백로그를 업데이트하고 git commit한다.

[!example] 활용 기계적인 저장 작업을 Haiku 모델의 서브에이전트에 위임하면 메인 컨텍스트를 보존하면서 비용도 절감할 수 있다. skills: save로 저장 규칙이 자동 주입된다.

참고 자료

• Create custom subagents - Claude Code Docs
• Subagents in the SDK - Claude API Docs
• Task Tool vs. Subagents

관련 노트

• Claude Code Agent 동작 방식
• Agent Teams
• Claude Code Skill
• Context 관리(Context Management)
• Hooks
• Cost 최적화(Cost Optimization)