클로드 코드 서브에이전트 실전 (조사와 검수 나누기)

Q: 특정 서브에이전트를 못 쓰게 할 수 있나요?

권한 규칙의 deny에 `Agent(Explore)`처럼 적으면 그 서브에이전트를 막을 수 있습니다.

클로드 코드 서브에이전트는 주 대화와 분리된 컨텍스트에서 따로 일하고 요약만 돌려주는 보조 에이전트로, 자기 시스템 프롬프트와 도구 권한, 모델을 따로 가집니다. 긴 조사와 결과 검수를 서브에이전트에 나눠 맡기면 주 대화의 컨텍스트가 덜 찹니다.

같은 말:클로드 코드 서브에이전트 만들기.claude/agentsExplore 에이전트서브에이전트 병렬agent-name 멘션

홍승협(준이아빠)게시 2026.10.02코스 5 / 10번째 개념

새로 올라온 개념이에요. 먼저 읽어 보고 퀴즈도 풀어 보세요

#AI #자동화 #바이브코딩

🤔 조사 결과가 대화창을 가득 채울 때
🔑 클로드 코드 서브에이전트의 정의
🧰 이미 들어 있는 서브에이전트
📄 서브에이전트 파일 형식과 위치
🧠 컨텍스트가 나뉘는 방식
🔍 조사와 검수를 나누는 구성
📞 서브에이전트를 부르는 방법
⚡ 병렬 실행과 비용
⚠️ 자주 하는 실수
❓ 자주 묻는 질문
📋 3줄 요약
📚 참고 자료

이 글은 앤트로픽이 운영하는 code.claude.com/docs의 Subagents 문서와 Costs 문서를 한국어 사용자가 실무에 바로 옮길 수 있도록 정리한 글입니다. 필드 이름과 버전은 2026년 9월 28일 공식 문서 기준이고, 원문 링크는 글 끝 참고 자료에 모았습니다.

🤔 조사 결과가 대화창을 가득 채울 때

"이 저장소에서 결제 관련 코드를 다 찾아 정리해 줘"라고 하면 클로드는 파일 수십 개를 열고 검색 결과를 쏟아 냅니다. 조사가 끝났을 때는 그 내용이 전부 대화에 남아 있어서, 정작 고칠 단계에 들어가면 컨텍스트가 반쯤 차 있습니다. 게다가 방금 만든 결과물을 같은 대화에서 검수하게 하면 자기가 쓴 것을 너그럽게 보는 경향이 생깁니다.

서브에이전트는 이 두 문제에 쓰는 도구입니다. 서브에이전트가 무엇인지는 입문 코스의 서브에이전트 알아보기에 있으므로, 지금부터는 직접 만드는 파일 형식, 컨텍스트가 어떻게 나뉘는지, 조사와 검수를 나누는 구성, 병렬 실행의 비용을 정리합니다.

🔑 클로드 코드 서브에이전트의 정의

클로드 코드 서브에이전트는 주 대화와 분리된 컨텍스트에서 따로 일하고 요약만 돌려주는 보조 에이전트로, 자기 시스템 프롬프트와 도구 권한, 모델을 따로 가집니다.

공식 문서가 꼽는 이점은 다섯 가지입니다. 주 대화의 컨텍스트를 아끼고, 쓸 수 있는 도구를 제한하고, 설정을 재사용하고, 역할에 맞게 행동을 좁히고, 더 싼 모델로 비용을 줄입니다. 서브에이전트는 한 세션 안에서 동작하는 기능이고, 여러 세션을 동시에 돌리는 백그라운드 에이전트나 세션끼리 협업하는 에이전트 팀과는 다른 기능입니다.

🧰 이미 들어 있는 서브에이전트

직접 만들지 않아도 클로드 코드에는 서브에이전트가 몇 개 들어 있습니다.

이름	하는 일	특징
Explore	파일 찾기와 코드 검색	읽기 전용, quick, medium, very thorough 세 가지 깊이
Plan	플랜 모드에서 계획 전 조사	읽기 전용
general-purpose	탐색과 수정이 모두 필요한 여러 단계 작업	쓸 수 있는 도구를 모두 사용

Explore와 Plan은 빠르고 싸게 돌도록 CLAUDE.md와 git 상태를 읽지 않습니다. 프로젝트 규칙을 알아야 하는 조사라면 직접 만든 서브에이전트를 씁니다.

📄 서브에이전트 파일 형식과 위치

서브에이전트는 YAML frontmatter가 붙은 마크다운 파일 하나입니다. 본문이 그 서브에이전트의 시스템 프롬프트가 됩니다. 공식 예시는 다음과 같습니다.

---
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.

