[이제와서 시작하는 Claude AI 마스터하기 #12] Subagents로 AI 분업하기

혼자 모든 일을 할 필요 없습니다. Claude Code의 Subagent 시스템을 사용하면 특화된 AI 에이전트에게 작업을 위임할 수 있어요. 마치 팀에서 각자 전문 분야를 맡아 일하는 것처럼요!

완독 시간: 25분 ⭐⭐⭐⭐

🎯 이번에 배울 것

• Subagent란 무엇인가
• 내장 Subagent 활용하기
• 커스텀 Subagent 만들기
• 포그라운드 vs 백그라운드 실행
• 영속 메모리로 학습하는 에이전트

📚 사전 지식

• #11편: Skills - Skill 시스템 이해

---

📖 Subagent란 무엇인가?

한 줄 설명

Subagent = 특정 작업에 특화된 독립 AI 에이전트

각 Subagent는 자신만의 컨텍스트, 시스템 프롬프트, 도구 권한을 가집니다.

Skill vs Subagent

구분	Skill	Subagent
컨텍스트	메인 대화와 공유	독립된 컨텍스트
실행 방식	인라인 실행	별도 프로세스
결과 반환	직접 대화에 포함	요약해서 반환
적합한 용도	간단한 지시	복잡한 탐색/분석

왜 Subagent를 사용할까?

flowchart TD
    A[메인 대화] -->|위임| B[Explore Agent]
    A -->|위임| C[Code Reviewer Agent]
    A -->|위임| D[Test Runner Agent]
    B -->|결과 요약| A
    C -->|결과 요약| A
    D -->|결과 요약| A

장점:

1. 컨텍스트 보존: 탐색 결과가 메인 대화를 오염시키지 않음
2. 특화된 역할: 각 에이전트가 자기 분야에 집중
3. 병렬 처리: 여러 작업을 동시에 수행
4. 비용 절감: 빠른 모델(Haiku 4.5)로 단순 작업 처리

---

🔧 내장 Subagent 활용하기

Claude Code에는 세 가지 내장 Subagent가 있습니다.

1. Explore (탐색 전문가)

특징:

• 모델: Haiku 4.5 (빠르고 저렴)
• 도구: 읽기 전용 (Read, Grep, Glob)
• 용도: 코드베이스 탐색, 파일 검색

사용 예:

use the Explore agent to find all authentication-related files

Claude가 자동으로 Explore에 위임:

"인증 시스템 구조가 어떻게 되어있어?"

철저함 수준:

• quick: 빠른 기본 검색
• medium: 균형 잡힌 탐색
• very thorough: 포괄적 분석

2. Plan (계획 전문가)

특징:

• 모델: 메인과 동일
• 도구: 읽기 전용
• 용도: Plan Mode에서 리서치

사용 예: Plan Mode에서 Claude가 자동으로 사용:

Shift+Tab 두 번 (Plan Mode 진입)
"OAuth2 마이그레이션 계획 세워줘"

3. general-purpose (범용)

특징:

• 모델: 메인과 동일
• 도구: 모든 도구
• 용도: 복잡한 다단계 작업

사용 예:

have the general-purpose subagent refactor the entire auth module

---

🛠️ 커스텀 Subagent 만들기

방법 1: /agents 명령어 (권장)

/agents

인터랙티브 인터페이스가 열립니다:

1. Create new agent 선택
2. User-level 또는 Project-level 선택
3. Generate with Claude - Claude가 에이전트 생성
4. 도구, 모델, 색상 선택
5. 저장

방법 2: 직접 파일 생성

User-level (모든 프로젝트):

mkdir -p ~/.claude/agents

Project-level (이 프로젝트만):

mkdir -p .claude/agents

Subagent 파일 구조

.claude/agents/code-reviewer.md:

---
name: code-reviewer
description: 코드 변경사항을 리뷰합니다. 코드 작성 후 자동으로 사용하세요.
tools: Read, Glob, Grep
model: sonnet
---

당신은 시니어 코드 리뷰어입니다.

호출되면:
1. git diff로 변경사항 확인
2. 수정된 파일 분석

리뷰 체크리스트:
- 코드 가독성
- 이름 규칙
- 중복 코드
- 에러 처리
- 보안 취약점
- 테스트 커버리지

피드백 형식:
- 🔴 Critical (필수)
- 🟡 Warning (권장)
- 🟢 Suggestion (제안)

Frontmatter 필드

필드	설명
name	고유 식별자 (소문자, 하이픈)
description	Claude가 위임 판단시 참고
tools	허용 도구 목록
disallowedTools	금지 도구 목록
model	sonnet, opus, haiku, inherit
permissionMode	권한 모드
skills	미리 로드할 Skill 목록
hooks	라이프사이클 훅
memory	영속 메모리 범위

---

🎭 모델 선택하기

모델	특징	적합한 용도
haiku	Haiku 4.5 - 빠르고 저렴	단순 탐색, 파일 검색
sonnet	Sonnet 4.5 - 균형 잡힌 성능	코드 분석, 리뷰
opus	Opus 4.6 - 최고 성능	복잡한 아키텍처 결정
inherit	메인과 동일	기본값

---
name: quick-search
model: haiku
---

---

🔄 포그라운드 vs 백그라운드 실행

포그라운드 (기본)

• 메인 대화가 대기 상태
• 권한 요청이 사용자에게 전달됨
• 질문이 사용자에게 전달됨

use the code-reviewer subagent to check my changes
(대기... 작업 완료까지 기다림)

백그라운드

• 메인 대화 계속 진행 가능
• 사전에 필요한 권한 요청
• 완료 시 알림

run the test-runner in the background
(다른 작업 계속 가능)

백그라운드로 전환:

• “run this in the background” 요청
• 실행 중 Ctrl+B 누르기

백그라운드 비활성화

CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 claude

---

💾 영속 메모리 설정

Subagent가 세션을 넘어 학습하게 만들 수 있습니다.

memory 필드

---
name: code-reviewer
memory: user
---

당신은 코드 리뷰어입니다.
리뷰하면서 발견한 패턴, 규칙, 반복되는 이슈를 메모리에 기록하세요.

메모리 범위

범위	위치	용도
user	~/.claude/agent-memory/	모든 프로젝트에서 학습
project	.claude/agent-memory/	프로젝트별 학습 (Git)
local	.claude/agent-memory-local/	프로젝트별 (Git 제외)

메모리 동작

메모리가 활성화되면:

1. 에이전트의 시스템 프롬프트에 메모리 지시 추가
2. MEMORY.md 첫 200줄이 컨텍스트에 포함
3. Read, Write, Edit 도구 자동 활성화

활용 팁:

"이 PR 리뷰해줘, 그리고 발견한 패턴은 메모리에 기록해"

시간이 지나면서 에이전트가 프로젝트 특성을 학습합니다!

---

🪝 Hooks 설정

Subagent에 라이프사이클 훅을 추가할 수 있습니다.

Subagent 파일 내 Hooks

---
name: db-reader
description: 읽기 전용 DB 쿼리 실행
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly.sh"
---

검증 스크립트 예제

#!/bin/bash
# ./scripts/validate-readonly.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# INSERT, UPDATE, DELETE 등 차단
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP)\b' > /dev/null; then
  echo "Blocked: 읽기 전용입니다" >&2
  exit 2  # exit 2 = 작업 차단
