Claude Code Subagent 완벽 가이드 — 메인 세션 컨텍스트를 지키는 전문 에이전트 활용법

안녕하세요, 자바파커입니다.

"Claude Code로 큰 프로젝트 탐색하다가 컨텍스트가 순식간에 차버린 경험, 한 번씩 있으시죠?"

솔직히 저도 그랬습니다. Grep·Read로 파일 수십 개 열다 보면 정작 본 작업 시작도 전에 토큰이 반쯤 날아가 있고, 한 세션 안에서 서로 다른 성격의 작업(탐색·계획·리뷰·보안점검)을 섞으면 프롬프트가 중구난방이 됩니다. 디버깅 한 번 하자고 메인 대화 히스토리가 로그로 뒤덮이는 것도 흔한 일이죠.

결론부터 말씀드리면 — Subagent는 "메인 세션과 컨텍스트를 공유하지 않는 독립 에이전트"로, 이 문제를 구조적으로 해결합니다. 무거운 탐색·리뷰·연구 작업을 서브 에이전트로 분리하면 결과만 메인으로 돌아오고, 중간 과정은 메인 컨텍스트를 오염시키지 않습니다. 여러 작업을 병렬로 돌릴 수도 있습니다. 오늘은 이 개념부터 커스텀 에이전트 제작, 실전 설계 원칙까지 정리하겠습니다.

이 포스팅은 Claude Code Agent 시리즈 1편입니다. 다음 편 Agent Teams에서는 "서브 에이전트끼리 서로 통신하는 한 단계 위 개념"을 다룰 예정입니다.

Subagent란? — 한 줄 정의

Subagent는 Claude Code가 메인 세션에서 Task(Agent) 도구로 호출하는 독립된 Claude 인스턴스입니다.

핵심 3가지 특성:

비유하자면 — 사무실 본인(메인)은 큰 회의를 주재하고, 리서치 과제는 인턴(Subagent)에게 위임합니다. 인턴은 혼자 책장에서 자료를 뒤지고 요약본만 들고 옵니다. 본인 회의실은 조용히 유지됩니다.

왜 쓰는가 — 3가지 가치

1) 컨텍스트 격리 — 가장 큰 이유

대량 탐색·로그 확인·문서 읽기 같은 "보조 작업"이 메인 대화의 토큰을 먹어치우는 걸 막습니다. 같은 프로젝트를 3일째 붙잡고 있는 세션일수록 체감 효과가 큽니다.

2) 병렬화

독립된 작업이라면 한 메시지 안에서 여러 Subagent를 동시에 호출 가능합니다. 예: 프론트엔드 코드 스캔 + 백엔드 API 점검 + 테스트 커버리지 확인을 동시 진행.

3) 특화 (Specialization)

각 에이전트에 전용 시스템 프롬프트 + 도구 조합을 세팅할 수 있습니다. 보안 리뷰어는 Read·Grep만 허용, 테스트 러너는 Bash까지 허용 — 식으로 최소 권한 + 전문성을 동시에 얻습니다.

내장 Subagent 지도 — 기본 탑재 5가지

Claude Code에는 바로 쓸 수 있는 공식 에이전트들이 있습니다 (버전·설정에 따라 구성 다름).

실전 선택 팁

• 탐색 범위가 명확하지 않다 → general-purpose
• 그냥 "어디 있는지"만 알면 됨 → Explore
• 큰 변경을 설계해야 함 → Plan
• Claude Code 자체 문법·설정 질문 → claude-code-guide

커스텀 Subagent 만들기 — .claude/agents/

프로젝트 루트 혹은 유저 홈에 agent 정의 파일을 두면 Claude Code가 자동 인식합니다.

파일 위치와 범위

최소 정의 예시

<repo>/.claude/agents/security-reviewer.md:

---
name: security-reviewer
description: Use when reviewing code for OWASP Top 10, secrets exposure, or auth bugs. Proactively invoke after touching auth/session/input-validation code.
tools: Read, Grep, Glob
model: sonnet
---

You are a security-focused code reviewer.

For any code shown:

1. Scan for OWASP Top 10 patterns (injection, XSS, SSRF, auth bypass).
2. Flag hardcoded secrets, API keys, tokens.
3. Check session/cookie handling, CSRF protection.
4. Return a punch list with severity (High / Medium / Low) and file:line citations.

Keep report under 300 words. Don't lecture — just findings and fixes.

프론트매터 필드

좋은 Subagent 설계 원칙 5가지

1) description에 "when to use"를 명시

메인 Claude는 이 문장을 보고 자동으로 해당 에이전트에 작업을 라우팅합니다. "무엇을 하는지"보다 "언제 불려야 하는지"가 중요합니다.

description: Use when reviewing PRs for security, performance, or test coverage issues. Proactively invoke after large code changes.

2) Tool은 최소 권한으로

읽기만 하면 되는 리뷰어에게 Write·Bash를 열어두면, 에이전트 오작동이 실제 변경으로 이어집니다. blast radius를 좁히세요.

tools: Read, Grep, Glob # 리뷰어는 여기까지만

3) Self-contained 프롬프트

에이전트는 메인 세션을 보지 못합니다. "아까 말한 그 함수 있잖아"는 통하지 않습니다. 프롬프트 안에 필요한 모든 맥락(파일 경로, 목표, 제약)을 담으세요.

4) 결과 형식을 지정

자유 형식 에이전트는 메인 context에 쓰레기를 쏟아냅니다. "200자 이내 보고서", "체크리스트 형식", "JSON으로만 답변" 같은 제약이 필수.

5) Trust but verify

에이전트 리턴값은 "의도"입니다. 실제로 파일이 변경됐다면 Read/git diff로 검증하세요. "했다"와 "진짜 했다"는 다릅니다.