파일은 프로젝트의 .claude/agents/나 내 모든 프로젝트에 쓰는 ~/.claude/agents/에 둡니다. 같은 이름이 겹치면 관리 정책, 시작 옵션 --agents, 프로젝트, 사용자, 플러그인 순서로 앞선 것이 쓰입니다. 파일을 추가하거나 고치면 몇 초 안에 반영되지만, 세션을 시작할 때 없던 agents 폴더를 새로 만들었다면 다시 시작해야 합니다.

필드	하는 일
`name`, `description`	필수. 이름과 언제 쓰는지. 자동 위임의 기준
`tools`	쓸 수 있는 도구. 생략하면 전부 물려받음
`disallowedTools`	빼 둘 도구
`model`	`sonnet`, `opus`, `haiku`, `fable`, `inherit` 등
`permissionMode`	서브에이전트의 권한 모드
`skills`	시작할 때 전문을 넣어 줄 스킬
`isolation`	`worktree`면 임시 git 워크트리에서 실행
`maxTurns`	최대 턴 수

permissionMode는 주 대화가 bypassPermissions, acceptEdits, auto일 때는 무시되고 주 대화의 모드를 따릅니다. 서브에이전트에게만 주 대화보다 넓은 권한을 줄 수는 없는 구조입니다.

🧠 컨텍스트가 나뉘는 방식

공식 문서는 서브에이전트가 새로 비어 있는 컨텍스트에서 시작한다고 설명합니다. 주 대화의 기록, 이미 부른 스킬, 클로드가 이미 읽은 파일을 보지 못하고, 클로드가 써 준 위임 메시지를 받아 일을 시작합니다.

처음 받는 것: 자기 시스템 프롬프트, 위임 메시지, CLAUDE.md(Explore와 Plan 제외), git 상태, skills 필드로 지정한 스킬
받지 못하는 것: 주 대화 기록, 주 대화의 자동 메모리, 출력 스타일

그래서 꼭 지켜야 할 규칙은 위임 요청에 다시 적으라고 문서가 안내합니다. 반대로 대화 전체를 물려받아야 하는 작업이라면 v2.1.212 이상에서 /subtask로 대화를 통째로 넘기는 방식이 있습니다.

주 대화에서 할 일과 서브에이전트에 넘길 일도 공식 문서가 나눠 둡니다. 주고받기가 잦거나 여러 단계가 같은 맥락을 공유하거나 빠르게 끝나는 작은 수정은 주 대화에서 합니다. 출력이 길고, 도구를 제한해야 하고, 요약만 돌려받으면 되는 독립 작업은 서브에이전트에 넘깁니다.

🔍 조사와 검수를 나누는 구성

실무에서 가장 쓸모 있는 구성은 조사와 검수를 각각 서브에이전트로 떼는 것입니다. 아래는 공식 필드로 준이아빠블로그가 구성한 예시입니다.

---
name: researcher
description: 코드베이스에서 관련 파일을 찾고 핵심만 요약한다. 조사, 위치 찾기, 영향 범위 확인 요청에 먼저 쓴다.
tools: Read, Glob, Grep
model: haiku
---

요청받은 주제와 관련된 파일 경로와 핵심 줄만 표로 돌려준다.
파일을 고치지 않는다. 확인하지 못한 것은 확인하지 못했다고 적는다.

---
name: reviewer
description: 방금 바뀐 코드를 검토해 문제만 보고한다. 수정이 끝난 뒤 검수 요청에 쓴다.
tools: Read, Glob, Grep, Bash
---

git diff로 바뀐 부분을 읽고 버그, 빠진 예외 처리, 규칙 위반만 목록으로 보고한다.
칭찬과 요약은 쓰지 않는다. 고치지 않는다.

조사용은 읽기 도구만 주고 가벼운 모델을 지정해 비용을 줄입니다. 검수용은 결과물을 만든 대화와 다른 컨텍스트에서 보게 되므로, 같은 대화 안에서 스스로 검수할 때 문제를 놓치기 쉬운 점을 덜 수 있습니다. 준이아빠블로그의 하네스 엔지니어링 입문도 결과물을 만든 에이전트에게 검수까지 맡기지 않는 구성을 권합니다.

공식 문서가 드는 흔한 패턴도 이 구성과 맞닿아 있습니다.

긴 출력 떼어 내기: "서브에이전트로 테스트를 돌리고 실패한 테스트만 보고해 줘"
병렬 조사: "인증, 데이터베이스, API 모듈을 서브에이전트로 나눠 동시에 조사해 줘"
연결: "code-reviewer로 성능 문제를 찾고, optimizer로 고쳐 줘"

📞 서브에이전트를 부르는 방법

