클로드 코드 서브에이전트 사용법과 만들기 — 2026년 8월판

요약: 클로드 코드 서브에이전트, 어떻게 만들고 언제 써야 하나?

• 서브에이전트는 .claude/agents/ 아래 마크다운 파일 하나다. 필수 frontmatter는 name과 description 둘뿐이고, 나머지 13개는 선택이다.
• 2025년 글 대부분이 안내하는 /agents 대화형 패널은 v2.1.198에서 삭제됐다. 지금은 파일을 직접 쓰거나 Claude에게 쓰게 한다.
• 서브에이전트가 해결하는 건 속도가 아니라 컨텍스트 오염이다. 중간 과정이 결론보다 훨씬 긴 작업만 넘긴다.
• 함정: 배경 설명이 많이 필요한 작업을 빈 컨텍스트 서브에이전트에 던지면 오히려 느려진다. 그럴 땐 대화를 통째로 물려받는 /subtask 포크를 쓴다. 그리고 "빈틈을 찾아라"고 시킨 리뷰어는 코드가 멀쩡해도 뭔가를 찾아낸다 — 공식 문서가 직접 경고하는 대목이다.
• 병렬 수단이 넷으로 늘었다(서브에이전트 / agent view / agent teams / dynamic workflows). 선택 기준은 아래 표에 있다.

최종 업데이트 2026-08-25. 필드명과 버전은 code.claude.com 현행 문서 기준.

2025년 글대로 따라 하면 막히는 지점

문법이 조금 바뀐 정도가 아니라, 만드는 방법 자체가 달라졌다.

모델도 세대가 통째로 바뀌었다. 지금은 claude-opus-5, claude-sonnet-5, claude-fable-5, claude-haiku-4-5다. 날짜 접미사를 붙이면 안 된다 — claude-opus-5가 완전한 ID다.

서브에이전트가 푸는 문제는 하나다

서브에이전트는 CPU 코어가 아니다. 같은 일을 두 배 빨리 해주는 물건이 아니라 메인 대화가 쓰레기로 차는 걸 막는 물건이다. 공식 베스트 프랙티스도 컨텍스트 창이 성능의 근본 제약이라는 문장으로 시작한다.

"이 API 호출 지점 다 찾아봐"를 메인 세션에 시키면 그 세션은 grep 결과로 절반이 찬다. 정작 시키려던 리팩터링에 쓸 자리가 없다. 같은 지시를 서브에이전트에 넘기면 탐색은 그쪽에서 타고 본류로는 결론 몇 줄만 돌아온다. 판단 기준은 하나다. 중간 과정이 결론보다 훨씬 길면 위임하고, 아니면 직접 시킨다.

파일 위치와 우선순위

정의는 마크다운 파일이며 위쪽이 이긴다.

1. 관리형 설정 → 2. --agents CLI 플래그 → 3. .claude/agents/(프로젝트, 팀 공유) → 4. ~/.claude/agents/(개인) → 5. 플러그인의 agents/

3번과 4번은 하위 폴더까지 재귀 스캔한다. .claude/agents/review/security.md 같은 정리가 가능하다. 팀이 같은 리뷰어를 쓰게 하려면 프로젝트에, 개인 취향에 가까운 검사기는 홈 디렉터리에 둔다.

frontmatter 전체 필드

필수는 name(소문자·하이픈, 콜론 불가)과 description 둘. 자동 위임이 description 한 문장을 보고 판단하므로, 여기가 부실하면 그 에이전트는 영영 호출되지 않는다.

공식 문서의 최소 예시는 이렇다.

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

2026년 필드까지 쓰면 이렇게 된다. 저장 위치는 .claude/agents/security-reviewer.md.

---
name: security-reviewer
description: >
  Reviews a diff for injection, authz, and secret-handling issues.
  Use after any change touching auth, DB queries, or external input.
tools: Read, Glob, Grep, Bash
model: opus
effort: high
isolation: worktree
memory: project
---

You review diffs for security defects only.

Report format:
- 파일:줄 — 문제 — 왜 위험한가 — 최소 수정안
발견이 없으면 "no findings"라고만 답하라. 없는 문제를 만들지 마라.

tools를 읽기 전용으로 좁힌 건 취향이 아니다. 리뷰어에게 쓰기 권한을 주면 리뷰 대신 수정을 시작한다. 읽기 전용 리뷰어와 쓰기 가능한 실행자를 나누는 게 설계의 기본이다.

호출하는 세 가지 방법

자동 위임은 description을 보고 Claude가 알아서 넘긴다. 편하지만 보장이 없다. 자연어로 Use the test-runner subagent to fix failing tests처럼 이름을 부를 수도 있다. 반드시 돌아야 하는 단계라면 @"code-reviewer (agent)" 멘션을 쓴다. 이건 실행을 보장한다. 세션 전체를 특정 에이전트로 돌리려면 claude --agent code-reviewer로 시작한다.

현재 세션의 백그라운드 항목은 /tasks, 워크플로는 /workflows로 본다. /agents로 뭔가 관리하려 들면 안 된다. 이름이 비슷한 claude agents는 완전히 다른 기능이다.

