Claude Code Subagents: 실전 가이드 (2026)

Claude Code와 subagent를 매일 쓰는 개발자 Jasmine이 씁니다.

Claude Code의 subagent란 무엇인가요?

subagent는 메인 에이전트가 특정 작업을 처리하기 위해 띄울 수 있는 Claude의 특화된 인스턴스로, 자신만의 컨텍스트 윈도우와 자신만의 시스템 프롬프트, 자신만의 도구 세트를 가지고 실행된 뒤, 압축된 결과를 메인 에이전트에게 다시 보고해요. 한마디로, 하나의 Claude가 단일 대화 안에서 일 전체를 짊어지게 하는 대신, 작업을 작은 어시스턴트들에게 나누는 거예요. 각각이 하나의 역할에 특화된 AI 에이전트인 셈이죠.

메인 에이전트를 테크 리드라고 생각해 보세요. 큰 일이 들어왔을 때, 예를 들어 "코드베이스 전체를 보안 관점에서 리뷰해 줘" 같은 일이 오면, 테크 리드는 모든 파일을 자기 머릿속에서 읽지 않아요. 읽고 요약해서 보고해 주는 보안 전문가에게 넘기죠. subagent가 바로 그 전문가예요. 작업 설명(시스템 프롬프트)을 가지고, 일정한 권한(도구)을 부여받고, 일이 끝나면 정말로 필요한 결론만 돌려줘요.

같은 세션에 지시를 더 입력하는 것과의 핵심적인 차이는 이거예요. Claude Code의 subagent는 격리된 컨텍스트를 가져요. subagent가 일을 하기 위해 읽어야 하는 모든 중간 정보는 그 "머릿속"에 머물고, 절대 메인 세션으로 새어 나오지 않아요. 각 subagent는 .claude/agents/ 디렉터리에 두는 간단한 Markdown 파일로 선언하며, Claude Code가 자동으로 인식해요.

subagent는 어떻게 동작하나요? (컨텍스트 격리)

subagent 뒤에 있는 메커니즘은 컨텍스트 격리(context isolation)라고 불러요. 이것이 subagent를 쓸 만한 진짜 이유이고, 단지 "보여주기용으로 AI를 하나 더 띄우는" 것이 아니에요.

전형적인 실행은 이렇게 흘러가요.

1. 메인 에이전트가 여러분의 요청을 받아, 어떤 작업을 subagent에게 넘겨야 할지 결정해요.
2. 구체적인 작업 설명과 함께 그에 맞는 subagent를 띄워요.
3. subagent는 자신만의 컨텍스트 윈도우, 즉 "인지적 샌드박스" 안에서 실행돼요. 파일을 읽고, 명령을 실행하고, 문제를 추론하는 이 모든 걸 자기 공간 안에서 해요.
4. 끝나면 subagent는 전체 과정을 메인 세션에 쏟아붓는 대신, 압축된 결과(요약, 버그 목록, 코드 스니펫)만 돌려줘요.

You
 └─► Main agent (main context, lean)
 ├─► subagent: test-runner ──► returns: 2 tests failing
 ├─► subagent: security-scan ──► returns: 1 SQLi vulnerability
 └─► subagent: style-checker ──► returns: 5 lint warnings
 (each subagent = its own context window)

subagent가 무거운 컨텍스트(수십 개의 파일 읽기, 긴 로그)를 "삼키고" 그 핵심만 "내뱉기" 때문에, 메인 세션은 깔끔한 컨텍스트를 유지하며 더 오래 지속돼요. 이건 일부는 토큰 절약(메인 컨텍스트가 부풀지 않음)에 관한 것이고, 일부는 품질에 관한 것이에요. 메인 에이전트가 중간 잡음으로 오염되지 않으니, 추론이 더 날카롭게 유지되죠. 이 메커니즘과 범위는 Anthropic이 공식 Claude Code Subagents 문서(2026년 8월 접속)에서 설명하고 있어요.

