13. Subagents(서브에이전트)

🎯 이 장의 목표

서브에이전트가 무엇이고 왜 컨텍스트 보호에 핵심인지 이해한다
내장 서브에이전트(Explore·Plan·general-purpose)를 안다
커스텀 서브에이전트를 만들고 도구·모델을 제한한다
서브에이전트의 권한 한계와 에이전트 팀(Agent Teams)을 안다

서브에이전트란

서브에이전트는 부모 세션에서 Task(=Agent) 도구로 띄우는 독립된 Claude 인스턴스입니다. 자기만의 컨텍스트 윈도우, 자기만의 도구 목록을 갖고 일한 뒤, 결과 요약만 메인 대화로 돌려줍니다.

비유하자면, 조사가 필요한 일을 전문 조사원에게 위임하는 것입니다. 조사원은 자기 책상(컨텍스트)에서 자료를 잔뜩 펼쳐놓고 일하지만, 당신 책상엔 깔끔한 요약 한 장만 올려놓습니다.

flowchart TB
    Main[메인 세션<br/>깨끗한 컨텍스트 유지]:::agent
    Main -->|Task로 위임| Sub[서브에이전트<br/>자기 컨텍스트에서 작업]:::sub
    Sub -->|파일 읽기·검색<br/>잡다한 출력 가둠| Work[(대량의 탐색 결과)]:::tool
    Sub -->|요약만 반환| Main

    classDef agent fill:#80DEEA,stroke:#00ACC1,color:#000
    classDef sub fill:#80DEEA,stroke:#00ACC1,color:#000,stroke-dasharray: 5 5
    classDef tool fill:#90CAF9,stroke:#1E88E5,color:#000

📌 핵심 가치는 컨텍스트 격리입니다. 50개 파일을 뒤지는 조사를 메인 세션에서 하면 컨텍스트가 잡동사니로 가득 차지만, 서브에이전트에 맡기면 그 무거운 작업이 별도 컨텍스트에서 일어나고 메인은 깨끗합니다. "Claude가 드리프트한다"는 불만의 상당수는 사실 컨텍스트 오염 문제입니다.

언제 서브에이전트를 쓸까

쓰기 좋은 경우	부적합한 경우
독립적 작업의 병렬 처리	메인 흐름과 긴밀히 얽힌 작업
대량 검색·탐색으로 컨텍스트 보호	사용자 승인이 자주 필요한 편집 작업(아래 한계 참고)
좁게 스코프된 작업에 깨끗한 출발	단순한 한두 파일 읽기(직접 Read가 빠름)

⚠️ 흔한 실수

한 가지 균형 감각: 멀티 에이전트가 유행이지만, 대부분의 작업엔 메인 스레드 하나로 충분합니다. 진짜 병렬성·컨텍스트 격리가 목적일 때만 서브에이전트를 쓰세요. 과한 위임은 오히려 오버헤드입니다.

내장 서브에이전트

Claude Code에는 세 가지 내장 서브에이전트가 있습니다.

이름	특징	용도
Explore	읽기 전용, 작은 컨텍스트(CLAUDE.md·git status 생략)	코드베이스 탐색에 가장 비용 효율적
Plan	읽기 전용, 계획 수립	Plan Mode의 탐색 단계 (→ 7장)
general-purpose	모든 도구 사용	범용 다단계 작업

💡 팁

6장에서 본 "열린 탐색은 Agent에게"가 바로 이것입니다. "인증이 어디서 처리되지?" 같은 질문엔 Explore가 메인 컨텍스트를 지키며 답을 찾아옵니다.

명시적으로 시킬 수도 있습니다:

CODE

> 이 코드를 보안 이슈 관점에서 서브에이전트로 리뷰해줘

커스텀 서브에이전트 만들기

서브에이전트는 YAML frontmatter를 가진 마크다운 파일입니다. .claude/agents/(프로젝트) 또는 ~/.claude/agents/(개인)에 저장합니다.

MARKDOWN

---
name: code-reviewer
description: 코드 품질·보안·유지보수성 전문 리뷰어.
  코드를 작성·수정한 직후 즉시 사용.
tools: Read, Grep, Glob, Bash
model: sonnet
---
당신은 높은 코드 품질과 보안 기준을 지키는 시니어 코드 리뷰어입니다.
다음을 점검하세요:
- 주입 취약점(SQL·XSS·커맨드 인젝션)
- 인증/인가 결함
- 코드에 노출된 비밀·자격증명
- 안전하지 않은 데이터 처리
구체적인 라인 참조와 수정 제안을 제시하세요.

