Day 3: 서브 에이전트 & /clear, /compact 활용
AI Tools Mastery Curriculum — Week 1, Day 3 소요 시간: 45분 | 실습 중심
핵심 배운 점
- 서브 에이전트는 별도 컨텍스트에서 동작, 메인을 오염시키지 않음
- Task()로 최대 10개 병렬 서브 에이전트 생성 가능
- /clear(완전 초기화) vs /compact(요약 압축) 판단 기준 명확히
- 50% 컨텍스트 사용 시 수동 /compact 실행 권장
① Task() 서브 에이전트 개념 학습
서브 에이전트란
Claude Code는 단일 AI가 아니다. 필요에 따라 별도의 Claude 인스턴스를 스폰(spawn) 해서 작업을 위임할 수 있다. 이것이 서브 에이전트다.
핵심 개념은 컨텍스트 격리다. 서브 에이전트는 자체 컨텍스트 윈도우에서 동작하기 때문에, 메인 대화를 오염시키지 않고 방대한 탐색/분석 작업을 수행할 수 있다.
메인 에이전트 (내 대화)
├─ Task() → 서브 에이전트 A (자체 컨텍스트) → 결과 요약만 반환
├─ Task() → 서브 에이전트 B (자체 컨텍스트) → 결과 요약만 반환
└─ Task() → 서브 에이전트 C (자체 컨텍스트) → 결과 요약만 반환
만약 서브 에이전트 없이 메인 대화에서 직접 웹 검색을 10번 하면, 검색 결과가 전부 컨텍스트에 쌓여서 토큰을 빠르게 소진한다. 서브 에이전트에 위임하면 검색 결과는 서브 에이전트의 컨텍스트에만 남고, 메인에는 요약만 돌아온다.
서브 에이전트를 쓰는 두 가지 이유
첫째, 컨텍스트 보존. 대규모 코드베이스를 탐색하면 수십 개 파일을 읽어야 하는데, 이 내용이 전부 메인 컨텍스트에 쌓이면 이후 작업 품질이 떨어진다. 서브 에이전트가 탐색하고 핵심만 보고하면 메인 컨텍스트는 깨끗하게 유지된다.
둘째, 병렬 처리. 서브 에이전트는 동시에 여러 개를 띄울 수 있다 (최대 10개). 순차적으로 하면 30분 걸릴 작업을 병렬로 10분에 끝낼 수 있다.
Claude Code의 내장 서브 에이전트 유형
Claude Code에는 이미 내장된 서브 에이전트가 있다:
| 유형 | 용도 | 언제 자동 호출되나 |
|---|---|---|
| general-purpose | 복잡한 리서치, 멀티스텝 작업, 코드 수정 | Task()로 직접 스폰하거나, Claude가 자동 판단 |
| plan (Explore) | 코드베이스 탐색, 계획 수립 | Plan Mode에서 Claude가 코드를 파악할 때 |
Claude가 자동으로 Task 도구를 사용하는 경우도 있지만, 명시적으로 요청하면 더 효과적이다.
서브 에이전트 사용법
방법 1: 자연어로 요청
> 서브 에이전트를 사용해서 이 프로젝트의 모든 REST API 엔드포인트를
찾아서 목록으로 정리해줘.
“서브 에이전트를 사용해서” 라고 명시하면 Claude가 Task() 도구를 통해 서브 에이전트를 스폰한다.
방법 2: 병렬 작업 요청
> 다음 3가지를 병렬로 조사해줘:
1. CourseService의 모든 public 메서드와 호출 관계
2. EnrollmentService의 외부 API 의존성 목록
3. 프로젝트의 테스트 커버리지 현황
각각 서브 에이전트로 동시에 진행해.
방법 3: 백그라운드 실행
서브 에이전트가 작업하는 동안 메인 대화를 계속할 수 있다.
> 서브 에이전트로 이 프로젝트의 의존성 분석을 백그라운드에서 진행해줘.
그 사이에 나는 다른 질문을 할게.
# 서브 에이전트가 시작되면 Ctrl+B로 백그라운드로 보낼 수 있다
# /tasks 명령어로 진행 상황 확인 가능
커스텀 서브 에이전트 만들기
.claude/agents/ 디렉토리에 마크다운 파일로 정의한다:
<!-- .claude/agents/code-reviewer.md -->
---
name: code-reviewer
description: 코드 변경사항을 보안, 성능, 패턴 관점에서 리뷰
model: sonnet
tools: Read, Glob, Grep, LS, WebSearch
---
당신은 시니어 백엔드 개발자이자 코드 리뷰어입니다.
변경된 코드를 다음 관점에서 리뷰해주세요:
1. 보안 취약점 (SQL Injection, XSS, 인증/인가)
2. 성능 이슈 (N+1 쿼리, 불필요한 DB 호출)
3. 프로젝트 컨벤션 위반
4. 에러 처리 누락
리뷰 결과를 심각도별로 분류해서 보고해주세요.사용법:
> @code-reviewer 방금 커밋한 변경사항을 리뷰해줘
서브 에이전트의 제약사항
알아두어야 할 제약이 있다:
- 서브 에이전트는 다른 서브 에이전트를 스폰할 수 없다 (1단계 깊이만 가능)
- 서브 에이전트는 새로운 컨텍스트에서 시작하므로, 메인 대화의 맥락을 자동으로 알지 못한다. 프롬프트에 필요한 정보를 담아줘야 한다.
- 서브 에이전트가 너무 많으면 토큰 사용량이 급증한다. Pro 플랜 사용 시 주의.
언제 서브 에이전트를 쓰고, 언제 안 쓸까
✅ 서브 에이전트가 적합한 경우:
- 코드베이스 전체 탐색 (파일 수십 개 읽기)
- 병렬로 처리할 수 있는 독립적 작업들
- 웹 검색이 많이 필요한 리서치
- 결과를 요약해서 받으면 되는 작업
❌ 메인 대화에서 직접 하는 게 나은 경우:
- 파일 1~2개 수정하는 간단한 작업
- 이전 대화 맥락이 중요한 후속 작업
- 대화형으로 방향을 조정해가며 진행해야 하는 작업
② /clear, /compact 컨텍스트 관리 실습
왜 컨텍스트 관리가 중요한가
Claude Code의 가장 흔한 실패 원인은 컨텍스트 저하(context degradation) 다. 컨텍스트 윈도우가 채워질수록 Claude의 지시 따르기 품질이 떨어진다.
비유하자면, 책상 위에 서류가 산더미처럼 쌓인 상태에서 일하는 것과 같다. 필요한 서류를 찾기 어려워지고, 새 서류를 놓을 공간도 없어진다.
/clear: 완전 초기화
> /clear컨텍스트를 완전히 비운다. 새 세션을 시작하는 것과 같다. 단, CLAUDE.md는 다시 로드된다.
언제 사용하나:
- 완전히 새로운 작업을 시작할 때
- 이전 대화가 현재 작업과 무관할 때
- Claude가 이상한 방향으로 반복해서 갈 때 (리셋 용도)
> 수강신청 API에 유효성 검사를 추가해줘
... (작업 완료)
> /clear
> 이번에는 결제 모듈의 환불 로직을 개선하자
(완전히 다른 작업이므로 이전 컨텍스트가 필요 없음)
/compact: 요약 후 압축
> /compact현재까지의 대화를 요약해서 컨텍스트를 압축한다. 이전 대화의 핵심 내용은 유지하면서 토큰을 절약한다.
언제 사용하나:
- 작업이 길어져서 컨텍스트가 50% 이상 찼을 때
- 같은 작업을 계속하지만 중간 과정이 너무 많이 쌓였을 때
- “Claude가 아까 논의한 내용을 까먹는 것 같다” 싶을 때
> CourseService를 리팩토링하자
... (30분간 작업, 파일 5개 수정)
> /compact
(지금까지의 작업 내용이 요약되고, 컨텍스트가 압축됨)
> 좋아, 이어서 테스트를 작성하자
(요약된 맥락 위에서 자연스럽게 이어짐)
/clear vs /compact 판단 기준
| 상황 | 추천 | 이유 |
|---|---|---|
| 완전히 다른 작업으로 전환 | /clear | 이전 맥락이 오히려 방해 |
| 같은 작업을 계속하는데 컨텍스트가 많이 참 | /compact | 맥락 유지하면서 공간 확보 |
| Claude가 이상한 응답을 반복 | /clear | 오염된 컨텍스트를 완전 리셋 |
| 긴 분석 후 구현 단계로 넘어갈 때 | /compact | 분석 결과 요약을 유지 |
| 하루의 첫 세션 시작 | /clear | 깨끗한 상태에서 시작 |
수동 /compact의 중요성
Claude Code는 컨텍스트가 거의 찼을 때 자동으로 compact를 실행한다. 하지만 그때는 이미 늦다. 자동 compact가 발동하기 전에 이미 품질이 떨어지고 있다.
권장 사항은 컨텍스트 사용량이 50%에 도달하면 수동으로 /compact를 실행하는 것이다.
# 컨텍스트 사용량 확인
> /stats
# 50% 이상이면 수동 compact
> /compact
실습: 컨텍스트 관리 워크플로우
아래 워크플로우를 실제로 따라해보자:
# 1. 새 작업 시작
claude
> /clear
> 이 프로젝트의 NotificationService를 분석해줘
# 2. 분석 결과를 바탕으로 작업 진행
> 분석 결과를 바탕으로 리팩토링 계획을 세워줘
> 계획대로 구현해줘
... (여러 파일 수정)
# 3. 컨텍스트 확인 및 압축
> /stats ← 토큰 사용량 확인
> /compact ← 50% 이상이면 압축
# 4. 이어서 작업
> 이어서 테스트를 작성해줘
# 5. 완전히 다른 작업으로 전환
> /clear
> 이번에는 PaymentService를 봐줘③ 대규모 코드베이스 분석 워크플로우
서브 에이전트와 컨텍스트 관리를 결합하면 대규모 코드베이스를 효과적으로 분석할 수 있다.
문제: 직접 분석의 한계
모노레포나 대규모 프로젝트를 메인 대화에서 직접 분석하면:
- 파일을 하나씩 읽을 때마다 컨텍스트가 빠르게 채워짐
- 50개 파일을 읽은 후 처음 읽은 파일의 내용을 정확히 기억하지 못함
- 분석이 끝났을 때 이미 컨텍스트가 거의 차서, 후속 작업 공간이 없음
해결: 3단계 분석 워크플로우
Phase 1: 서브 에이전트로 병렬 탐색
> 이 프로젝트를 분석하려고 해. 다음 3개 영역을 각각 서브 에이전트로
병렬 조사해줘:
1. API 레이어: 모든 REST 엔드포인트 목록, URL 패턴, 인증 방식
2. 서비스 레이어: 각 서비스 클래스의 책임과 의존 관계
3. 데이터 레이어: 엔티티 목록, 테이블 관계, 리포지토리 패턴
각 서브 에이전트는 결과를 파일로 저장해줘:
- analysis/api-layer.md
- analysis/service-layer.md
- analysis/data-layer.md
서브 에이전트가 수십 개 파일을 읽어도 메인 컨텍스트는 깨끗하다. 결과는 파일로 저장되므로 이후에도 참조할 수 있다.
Phase 2: 요약 통합
> analysis/ 폴더의 3개 분석 파일을 읽고,
프로젝트 전체 아키텍처를 하나의 문서로 통합해줘.
포함할 내용:
- 전체 아키텍처 다이어그램 (Mermaid)
- 모듈 간 의존 관계
- 외부 시스템 연동 포인트
- 개선이 필요한 부분 Top 5
결과를 analysis/architecture-overview.md로 저장해줘.
Phase 3: 심층 분석 (특정 영역)
> /compact ← 여기서 한번 정리
> architecture-overview.md에서 "개선이 필요한 부분" 1번을
상세히 분석해줘.
- 현재 코드의 문제점
- 리팩토링 방향
- 예상 작업량
실전 예시: 새 프로젝트 온보딩
새로 합류한 프로젝트를 빠르게 파악하는 워크플로우:
# Step 1: 전체 구조 파악 (서브 에이전트)
> 이 프로젝트에 처음 합류했어. 다음을 병렬로 조사해줘:
1. 디렉토리 구조와 각 모듈의 역할
2. build.gradle 분석해서 의존성 목록과 버전
3. 설정 파일(application.yml 등) 분석해서 프로파일별 차이
각각 서브 에이전트로 진행하고, 결과를 onboarding/ 폴더에 저장해.
# Step 2: 핵심 비즈니스 로직 파악
> onboarding/ 폴더의 분석 결과를 읽고,
이 프로젝트에서 가장 핵심적인 비즈니스 서비스 3개를 골라줘.
각 서비스의 주요 메서드와 흐름을 설명해줘.
# Step 3: 개발 환경 셋업 가이드
> 위 분석을 바탕으로 새 개발자를 위한
로컬 환경 셋업 가이드를 작성해줘.
onboarding/setup-guide.md로 저장해.워크플로우 다이어그램
┌─────────────────────────────────────────────────┐
│ 메인 대화 │
│ │
│ "프로젝트를 분석해줘" │
│ │ │
│ ├── Task() ──→ [서브 에이전트 A] │
│ │ API 레이어 분석 │
│ │ → api-layer.md 저장 │
│ │ │
│ ├── Task() ──→ [서브 에이전트 B] ← 병렬 │
│ │ 서비스 레이어 분석 │
│ │ → service-layer.md 저장 │
│ │ │
│ └── Task() ──→ [서브 에이전트 C] │
│ 데이터 레이어 분석 │
│ → data-layer.md 저장 │
│ │
│ ← 각 서브 에이전트가 요약만 반환 │
│ │
│ /compact ← 컨텍스트 정리 │
│ │
│ "분석 파일을 통합해줘" │
│ → architecture-overview.md 생성 │
│ │
│ "1번 이슈를 상세 분석해줘" │
│ → 심층 분석 & 리팩토링 계획 │
└─────────────────────────────────────────────────┘
plan.md와 결합
Day 2에서 배운 plan.md 패턴과 결합하면 더 강력하다:
# Phase 1: 서브 에이전트로 분석
> 서브 에이전트로 프로젝트 전체를 분석해줘...
# Phase 2: 분석 기반으로 작업 계획
> 분석 결과를 바탕으로 plan.md를 작성해줘.
- 리팩토링이 필요한 영역 우선순위
- 각 영역의 작업 체크리스트
- 의존 관계에 따른 작업 순서
# Phase 3: plan.md 기반 실행
> plan.md를 읽고 1번 항목부터 시작하자.
# (다음 날)
> /clear
> plan.md를 읽고 아직 완료되지 않은 항목부터 이어서 작업해줘.
실습 과제
과제 1: 서브 에이전트 체험 (15분)
자신의 프로젝트에서:
- “서브 에이전트를 사용해서 모든 REST 엔드포인트를 찾아줘” 요청
- 서브 에이전트가 동작하는 모습 관찰 (Task 도구 호출 확인)
- 동일 작업을 서브 에이전트 없이 해보고, 컨텍스트 소모량 비교
과제 2: /clear와 /compact 실습 (10분)
- 아무 작업을 진행하면서 /stats로 컨텍스트 사용량 모니터링
- 50% 도달 시 /compact 실행, 전후 차이 확인
- /clear 후 완전히 다른 작업 시작, 이전 맥락이 없는 상태 확인
과제 3: 대규모 분석 워크플로우 (20분)
- 프로젝트 루트에서 3단계 분석 워크플로우 실행
- 서브 에이전트 병렬 탐색 → 통합 문서 생성 → 심층 분석
- 결과물 (analysis/ 폴더)을 검토하고 정확도 평가
오늘의 핵심 정리
| 포인트 | 설명 |
|---|---|
| 서브 에이전트 본질 | 별도 컨텍스트에서 동작하는 독립 Claude 인스턴스 |
| 핵심 이점 | 메인 컨텍스트 보존 + 병렬 처리 (최대 10개 동시) |
| 제약사항 | 서브→서브 스폰 불가, 메인 맥락을 자동으로 모름 |
| /clear | 완전 초기화, 새 작업 시작 시 사용 |
| /compact | 요약 후 압축, 같은 작업 계속할 때 50%에서 수동 실행 |
| 대규모 분석 | 서브 에이전트 병렬 탐색 → 파일 저장 → 통합 → 심층 분석 |
| 결합 패턴 | 서브 에이전트 + /compact + plan.md = 세션을 넘나드는 대규모 작업 |
명령어 치트시트
# 서브 에이전트 사용
"서브 에이전트를 사용해서 ~해줘"
"다음 3가지를 병렬로 각각 서브 에이전트로 조사해줘"
"백그라운드에서 서브 에이전트로 ~를 진행해줘"
# 백그라운드 제어
Ctrl+B 서브 에이전트를 백그라운드로 보내기
/tasks 백그라운드 작업 목록 확인
# 컨텍스트 관리
/clear 컨텍스트 완전 초기화
/compact 대화 요약 후 압축
/stats 현재 토큰 사용량 확인
# 커스텀 서브 에이전트
@agent-name 커스텀 에이전트 직접 호출
참고 리소스
- Claude Code 공식 문서: Create custom subagents
- Anthropic SDK 문서: Subagents in the SDK
- 실전 가이드: Claude Code Customization Guide — 서브 에이전트 설정 예시
- 커뮤니티: Task Tool vs Subagents 비교