이걸 새 채팅 탭을 손으로 여는 것과 구분하면 이해가 쉬워요. 여러 세션을 손으로 오가며 채팅할 때는, 여러분이 직접 결과를 이리저리 복사해 옮겨야 해요. 느리고 빠뜨리기 쉽죠. subagent를 쓰면 메인 에이전트가 흐름 전체를 오케스트레이션해요. 무엇을 누구에게 넘길지 정하고, 그 결과를 한 번의 작업 턴 안에서 자동으로 이어 붙여요. 터미널을 떠날 필요가 전혀 없어요.

사람들이 자주 오해하는 점이 하나 있어요. 컨텍스트 격리가 subagent를 "더 멍청하게" 만들지는 않아요. 여러분이 고른 것과 같은 모델 라인 그대로이고, 딱 필요한 도구만 가지고 정확히 하나의 작업에 집중할 뿐이에요. 범위를 좁히는 건 보통 출력을 나쁘게 하기는커녕 더 좋게 해요. 한 사람에게 한꺼번에 열 가지를 시키는 대신, 전문가에게 명확한 하나의 일을 맡기는 것과 같죠.

첫 subagent 만들기 - .claude/agents 파일

여기가 실습의 핵심 부분이에요. subagent를 만드는 방법은 두 가지예요. /agents 인터페이스를 쓰거나(처음이라면 추천), Markdown 파일을 직접 손으로 쓰거나. 둘 다 같은 결과물, 즉 .claude/agents/ 안의 파일을 만들어요.

1단계 - 에이전트 매니저 열기

Claude Code 세션 안에서 이렇게 입력하세요.

/agents

인터페이스는 기존 에이전트를 목록으로 보여주고, 새 에이전트 만들기, 스코프 고르기, 모델 고르기, 메뉴로 도구 제한하기를 할 수 있게 해줘요. 직접 제어하고 싶다면 이 단계를 건너뛰고 파일을 직접 써도 돼요. 결과는 똑같아요.

2단계 - 스코프 고르기: 프로젝트냐 사용자냐

에이전트 파일을 둘 곳은 두 군데이고, 올바른 쪽을 고르는 게 중요해요.

• 프로젝트 레벨 - 프로젝트 폴더 안의 .claude/agents/. 이 프로젝트에만 적용되고, Git에 커밋하면 팀 전체가 공유할 수 있어요. 프로젝트에 특화된 에이전트(예: 팀의 관례를 이해하는 리뷰어)에는 이쪽을 고르세요.
• 사용자 레벨 - 홈 디렉터리의 ~/.claude/agents/. 여러분의 모든 프로젝트에 적용돼요. 어디서나 손쉽게 쓰고 싶은 에이전트(예: 범용 문서 작성기)에는 이쪽을 고르세요.

이름이 겹치면 프로젝트 레벨 에이전트가 사용자 레벨보다 우선해요.

3단계 - 에이전트 파일 쓰기 (실제 예시)

아래 내용으로 .claude/agents/code-reviewer.md 파일을 만드세요. 위쪽은 YAML 프론트매터이고, 본문은 subagent의 시스템 프롬프트예요.

---
name: code-reviewer
description: Review code for bugs, security, and maintainability. Use right after you write or change code.
tools: Read, Grep, Glob
model: sonnet
---

You are a senior-level code reviewer. Your job:
- Read the code that just changed (use Read/Grep/Glob, do NOT edit files).
- Find logic bugs, security holes, and hard-to-maintain spots.
- Rank findings by severity: critical / should-fix / suggestion.
- Return a short list with file paths and line numbers.
Do not run write commands, do not commit, do not change code.

4단계 - 확인하기

다시 /agents를 실행해 code-reviewer가 목록에 나타나는지 확인하세요. 이게 다예요. 여러분은 방금 첫 subagent를 만들었어요. 이제부터는 코드를 막 바꾼 직후라면 언제든 Claude가 자동으로 그것을 호출할 수 있고, 직접 호출할 수도 있어요. "code-reviewer subagent를 써서 방금 바꾼 걸 살펴봐 줘"처럼요.

프론트매터 필드 (name, description, tools, model)

프론트매터가 subagent의 동작 방식을 결정해요. 기억할 필드는 딱 네 개예요.