자동 위임: 클로드가 요청과 description을 보고 판단합니다. 더 적극적으로 쓰게 하려면 설명에 "use proactively" 같은 문구를 넣습니다
이름으로 요청: "researcher 서브에이전트로 찾아 줘"처럼 말하면 클로드가 위임합니다
@멘션: @agent-researcher처럼 부르면 그 작업에는 반드시 그 서브에이전트가 실행됩니다
세션 전체: claude --agent code-reviewer로 시작하면 세션 전체가 그 서브에이전트로 동작합니다

v2.1.198부터 /agents 명령은 대화형 생성 화면을 열지 않고 안내만 출력합니다. 서브에이전트를 만들려면 클로드에게 요청하거나 .claude/agents/에 파일을 직접 씁니다. 지금 실행 중인 서브에이전트와 모델은 /tasks로 봅니다.

⚡ 병렬 실행과 비용

서브에이전트는 기본으로 20개까지 동시에 돌고, 서브에이전트가 다시 서브에이전트를 부르는 중첩은 3단계까지입니다. 다만 비용 문서는 서브에이전트가 자기 요청을 따로 보내며 주 대화와 같은 사용량 한도에서 차감된다고 적습니다. 공식 문서의 경고를 그대로 옮기면, 자세한 결과를 돌려주는 서브에이전트를 여럿 돌리면 컨텍스트를 크게 쓰고 각자 실행 중에 자기 토큰도 씁니다.

그래서 병렬 실행은 조사 경로가 서로 의존하지 않을 때만 쓰고, 결과는 표나 목록으로 짧게 돌려받도록 시스템 프롬프트에 적습니다. 간단한 작업은 model: haiku로 두라는 것도 비용 문서의 권고입니다. 사용량 관리 전체는 클로드 코드 비용과 한도 관리에서 이어집니다.

⚠️ 자주 하는 실수

서브에이전트가 대화 내용을 안다고 가정합니다: 새 컨텍스트에서 시작하므로 필요한 조건은 위임 요청에 적습니다
조사용 서브에이전트에 쓰기 도구를 줍니다: tools를 생략하면 모든 도구를 물려받습니다. 읽기 도구만 적습니다
의존 관계가 있는 일을 병렬로 돌립니다: 앞 결과가 필요한 일은 차례로 연결합니다
설명을 길게 씁니다: 서브에이전트 설명의 합계가 15,000토큰을 넘으면 시작할 때 경고가 뜹니다. 자세한 내용은 본문에 적습니다

❓ 자주 묻는 질문

스킬과 서브에이전트는 무엇이 다른가요?

스킬은 지금 대화에 절차와 지침을 더하고, 서브에이전트는 별도 컨텍스트에서 일한 뒤 요약만 돌려줍니다. 절차를 따르게 하려면 스킬, 긴 출력을 떼어 내거나 다른 눈으로 검수하려면 서브에이전트가 맞습니다.

특정 서브에이전트를 못 쓰게 할 수 있나요?

권한 규칙의 deny에 Agent(Explore)처럼 적으면 그 서브에이전트를 막을 수 있습니다.

서브에이전트가 파일을 고쳐도 되나요?

됩니다. 다만 여러 서브에이전트가 같은 파일을 동시에 고치면 서로 덮어쓸 수 있으므로, 수정하는 서브에이전트에는 isolation: worktree를 두어 별도 워크트리에서 일하게 하는 방법이 있습니다.

📋 3줄 요약

클로드 코드 서브에이전트는 .claude/agents/의 마크다운 파일로 정의하고, 새 컨텍스트에서 일한 뒤 주 대화에는 요약만 돌려줍니다.
서브에이전트는 주 대화 기록과 자동 메모리를 보지 못하므로 꼭 지킬 규칙은 위임 요청에 다시 적고, 조사용은 읽기 전용 도구와 가벼운 모델로 둡니다.
서브에이전트마다 자기 토큰을 쓰고 같은 사용량 한도에서 차감되므로, 병렬 실행은 서로 의존하지 않는 조사에만 쓰고 결과는 짧게 받습니다.

📚 참고 자료

서브에이전트 문서: https://code.claude.com/docs/en/sub-agents
비용 관리 문서: https://code.claude.com/docs/en/costs
권한 규칙 문서: https://code.claude.com/docs/en/permissions
명령 목록 문서: https://code.claude.com/docs/en/commands

제대로 이해했는지 한 문제로 확인해 볼까요?

답을 고르면 바로 풀이가 나와요.

서브에이전트가 작업을 시작할 때 처음부터 볼 수 있는 것은 무엇일까요?

6개념 / 클래스클로드 코드 MCP 서버 연결하기 (설정 파일, 권한, 오류)