실제로 효과가 나는 네 가지 패턴

범위를 준 조사. "결제 관련 코드 다 찾아줘"를 격리하고 결과는 파일 목록과 요약만 받는다.

적대적 리뷰. 구현한 세션이 자기 작업을 채점하게 두면 안 된다. 새 컨텍스트의 리뷰어에게 diff만 보여준다. 번들 /code-review 스킬이 30주차부터 이걸 백그라운드 서브에이전트로 수행한다. 아래 실패 모드 5번을 반드시 함께 읽어야 한다.

포크(/subtask). 일반 서브에이전트는 빈 컨텍스트로 시작하지만 /subtask로 띄운 서브에이전트는 지금까지의 대화 전체를 물려받는다(툴 호출과 결과만 격리된다). 한 시간 쌓아 온 맥락에서 곁가지 하나를 떼어낼 때 쓴다. 33주차부터 포크 모드가 대화형 세션 기본값이고, agent view를 끄면 명령이 /fork로 바뀌면서 /subtask는 사라진다.

/batch. 큰 변경을 5~30개 서브에이전트로 쪼개 각각 별도 워크트리에서 작업하고 각자 PR을 연다. 조각마다 독립적인 일괄 리네이밍 같은 작업에 맞는다.

클로드코드 병렬 실행 수단 네 가지 비교

규모 감각을 위한 숫자. 동시 에이전트 최대 16개, 1회 실행 총 1,000개. 25개를 넘거나 예상 토큰 150만을 넘으면 Large workflow 경고가 뜬다. 스크립트 안에서는 import()와 파일시스템 직접 접근이 막혀 있고 실행 중 사용자 입력도 받을 수 없다(v2.1.154+).

모델·effort·툴·스키마·작업 디렉터리가 같은 형제 에이전트끼리는 프롬프트 캐시를 공유한다. 캐시 히트를 만들려고 클로드 코드가 첫 응답이 시작될 때까지 나머지를 최대 5초 붙잡는다. 형제 에이전트 설정을 무의미하게 제각각으로 만들지 말아야 할 이유다.

Channels는 외부 이벤트를 실행 중 세션에 밀어 넣는 기능이지 병렬 실행 수단이 아니다. 위 표에 넣지 않은 이유다.

서브 에이전트의 흔한 실패 모드

대부분 공식 문서가 직접 경고하는 항목이다.

1. 범위 없는 "조사해줘". 수백 파일을 읽으며 컨텍스트를 태운다. 범위를 좁히든 격리하든 하나는 해야 한다.
2. 컨텍스트가 부족한 서브에이전트. 브리핑을 길게 쓰느니 /subtask 포크가 낫다.
3. 파일 충돌. agent teams는 워크트리 격리를 해주지 않는다. 파일 분할은 직접 해야 한다. 서브에이전트는 isolation: worktree로 격리한다.
4. 팬아웃 중간 중단이 비싸다. 재개하면 미완료 에이전트보다 나중에 시작된 에이전트는 이미 끝났어도 전부 재실행된다. 큰 에이전트 하나보다 작은 에이전트 여럿이 진행을 더 보존한다.
5. 리뷰어 과잉 신뢰. 빈틈을 찾으라고 시킨 리뷰어는 멀쩡한 작업에서도 뭔가를 찾아내고, 전부 쫓아가면 과잉 엔지니어링으로 간다. 리뷰 결과는 입력이지 지시가 아니다.
6. 모델 선택 방치. 워크플로의 모든 에이전트는 세션 모델을 그대로 쓴다. 큰 실행 전 /model을 확인하고 가벼운 단계는 작은 모델로 지정한다.
7. 전부 위임하려는 것. 결과 diff를 한 문장으로 설명할 수 있으면 직접 시키는 게 빠르다. 위임에도 고정 비용이 있다.

비용 감각

서브에이전트를 여럿 돌리면 토큰이 배수로 늘고 그게 플랜 한도에 그대로 잡힌다. 병렬 실행은 공짜로 빨라지는 게 아니라 시간을 토큰으로 사는 거래다. /usage가 스킬·서브에이전트·플러그인·MCP 서버별로 한도 소모를 분해해준다(21주차부터). 워크플로를 크게 한 번 돌린 뒤 열어보면, 다음엔 어느 단계를 haiku로 내릴지 판단할 근거가 생긴다.

다음에 읽을 것

왜 이렇게 설계해야 하는지 이론 배경은 하네스 엔지니어링이 다섯 요소로 정리해 뒀다. 맥에서 GUI로 여러 세션을 관리하고 싶다면 Conductor 사용법이 별도 앱 쪽 선택지다.

하나만 덧붙이면, CLAUDE.md와 서브에이전트를 같은 서랍에 넣으면 안 된다. CLAUDE.md는 매 세션 항상 로드되고 스킬과 서브에이전트는 필요할 때만 로드된다. 그래서 CLAUDE.md는 짧아야 하고 서브에이전트 정의는 길어도 된다. 배치와 병합 순서는 CLAUDE.md 위치와 작성법에서 따로 다뤘다.

출처

• Anthropic Claude Code 서브에이전트 문서