무게값을 하는 두 가지 팁: (1) 동사와 상황을 넣어 명확한 description을 쓰세요("~한 직후에 사용" 등). 이것이 바로 Claude가 알맞은 때에 알맞은 에이전트를 자동 호출하는 데 쓰는 것이니까요. (2) 읽기 전용 에이전트에는 tools를 Read, Grep, Glob로 제한하세요. 그러면 subagent는 물리적으로 실수로라도 파일을 편집하거나 삭제할 수 없게 돼요.

subagent 호출과 관리

subagent를 작동시키는 방법은 세 가지예요.

1. 자동 위임 - Claude가 description 필드를 바탕으로 알맞은 subagent를 골라요. 여러분은 평소처럼 작업하면 되고, 컨텍스트가 맞아떨어질 때(예: 코드 편집을 막 끝낸 직후) Claude가 알아서 code-reviewer에게 넘겨요.
2. 직접 호출 - 요청에서 에이전트를 지목하세요. "code-reviewer subagent를 써서 결제 모듈을 확인해 줘"처럼요. 무엇이 필요한지 정확히 알 때 가장 확실한 방법이에요.
3. /agents로 관리 - 인터페이스를 열어 에이전트를 목록으로 보고, 편집하거나 삭제하고, 파일을 손으로 열지 않고도 모델을 바꾸거나 도구를 더하거나 빼세요.

불려야 한다고 생각하는데도 subagent가 "전혀 호출되지 않는다"면, 범인은 거의 언제나 너무 모호한 description이에요. 구체적으로 다시 쓰면 해결돼요.

병렬 실행과 여러 subagent 오케스트레이션

여기가 subagent가 진짜로 빛나는 지점이고, 대부분의 가이드가 건너뛰는 부분이에요. 각 subagent가 자신만의 컨텍스트에서 실행되기 때문에, 메인 에이전트는 같은 코드베이스에 대해 여러 subagent를 한꺼번에 펼칠(fan out) 수 있어요.

예시: subagent 세 개를 병렬로

방금 기능을 하나 끝냈고 PR을 열기 전에 전체 점검을 하고 싶다고 해봐요. 순차적으로 하는 대신 이렇게 요청하세요.

Run 3 subagents in parallel on the current branch:
- test-runner: run the full test suite, report which tests fail
- security-scanner: scan the code that just changed for vulnerabilities
- style-checker: check lint and conventions
Combine all three into a single report.

세 에이전트는 각자 독립적으로 실행되며 필요한 것을 스스로 읽고, 그다음 메인 에이전트가 세 개의 간결한 보고서를 합쳐요. 시간과 컨텍스트를 모두 아끼는 거죠.

토큰 측면에서는 "몇 퍼센트 절약"을 기대하기 전에 메커니즘부터 제대로 알아야 해요. 절약되는 건 총 토큰 수가 아니에요. 에이전트 셋을 돌리면 셋 모두의 토큰이 여전히 들어요. 절약되는 건 메인 세션의 토큰이에요. 모든 테스트 로그, 보안 스캔 흔적, lint 경고는 각 subagent의 컨텍스트 안에 머물고, 되돌아오는 건 결론 몇 줄뿐이에요. 그게 바로 메인 세션이 일찍 가득 차는 걸 막아 주고 더 긴 사고의 흐름을 유지하게 해줘요. 그게 진짜 이점이지, 고정된 퍼센트가 아니에요.

여러 계층 오케스트레이션

한 단계 위로: 한 subagent의 출력이 다음 subagent의 입력이 돼요. 전형적인 explore -> plan -> implement 흐름은 이래요.

1) subagent "explorer": survey the codebase, return a module map + spots to change.
2) Feed that result to subagent "planner": lay out a step-by-step plan.
3) Feed the plan to subagent "implementer": execute it step by step.

이건 강력한 오케스트레이션 패턴이지만, 그 밑에 깔린 한 가지 중요한 한계를 이해해야 해요.

반드시 알아야 할 한계

