Subagents

Eleven·2026년 4월 15일

Hello, Claude Code

목록 보기

7/11

요약

Subagent는 메인 Claude가 특정 작업을 위임하는 전문 AI 어시스턴트다. 독립된 컨텍스트 윈도우에서 실행되어 컨텍스트 오염을 방지하고, 전문 분야에 집중한 높은 품질의 결과를 반환한다. 실습을 통해 code-reviewer Subagent를 직접 설치하고 실제 코드 리뷰를 받아봤다.

개념 정리

지금까지 배운 것들과의 비교

CLAUDE.md   →  기억 (세션 간 유지되는 컨텍스트)
Hooks       →  자동화 (이벤트 발생 시 강제 실행)
MCP         →  연결 (외부 도구에 접근)
Subagents   →  위임 (전문 에이전트에게 작업 분담)

왜 필요한가

메인 Claude 혼자 모든 걸 다 하면 두 가지 문제가 생긴다.

문제 1: 컨텍스트 오염
  코드 리뷰 + 테스트 작성 + 보안 분석을 동시에 하면
  서로의 내용이 섞여서 품질이 떨어짐

문제 2: 깊이 부족
  "모든 걸 아는 제너럴리스트"보다
  "한 분야의 전문가"가 더 정확한 결과를 냄

Subagent는 독립된 컨텍스트에서 시작해서 자기 전문 분야에만 집중한다.

파일 위치

.claude/agents/          ← 프로젝트 전용 (팀 공유, git 커밋됨)
~/.claude/agents/        ← 전역 (모든 프로젝트에서 사용 가능)

CLAUDE.md, Hooks, MCP와 동일한 패턴이다.

Subagent 파일 구조

---
name: code-reviewer
description: Expert code review specialist. Use PROACTIVELY after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer...

description 필드가 핵심이다. Claude가 이 설명을 읽고 언제 자동으로 이 Subagent를 써야 하는지 판단한다. "Use PROACTIVELY"라고 쓰면 코드 수정 후 Claude가 자동으로 호출한다.

*PROACTIVELY
Claude가 자율적이고 선제적으로 코드 변경 사항을 검토하거나 작업을 처리하도록 유도하는 핵심 키워드

model 필드는 사용할 모델을 지정한다.

inherit  →  메인 대화의 모델을 그대로 사용
sonnet   →  항상 Sonnet 사용
haiku    →  가벼운 작업에 Haiku로 비용 절약
opus     →  복잡한 분석에 Opus 사용

호출 방법 3가지

# 방법 1: 자연어 (Claude가 자동으로 적합한 Subagent 선택)
> 최근 변경 코드를 리뷰해줘

# 방법 2: 명시적 지정
> code-reviewer 서브에이전트를 사용해서 최근 변경 코드 리뷰해줘

# 방법 3: @ 접두사 (자동 선택 무시하고 강제 지정)
> @code-reviewer 최근 변경 코드를 리뷰해줘

레포 실습 파일 목록 (04-subagents/)

code-reviewer.md         ← 코드 품질, 보안, 성능 리뷰
test-engineer.md         ← 테스트 작성 및 커버리지 확인
documentation-writer.md  ← 문서 자동 생성
secure-reviewer.md       ← 보안 전문 리뷰
implementation-agent.md  ← 기능 구현 전문

실습 — code-reviewer 설치 및 동작 확인

1. 레포 클론 및 이동

cd ~/IdeaProjects
git clone https://github.com/luongnv89/claude-howto.git
cd claude-howto/claude-howto

2. agents 폴더 생성 및 파일 복사

mkdir -p .claude/agents
cp 04-subagents/code-reviewer.md .claude/agents/

3. 설치 확인

claude
/agents

Agent Library에 아래처럼 표시되면 성공이다.

Project (.claude/agents)
└── code-reviewer · inherit     ← 설치 완료

Built-in agents (always available)
├── claude-code-guide · haiku
├── general-purpose · inherit
└── ...

4. 실제 동작 테스트

@code-reviewer 04-subagents/code-reviewer.md 파일을 리뷰해줘

실습에서 받은 리뷰 결과 요약:

Critical:
- 파일이 "배포용 에이전트 정의"와 "튜토리얼 문서" 두 역할을 동시에 수행
  → Example Review 섹션이 매 호출마다 시스템 프롬프트에 포함되어 토큰 낭비

Warning:
- Review Priorities 5개 항목과 Checklist 8개 항목 간 매핑 불일치
- 출력 형식 예시가 명세와 불일치 (코드 블록 없이 산문 형태)

Suggestion:
- 호출 예시 추가 권장
- 언어 중립적인 예시로 교체

메인 Claude에게 같은 질문을 했을 때보다 훨씬 구조화되고 구체적인 피드백이 나왔다. Subagent의 전문화 효과가 실제로 확인된 것이다.

전체 조합 워크플로우

MCP(GitHub)로 PR 가져오기
→ code-reviewer Subagent가 코드 품질 리뷰
→ secure-reviewer Subagent가 보안 검사
→ test-engineer Subagent가 테스트 커버리지 확인
→ Hooks로 결과 자동 저장