실전 예시 3개

예시 1) 블로그 톤 검토 에이전트

블로그 포스팅 톤이 프로젝트 가이드라인과 일치하는지 검증합니다.

.claude/agents/blog-tone-reviewer.md:

---
name: blog-tone-reviewer
description: Use to review draft blog posts for tone consistency. Checks greeting, conclusion-first pattern, SEO elements.
tools: Read, Grep, Glob
model: haiku
---

You review Korean dev-blog drafts against the project's tone guide.

Check:

1. Opens with "안녕하세요, 자바파커입니다"
2. Uses "~합니다" body (친근하되 가볍지 않음)
3. Conclusion stated early with "결론부터 말씀드리면"
4. Has frontmatter with title, description (150자 내), tags
5. Closes with a reader question
6. Has at least 2 section dividers (---)

Report deviations with line numbers and suggested fixes. Under 200 words.

호출:

Agent({
  subagent_type: "blog-tone-reviewer",
  prompt: "Review tistory/post/k8s-understanding.md for tone compliance."
})

예시 2) 보안 리뷰어 (병렬 호출)

PR 전체를 세 가지 관점으로 동시 검토.

Agent({ subagent_type: "security-reviewer", prompt: "Audit PR #42..." })
Agent({ subagent_type: "perf-reviewer", prompt: "Check perf regression in PR #42..." })
Agent({ subagent_type: "test-coverage-reviewer", prompt: "Validate test coverage of PR #42..." })

한 메시지에 세 개를 동시 호출 → 셋이 병렬 실행되고 결과가 모여 돌아옵니다. Agent Team과 달리 서로 대화하진 않지만, 단순 리뷰라면 이걸로 충분합니다.

예시 3) 리서치용 범용 에이전트 (내장 활용)

새 라이브러리 도입 전 조사:

Agent({
  subagent_type: "general-purpose",
  prompt: "Research pros/cons of using Drizzle ORM vs Prisma for a Next.js 15 project. Summarize under 300 words with a recommendation and two tradeoffs."
})

내장 general-purpose는 WebSearch·WebFetch도 쓸 수 있어 외부 문서 조사까지 가능합니다.

자주 겪는 이슈 3가지

1) "에이전트가 내가 방금 말한 걸 모른다"

→ 당연합니다. 에이전트는 메인 히스토리를 못 봅니다. 프롬프트에 직접 파일 경로·숫자·제약을 넣으세요.

2) "에이전트가 결과를 너무 장황하게 돌려준다"

→ description·프롬프트에 "Report in under 200 words" 같은 명시적 길이 제약을 넣으세요. 결과가 메인 context로 그대로 들어오기 때문에, 장황하면 오히려 손해입니다.

3) "간단한 작업인데 에이전트 쓰니 오히려 느리다"

→ 정확한 판단입니다. Subagent는 비용이 있는 선택입니다. 한두 번 grep이면 끝날 일은 직접 수행이 빠릅니다. "탐색이 3라운드 이상 될 것 같다" 싶을 때만 delegate하세요.

FAQ

Q. Subagent와 Skill, Slash Command의 차이는?

• Skill: 메인 세션 안에서 지식·도구 묶음을 로드하는 확장 (예: update-config)
• Slash Command: 사용자가 타이핑하는 매크로
• Subagent: 별도 Claude 세션으로 위임하는 작업 실행자

Skill·Command는 메인 컨텍스트에 머물고, Subagent만 컨텍스트를 분리합니다.

Q. 커스텀 에이전트는 어디에 둬야 팀 공유가 되나요?

<repo>/.claude/agents/*.md 에 넣고 Git에 커밋하세요. 같은 레포를 clone한 팀원 전원이 동일 에이전트를 자동 인식합니다.

Q. model: opus로 지정하면 비쌀텐데, 효과가 있나요?

리서치·복잡한 추론·계획 수립 같은 주제가 크고 깊은 작업에는 opus가 효과적입니다. 반면 형식 검증·패턴 탐지 같은 기계적 작업은 haiku로도 충분하고 비용이 훨씬 낮습니다. 에이전트별로 model을 다르게 지정하는 게 토큰 최적화의 핵심 지렛대입니다.

Q. Subagent 안에서 또 Subagent를 호출할 수 있나요?

허용되지 않습니다. 중첩 호출은 막혀 있습니다. 복잡한 협업이 필요하면 다음 편에서 다룰 Agent Teams를 쓰세요 (팀원 간 통신 가능).

마무리 — 다음 단계

Subagent는 "Claude Code 숙련도를 한 단계 올리는" 핵심 개념입니다. 쓰는 순간 메인 컨텍스트가 깔끔해지고, 토큰 사용도 훨씬 예측 가능해집니다.

오늘 정리 핵심:

• Subagent는 독립 컨텍스트 · 제한 도구 · 결과 반환의 3박자
• 가치는 컨텍스트 격리 · 병렬화 · 특화
• .claude/agents/*.md로 팀 공유 에이전트 제작
• 설계 원칙: description trigger · 최소 권한 · self-contained · 결과 형식 · verify
• 탐색 3라운드 이상 예상될 때만 delegate

시리즈 다음 편

2편: Claude Code Agent Teams — Subagent끼리 서로 통신하는 상위 개념

Agent Teams는 Subagent의 확장판으로, 팀원들이 공유 작업 목록으로 자체 조율하고 서로 메시지를 주고받습니다. 다음 편에서 자세히 다루겠습니다.

관련 포스팅

• Claude Code 입문 가이드 2026
• Claude Code 토큰 절약 — 초급 / 중급 / 고급

여러분은 어떤 커스텀 Subagent를 만들어 쓰고 계신가요? 댓글로 공유해주시면 다음 편에 활용 패턴으로 반영하겠습니다.