subagent들은 서로 직접 컨텍스트를 공유하지 않고 서로 "대화"하지도 않아요. 결과를 메인 에이전트에게 돌려줄 뿐이고, 다음 subagent에게 정보를 전달하는 건 메인 에이전트예요. 매 실행마다 한 번의 토큰 왕복이 생겨요. 그래서 여러 계층 오케스트레이션에는 진짜 힘이 있는 동시에 비용도 있어요. 남용하지 마세요. subagent가 Skills/Hooks/MCP와 정확히 어떻게 다른지 이해하려면 Skills, Subagents, Hooks, MCP를 비교하는 가이드를 읽어 보세요.

지금 바로 쓸 만한 subagent 템플릿 몇 가지

복사해서 붙여 넣을 수 있는 네 가지 템플릿이에요. 가볍게 손보고 바로 시작하세요.

1. 읽기 전용 리뷰어 (절대적으로 안전)

---
name: safe-reviewer
description: Read-only code review that never edits files. Use to inspect before a merge.
tools: Read, Grep, Glob
model: sonnet
---
You only read and comment. Never run write commands. Return findings ranked by severity.

2. Test-runner

---
name: test-runner
description: Run the test suite and summarize failures. Use after editing code.
tools: Bash, Read, Grep
model: haiku
---
Run the project's tests, read the output, list failing tests with a short cause each.

3. Doc-writer

---
name: doc-writer
description: Write/update documentation and docstrings for new code.
tools: Read, Grep, Glob, Edit
model: sonnet
---
Read the code, write clear docs that match the repo's style. Do not change code logic.

4. Explorer

---
name: explorer
description: Survey an unfamiliar codebase, return an architecture map and entry points.
tools: Read, Grep, Glob
model: sonnet
---
Map out the modules, data flow, and the important files. Read only, never edit.

네 템플릿 모두를 눈여겨보세요. 쓸 필요가 없는 에이전트에는 쓰기 권한을 주지 않았어요. 그건 지킬 만한 안전한 습관이에요.

subagent는 Skills, Hooks, MCP와 어떻게 다른가요?

이 네 가지 빌딩 블록은 자주 헷갈려요. 빠르게 구분하는 방법은 이거예요.

요약하면: subagent는 일을 나누고, Skills는 절차를 가르치고, Hooks는 이벤트를 자동화하고, MCP는 연결을 확장해요. 어느 것을 골라야 할지 아직 헷갈린다면 네 가지 빌딩 블록 전체 비교가 더 깊이 파고들어요.

흔한 실수와 진짜 한계

이 섹션을 굳이 쓰는 블로그는 거의 없지만, 이게 바로 subagent를 올바르게 쓰는 데 도움을 주는 부분이에요.

• 과도한 위임. 아주 작은 작업(변수 하나 이름 바꾸기, 한 줄 고치기)을 subagent로 나누는 건 역효과예요. 토큰 왕복과 지연 시간이 직접 하는 것보다 더 비싸요. subagent는 "컨텍스트는 무겁고 결과는 가벼운" 작업을 위한 거예요.
• 모호한 description은 자동 호출이 안 돼요. description이 두루뭉술하면 Claude는 언제 넘겨야 할지 몰라요. 사용할 구체적인 상황을 적어 두세요.
• tools 제한을 잊는 것. 읽기만 해야 하는데 쓰기 권한을 받은 리뷰어는 엉뚱한 파일을 편집할 수 있어요. 언제나 최소한의 권한만 부여하세요.
• 에이전트를 너무 많이 펼쳐 토큰을 태우는 것. 에이전트 5~6개를 병렬로 돌리면 그럴듯해 보이지만, 각각이 과금되는 독립 세션이에요. 목적을 가지고 펼치세요.
• 나누면 안 되는 때: 작업이 현재 대화의 전체 컨텍스트를 필요로 할 때예요(예: 앞선 모든 세부가 중요한 긴 흐름을 디버깅하는 경우). subagent는 메인 컨텍스트를 볼 수 없으니, 떼어 내면 정작 필요한 그 컨텍스트를 잃게 돼요.

직접 쓰는 수고를 덜기 - AgentKit의 45개 사전 제작 에이전트