핵심 요약 (TL;DR)

Subagent = 독립 컨텍스트에서 실행되는 전문 AI 어시스턴트
컨텍스트 오염 방지 + 전문 분야 깊이 있는 결과가 핵심 장점
description 필드가 자동 호출 트리거 역할을 함
@에이전트명으로 강제 지정, 자연어로 자동 위임 모두 가능
.claude/agents/(프로젝트), ~/.claude/agents/(전역) — 동일한 패턴
CLAUDE.md + Hooks + MCP + Subagents 네 가지가 합쳐지면 완성형 자동화

다음에 알아볼 것

Module 09: Advanced Features — Agent Teams로 Subagents끼리 직접 소통하는 패턴
secure-reviewer, test-engineer Subagent 직접 설치 및 테스트
나만의 Subagent 직접 작성해보기

[Series] Claude Code Fundamentals - Subagents

Summary

A Subagent is a specialized AI assistant that the main Claude delegates tasks to. It runs in an isolated context window, preventing context contamination and producing higher-quality results by focusing on a specific domain. In practice, we installed the code-reviewer Subagent and received an actual code review.

Key Concepts

Comparison with Everything Learned So Far

CLAUDE.md   →  Memory (context that persists across sessions)
Hooks       →  Automation (enforced execution on lifecycle events)
MCP         →  Connection (access to external tools)
Subagents   →  Delegation (task distribution to specialized agents)

Why They Are Needed

Two problems arise when the main Claude handles everything alone.

Problem 1: Context contamination
  Doing code review + writing tests + security analysis simultaneously
  causes content to mix, reducing quality

Problem 2: Lack of depth
  A "specialist in one domain" produces more accurate results
  than a "generalist who knows everything"

Subagents start with a clean context and focus entirely on their domain.

File Location

.claude/agents/          ← Project-specific (team-shared, git-committed)
~/.claude/agents/        ← Global (available across all projects)

Same pattern as CLAUDE.md, Hooks, and MCP.

Subagent File Structure

---
name: code-reviewer
description: Expert code review specialist. Use PROACTIVELY after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer...

The description field is the key. Claude reads it to decide when to automatically invoke this Subagent. Writing "Use PROACTIVELY" tells Claude to call this agent automatically after code modifications.

The model field specifies which model to use.

inherit  →  Use whatever model the main conversation is using
sonnet   →  Always use Sonnet
haiku    →  Use Haiku for lightweight tasks (cost-saving)
opus     →  Use Opus for complex analysis

3 Ways to Invoke

# Method 1: Natural language (Claude auto-selects the right Subagent)
> Review my recent code changes

# Method 2: Explicit specification
> Use the code-reviewer subagent to review my recent changes

# Method 3: @ prefix (forces a specific Subagent, bypasses auto-selection)
> @code-reviewer review my recent code changes

Repo Practice Files (04-subagents/)

code-reviewer.md         ← Code quality, security, performance review
test-engineer.md         ← Test writing and coverage verification
documentation-writer.md  ← Automatic documentation generation
secure-reviewer.md       ← Security-focused review
implementation-agent.md  ← Feature implementation specialist

Practice — Installing and Testing code-reviewer

1. Clone the Repo and Navigate

cd ~/IdeaProjects
git clone https://github.com/luongnv89/claude-howto.git
cd claude-howto/claude-howto

2. Create agents Folder and Copy File

mkdir -p .claude/agents
cp 04-subagents/code-reviewer.md .claude/agents/

3. Verify Installation

claude
/agents

Success looks like this in the Agent Library:

Project (.claude/agents)
└── code-reviewer · inherit     ← Installed

Built-in agents (always available)
├── claude-code-guide · haiku
├── general-purpose · inherit
└── ...

4. Test in Action

@code-reviewer review the file 04-subagents/code-reviewer.md

Summary of review results received during practice:

Critical:
- File serves dual purpose: "agent definition" and "tutorial document"
  → Example Review section included in system prompt on every call = token waste

Warning:
- Mismatch between Review Priorities (5 items) and Checklist (8 items)
- Output format example inconsistent with spec (prose instead of code blocks)

Suggestion:
- Add invocation examples
- Replace TypeScript-specific examples with language-neutral ones

The feedback was far more structured and specific than asking the main Claude directly. The specialization effect of Subagents was confirmed in practice.

Complete Combined Workflow

Fetch PR via MCP (GitHub)
→ code-reviewer Subagent reviews code quality
→ secure-reviewer Subagent checks security
→ test-engineer Subagent verifies test coverage
→ Hooks automatically save results

TL;DR

Subagent = specialized AI assistant running in an isolated context window
Core advantages: prevents context contamination + deeper domain expertise
The description field acts as the auto-invocation trigger
Use @agent-name to force a specific agent, or natural language for auto-delegation
.claude/agents/ (project), ~/.claude/agents/ (global) — same pattern as always
CLAUDE.md + Hooks + MCP + Subagents combined = complete automation system

Eleven

이전 포스트

MCP (Model Context Protocol)

다음 포스트