fi

exit 0

---

🧪 실전 Subagent 예제

예제 1: 디버거

---
name: debugger
description: 에러, 테스트 실패, 예상치 못한 동작 디버깅. 문제 발생시 자동 사용.
tools: Read, Edit, Bash, Grep, Glob
---

당신은 디버깅 전문가입니다.

호출되면:
1. 에러 메시지와 스택 트레이스 수집
2. 재현 단계 파악
3. 실패 지점 격리
4. 최소한의 수정 구현
5. 해결 확인

디버깅 프로세스:
- 에러 메시지와 로그 분석
- 최근 코드 변경 확인
- 가설 수립 및 테스트
- 전략적 디버그 로깅 추가
- 변수 상태 검사

각 이슈에 대해:
- 근본 원인 설명
- 진단 근거
- 구체적 코드 수정
- 테스트 방법
- 예방 권장사항

예제 2: 데이터 사이언티스트

---
name: data-scientist
description: SQL 쿼리, BigQuery, 데이터 분석 전문가
tools: Bash, Read, Write
model: sonnet
---

당신은 SQL과 BigQuery 전문 데이터 사이언티스트입니다.

호출되면:
1. 데이터 분석 요구사항 이해
2. 효율적인 SQL 쿼리 작성
3. BigQuery CLI (bq) 사용
4. 결과 분석 및 요약
5. 명확한 발견사항 제시

핵심 원칙:
- 적절한 필터로 최적화된 쿼리
- 적절한 집계와 조인 사용
- 복잡한 로직에 주석 추가
- 결과를 읽기 쉽게 포맷
- 데이터 기반 권장사항 제공

예제 3: DB 읽기 전용 에이전트 (Hooks 활용)