좋은 subagent를 쓰려면 프롬프트를 다듬고 몇 번이고 테스트하는 수고가 들어요. 처음부터 직접 쓰는 대신 특화된 에이전트의 완성된 라이브러리를 원한다면, AgentKit의 45개 사전 제작 에이전트가 선택적인 지름길이 될 수 있어요. 이건 Claude Code용 키트로(OpenAI의 AgentKit이 아니라 - 그냥 이름이 겹칠 뿐이에요), 108개 이상의 스킬과 함께 45개 에이전트 = 17개 Engineer + 28개 Marketing을 함께 제공해요. 결정하기 전에 에이전트 카탈로그를 둘러보고 싶다면 AgentKit의 45개 사전 제작 에이전트 개요를 읽어 보세요. Engineer Kit은 99달러예요(사이트에 반복 결제 언급은 없어요). 그렇긴 해도, 자기 저장소의 관례에 맞는 에이전트를 몇 개 써 보는 건 여전히 배울 가치가 있는 기초 역량이에요. 키트는 그저 여러분이 더 빨리 나아가도록 도와줄 뿐이죠.

자주 묻는 질문 (FAQ)

subagent는 돈이 더 드나요?

네, 간접적으로요. 각 subagent는 자신만의 컨텍스트를 가진 세션이라서 자기 토큰을 써요. 여러 개를 병렬로 돌리면 단일 세션보다 토큰을 더 많이 쓰죠. 대신 메인 컨텍스트가 더 가볍게 유지되니, 컨텍스트가 무거운 작업에서는 전체적으로 여전히 효율적일 수 있어요.

subagent는 몇 개까지 병렬로 실행할 수 있나요?

한꺼번에 여러 subagent를 펼칠 수 있지만, 실제 필요에 맞게 제한해야 해요(리뷰 작업이라면 보통 3~4개가 적당해요). 많이 펼칠수록 토큰을 더 태우고 추적하기도 더 어려워져요.

subagent가 메인 대화를 기억하나요?

아니요. 각 subagent는 격리된 컨텍스트 윈도우에서 실행되며, 메인 에이전트가 일부러 넘겨준 것을 빼고는 메인 세션의 기록을 볼 수 없어요. 그게 강점(깔끔한 컨텍스트)인 동시에 염두에 둬야 할 한계이기도 해요.

subagent는 Skills와 어떻게 다른가요?

subagent는 일을 배정받아 독립적으로 실행되는 특화된 서브 AI예요. Skills는 Claude가 따르도록 로드되는, 패키징된 지시/절차예요. 하나는 "여러분 대신 일을 해주고", 다른 하나는 "하는 방법을 가르쳐줘요".

에이전트를 프로젝트 레벨에 둬야 하나요, 사용자 레벨에 둬야 하나요?

팀을 위해 커밋하고 싶은 프로젝트 특화 에이전트는 프로젝트 레벨(.claude/agents/)에 두세요. 모든 프로젝트에서 쓰고 싶은 에이전트는 사용자 레벨(~/.claude/agents/)에 두세요. 이름이 겹치면 프로젝트 레벨이 이겨요.

Claude Code Pro가 필요한가요?

subagent는 Claude Code 기능이에요. 이미 가입한 어떤 요금제 안에서든 쓰면 돼요. 요금제 세부 사항(월 20달러 Pro, Max 등)은 Claude Code가 무엇인지를 참고하세요.

마무리와 다음 단계

subagent는 Claude Code를 혼자 일하는 어시스턴트에서 작은 팀으로 바꿔줘요. 일을 나누고, 병렬로 실행하고, 컨텍스트를 깔끔하게 유지하죠. 읽기 전용 code-reviewer로 간단하게 시작하고, 그 힘과 한계를 모두 파악한 뒤에 오케스트레이션으로 넓혀 가세요. subagent와 skill을 짝지으려면 다음으로 Claude Code Skills가 무엇인지를 읽어 보고, 알맞은 도구를 고르려면 네 가지 빌딩 블록 비교를 보세요. 그리고 처음부터 직접 쓰고 싶지 않다면, 사전 제작 에이전트 라이브러리를 갖춘 AgentKit 번들 — 지금 149달러(198달러에서)을 써 보세요.