자주 쓰는 frontmatter 필드: name, description, model, tools(허용 도구), disallowedTools(금지 도구), effort, maxTurns, skills(미리 로드할 스킬), memory(메모리 범위), isolation(값은 worktree만).

Claude는 작업 유형에 따라 자동 위임하거나, @에이전트이름·claude --agent <name>으로 명시 호출합니다.

💡 팁

비용 절감: 잡일(파일 검색·로그 스캔)에는 model을 더 싸고 빠른 모델로 지정하고, 실제 추론은 강한 모델에 맡기면 품질을 지키며 비용을 아낍니다(→ 22장).

⚠️ 중요한 권한 한계

서브에이전트는 사용자에게 대화형 승인 프롬프트를 띄울 수 없습니다. 그래서 서브에이전트가 ask 규칙에 걸리는 도구를 호출하면 거부로 처리됩니다.

권장 패턴:

서브에이전트는 읽기 전용 도구로 제한(frontmatter tools에서 Edit·Write·NotebookEdit 빼기)
실제 편집·Bash 작업은 승인을 처리할 수 있는 부모 에이전트에게 맡기기

flowchart LR
    Sub[서브에이전트<br/>읽기 전용·탐색]:::sub -->|발견·요약| Parent[부모 에이전트]:::agent
    Parent -->|승인받아 편집·실행| Apply[Edit / Write / Bash]:::tool

    classDef sub fill:#80DEEA,stroke:#00ACC1,color:#000,stroke-dasharray: 5 5
    classDef agent fill:#80DEEA,stroke:#00ACC1,color:#000
    classDef tool fill:#90CAF9,stroke:#1E88E5,color:#000

📌 핵심

단, statusline-setup처럼 편집 범위가 좁고 예측 가능한 내장 서브에이전트는 예외입니다.

서브에이전트의 메모리

서브에이전트는 memory: frontmatter로 자기만의 메모리 범위를 가질 수 있습니다(user·project·local). 전체 메모리 계층을 상속받는 대신 집중된 컨텍스트로 일하게 하는 것입니다. 자기만의 자동 메모리도 쌓을 수 있습니다(→ 10장).

에이전트 팀(Agent Teams)

단일 서브에이전트를 넘어, 여러 Claude 인스턴스가 공유 작업 목록으로 협업하는 것이 에이전트 팀입니다. 여러 바운디드 컨텍스트에 걸치거나 병렬 작업 스트림이 필요한 거대 기능에 적합합니다(7장에서 예고).

서브에이전트와의 차이는 조율(coordination) 입니다. 서브에이전트는 일을 받아 요약을 돌려주는 단방향이지만, 에이전트 팀은 여러 일꾼이 작업 목록을 공유하며 진행합니다.

⚠️ 흔한 실수

에이전트 팀·멀티 에이전트는 강력하지만 디버깅이 어렵고 비용이 큽니다. "간단한 제어 루프가 멀티 에이전트 시스템을 이긴다"는 격언을 기억하고, 정말 필요할 때만 도입하세요.

이 장에서 배운 것

서브에이전트는 자기 컨텍스트에서 일하고 요약만 돌려주는 독립 Claude 인스턴스다. 핵심 가치는 컨텍스트 격리.
내장 Explore(탐색)·Plan(계획)·general-purpose(범용)가 있고, Explore가 탐색에 가장 효율적이다.
커스텀 서브에이전트는 .claude/agents/의 마크다운+frontmatter로 만들고, tools·model로 도구·두뇌를 제한한다.
서브에이전트는 승인 프롬프트를 못 띄운다 → 읽기 전용으로 두고 편집은 부모에게 맡긴다.
거대 작업은 에이전트 팀으로 가되, 과한 멀티 에이전트는 피한다.

✍️ 확인 문제

서브에이전트의 핵심 가치인 "컨텍스트 격리"가 무엇이며 왜 중요한가요?
서브에이전트에 편집 도구(Edit·Write)를 주지 말고 읽기 전용으로 두라는 권장의 이유는 무엇인가요?
잡일용 서브에이전트의 비용을 줄이려면 frontmatter에서 무엇을 조정하나요?

다음 장: 14. MCP 서버 연동 — Claude를 외부 세계(깃허브·DB·브라우저)와 잇기.

← 이전12. Skills(에이전트 스킬)다음 →14. MCP 서버 연동