---
name: db-reader
description: 읽기 전용 DB 쿼리. 데이터 분석, 리포트 생성시 사용.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

당신은 읽기 전용 DB 분석가입니다.
SELECT 쿼리만 실행하여 데이터를 분석합니다.

데이터 수정이 요청되면:
"저는 읽기 전용 권한만 있습니다. 데이터 수정은 DBA에게 문의하세요."

---

🎯 Subagent 활용 패턴

패턴 1: 대용량 출력 격리

테스트나 로그 분석은 출력이 많습니다. Subagent에 위임하면 메인 컨텍스트가 깔끔합니다.

use a subagent to run the test suite and report only failing tests

패턴 2: 병렬 리서치

독립적인 조사는 동시에 수행:

research the authentication, database, and API modules
in parallel using separate subagents

패턴 3: 체이닝

순차적으로 여러 에이전트 활용:

use the code-reviewer to find issues,
then use the optimizer to fix them

---

🤝 Agent Teams (연구 프리뷰)

여러 Claude 세션이 팀으로 협업하는 새로운 기능입니다.

활성화

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

동작 방식

flowchart TD
    A[리드 에이전트] -->|작업 분배| B[팀원 1: 프론트엔드]
    A -->|작업 분배| C[팀원 2: 백엔드]
    A -->|작업 분배| D[팀원 3: 테스트]
    B -->|결과 보고| A
    C -->|결과 보고| A
    D -->|결과 보고| A

• 각 팀원은 독립된 세션에서 작업
• 리드 에이전트가 작업 분배 및 조율
• TeammateIdle / TaskCompleted Hook 이벤트 지원

⚠️ 연구 프리뷰 기능으로 토큰 소비가 많습니다. 복잡한 다중 도메인 작업에 적합합니다.

---

🔒 Subagent 스폰 제한

에이전트가 생성할 수 있는 서브 에이전트를 제한할 수 있습니다:

---
name: team-lead
tools: Read, Grep, Glob, Task(code-reviewer), Task(test-runner)
---

Task(agent_type) 구문으로 특정 에이전트만 스폰 가능하도록 제한합니다.

---

⚠️ 주의사항

1. Subagent는 Subagent를 생성할 수 없음
   • 중첩 불가, 체이닝은 메인에서 조율
2. 메인 대화 컨텍스트 영향
   • Subagent 결과가 메인에 반환됨
   • 너무 많이 생성하면 컨텍스트 증가
3. 백그라운드 제한
   • 권한이 사전에 필요

---

📝 오늘 배운 것 정리

✅ Subagent = 독립 컨텍스트를 가진 특화 AI

✅ 내장 에이전트: Explore(탐색), Plan(계획), general-purpose(범용)

✅ 커스텀 생성: /agents 또는 .claude/agents/ 파일

✅ 모델 선택: haiku(Haiku 4.5, 빠름) / sonnet(Sonnet 4.5, 균형) / opus(Opus 4.6, 강력)

✅ 포그라운드/백그라운드: 대기 vs 병렬 작업

✅ 영속 메모리: memory 필드로 세션 넘어 학습

✅ Agent Teams: 여러 세션이 팀으로 협업 (연구 프리뷰)

---

🔗 다음 편 미리보기

#13편: MCP로 외부 도구 연결하기

Claude Code를 외부 세계와 연결:

• MCP (Model Context Protocol)란?
• GitHub, Database, Slack 연동
• OAuth 인증
• 실전 MCP 설정 예제

---

🔗 시리즈 전체 보기

#	제목	상태
01	Claude AI란? 첫 대화 시작하기	✅ 완료
02	프롬프트 엔지니어링 기초	✅ 완료
03	Claude의 다양한 모델과 선택 가이드	✅ 완료
04	API 활용 첫걸음	✅ 완료
05	고급 프롬프트 테크닉	✅ 완료
06	Claude Projects 활용하기	✅ 완료
07	Claude Code 시작하기	✅ 완료
08	Claude Code 작동 원리	✅ 완료
09	실전 워크플로우	✅ 완료
10	CLAUDE.md 완전 정복	✅ 완료
11	Skills: 나만의 명령어 만들기	✅ 완료
12	Subagents로 AI 분업하기	📖 현재 글
13	MCP로 외부 도구 연결하기	✅ 완료
14	IDE 통합 완벽 가이드	✅ 완료
15	GitHub Actions와 CI/CD 자동화	✅ 완료

---

🔗 참고 자료

• Subagents Documentation

---

🚀 분업은 효율의 시작입니다!