Claude Code Workshop - Chapter 2 Subagents

AWS 최우형님의 GitHub Claude Code Deep Dive Workshop 을 보면서 스스로 공부한 내용을 작성했습니다.

포스팅 모든 자료는 해당 워크숍 커리큘럼에서 학습했습니다.

* 자료 출처

GitHub - whchoi98/claude-code-workshop: claude-code-workshop

claude-code-workshop. Contribute to whchoi98/claude-code-workshop development by creating an account on GitHub.

github.com

1. Agents (Subagents)

1.1. 사전 내용

학습 내용
서브에이전트의 격리 모델을 설명하고, 프론트매터로 맞춤 에이전트를 정의하며, 자동 위임과 명시 호출, 병렬 실행을 실무 워크플로에 적용

격리 모델 이해
- 컨텍스트 격리와 요약 회수
- fork 와 팀 경계

에이전트 정의
- 프론트매터 15필드로 도구, 모델, 메모리, 훅 설계

디스패치 운용
- 자동 위임, @멘션, 병렬과 체이닝, resume 활용

실전 패턴 구축
- 리뷰어부터 마이그레이션 봇까지

1.2. Agents

위임과 병렬화로 컨텍스트를 지키는 기술

Subagents 개념과 원리

- 자기만의 컨텍스트 윈도우를 가진 격리 인스턴스
- 특정 작업을 처리하는 격리된 Claude 인스턴스
- 자체 컨텍스트 윈도우, 맞춤 시스템 프롬프트, 별도 도구 권한으로 독립 작업 후 요약 출력

특징

자체 컨텍스트
- 메인 대화와 분리된 윈도우에서 작업
- 상호 오염 없음
전용 프롬프트
- 역할에 특화된 시스템 프롬프트로 한 가지 일에 집중
도구 격리
- 허용 도구를 좁혀 읽기 전용 등 안전한 권한 설계
요약 회수
- 수십 개 도구 호출의 결과가 요약 한 덩이로 귀환

Why use subagents ??

컨텍스트 오염 = 응답 품질 저하
- 불필요한 컨텍스트가 많아지면 모델이 참조할 내용이 산만해짐
- 서브 에이전트 없이 메인에서 처리
- 30개 파일 읽기가 그대로 이력에 축적
- 테스트 로그 수천 줄이 윈도우 점유
- Compaction 한계가 빨리 오고 초기 지시 소실
긴 세션일수록 응답 품질 하락
- 서브 에이전트 위임
- 대량 읽기는 자식 컨텍스트에서 소화
- 메인에는 실패 테스트 요약만 도착
- 본 대화는 결정과 방향에만 사용
긴 세션에도 컨텍스트가 가볍게 유지

Subagent 컨텍스트 구성

System Prompt
- 에이전트 자신의 프롬프트 + 작업 디렉토리 등 환경 정보
- Claude Code 전체 프롬프트는 미포함

Task Message
- 메인 Claude 가 작성한 위임 지시문
- 대화 이력은 오지 않음

CLAUDE.md + Memory
- 메인이 로드한 메모리 계층 전체
- Explore 와 Plan 은 생략

Git Status
- 부모 세션 시작 시점 스냅샷
-Explore 와 Plan 은 생략

Preloaded Skills
- skils 필드에 지정한 스킬의 본문 전체

위임의 가치

컨텍스트 보존(Preserve Context)
- 탐색과 구현 출력을 메인 대화 밖에 격리

제약 강화(Enforce Constraints)
- 도구 제한으로 읽기 전용 등 안전 강제

재사용성(Reuse Configs)
- 사용자 레벨 정의로 전 프로젝트 재사용

전문화(Specialize)
- 도메인 특화 프롬프트로 성공률 상승

비용조정(Control Costs)
- haiku 같은 경량 모델 라우팅을 통한 비용 절감

팀 자산화
- 프로젝트 정의를 버전 관리로 팀과 공유, 공동 개선

1.3. 빌트인 에이전트 (Built-in Agents)

- Claude Code 설치 시 기본적으로 내장되어 있는 빌트인 에이전트

탐색 에이전트 (Explore)

- 읽기 전용 탐색 전문 에이전트

- 코드베이스 검색과 분석에 최적화된 읽기 전용 에이전트

- Claude 가 수정없이 코드 이해할 때 자동 위임

- 읽기 전용, 쓰기/편집 거부

상속 모델
- 메인 모델 상속
- Claude API 에서는 Opus 상한 적용
- Bedrock 등의 공급자를 사용시 상한 없음
- 메인 대화 Haiku → Haiku
- 메인 대화 Sonnet → Sonnet
- 메인 대화 Opus → Opus
호출 강도(Depth)
- 3단계 호출 강도 지정 가능
- quick, medium, very thorough
- 기본 - 자동
- 명시적 지정 - 프롬프트에서 명시

"Explore 인증 시스템 (thoroughness: quick). 로그인 핸들러를 찾아줄래."
"Payment 모듈 탐색 (thoroughness: medium). Stripe 통합 포인트와 webhook 핸들러를 모두 찾아."
"User 인증 흐름 완전 분석 (thoroughness: very thorough). JWT, refresh tokens, logout 모두 포함해서 매핑해줄래."

경량 설계
- CLAUDE.md 와 git 상태 생략

플랜 에이전트 (Plan)

- Plan 모드의 조사 담당, 읽기 전용, 모델 상속

- 탐색 출력을 별도 창에 격리

범용 에이전트 (General-purpose)

- 탐색과 수정 모두 필요한 작업 처리

- 전체 도구, 모델 상속

- 복잡한 다단계 작업

1.4. 실행 모델 / 실행 환경

모델 실행 환경

- 백그라운드 실행이 기본값

- 결과가 즉시 필요할 때만 포그라운드에서 실행

- 권한 프롬프트는 메인 세션

Foreground
- 완료까지 메인 차단
- 결과가 다음 판단에 즉시 필요할 때
- Ctrl + B 를 통해 실행 중 작업을 백그라운드 전환 가능
Background
- 기본값, 동시 진행
- 완료 시 결과가 메시지로 도착

모델 상태

- 각 호출은 새 인스턴스로 시작하지만, 완료된 에이전트의 대화 기록은 파일로 남아 있음

- Explore, Plan 을 제외한 나머지 에이전트는 재개 가능

- 자동 정리 기간 : 30일 기본 (cleanupPeriodDays 설정)

모델 해석 우선순위

- 서브 에이전트 모델 선정 우선 순위

환경변수 - CLAUDE_CODE_SUBAGENT_MODEL, alias, 모델 ID 지정
호출 파라미터 - 메인 Claude 가 Agent 호출과 함께 넘기는 모델 값
Frontmatter - 정의 파일의 모델 필드
메인 모델 - 위 설정이 없을 경우 메인 대화 모델 상속, 기본값

1.5. 서브에이전트 병렬화 수단

Subagent
- 한 세션 안의 워커, 새 컨텍스트, 요약 회수 병렬화
- 곁가지 격리, 병렬 리서치
Fork
- 대화 전체를 물려받은 서브에이전트
Background agents
- 독립 세션 여러 개를 한 화면에서 관찰
- 무관한 작업들의 병렬 운영
Agent Teams
- 세션들끼리 메시지로 협업
- 더 무겁고 비쌈
- 지속 병렬, 컨텍스트 초과 작업
- 에이전트간 소통 필요 시 Teams 활용

1.6. 서브에이전트 사용 사례

고볼륨 격리
- 테스트, 로그 처리 등의 대량 출력 격리

병렬 리서치
- 독립 모듈 여러 개를 동시 조사, 결과만 종합

리뷰, 검증
- 구현과 분리된 컨텍스트로 리뷰 및 검증

권한 강제
- 읽기 전용, 도메인 한정 등 도구 제약을 역할로 고정

문서 조회
- 외부 문서 다량 읽기를 자식에서 소화

반복 역할
- 같은 지시를 반복하는 워커

1.7. 서브에이전트 고려 사항

실행 비용
- 새 컨텍스트로 시작하기 때문에, 단발 작업엔 비효율
회수 비용
- 다수 에이전트의 결과물이 메인 대화 컨텍스트를 다시 채움
- 요약 회수 등의 통제 필요
모델 배분
- 탐색 워커는 haiku 등의 저비용 모델을 지정
캐시 관점
- fork 는 메인 프롬프트 캐시를 공유

1.8. 서브에이전트 안티 패턴

- 잦은 왕복이 필요한 대화형 작업 → 왕복형 작업은 메인 대화에서 수행

- 계획, 구현, 테스트가 맥락을 공유하는 일 분리 → 맥락 공유 단계는 한 흐름으로 유지

- 한 줄 수정 같은 단발 작업 → 빠른 확인은 /btw

- 이전 단계 결과에 의존하는 조사 → 의존 조사는 체이닝으로 순차 실행

- 만능 에이전트 1개로 모든 역할 수행 → 역할별 단일 책임 에이전트로 분리

2. Subagent 정의

2.1. 마크다운 정의

- YAML Frontmatter + 시스템 프롬프트

- Frontmatter : 마크다운 파일 맨 앞에 있는 메타데이터

---
name: code-reviewer
description: |
  PR diff를 검토하여 가독성, 안전성, 성능, 테스트 커버리지 관점에서
  개선 사항을 제안하는 시니어 코드 리뷰어. 사용 시점: 코드 리뷰가
  필요하다고 사용자가 요청하거나 git diff 검토가 필요한 경우.
tools: Read, Grep, Glob, Bash(git diff:*), Bash(git log:*)
model: sonnet
---
당신은 10년 경력의 시니어 소프트웨어 엔지니어입니다.

# 검토 우선순위
1. 안전성: null 참조, race condition, 입력 검증 누락
2. 가독성: 명명, 함수 크기, 주석 필요성
3. 성능: 알고리즘 복잡도, 불필요한 I/O
4. 테스트: 새 코드의 테스트 커버리지

# 출력 형식
- Severity: high | medium | low
- 파일:라인, 문제 설명, 권장 수정안

2.2. 서브에이전트 이름 우선순위

서브에이전트 이름 우선순위

- 같은 이름일 경우 호출되는 순서

Managed - 관리자가 배포한 조직 관리 설정의 .claude/agents/
--agents 플래그 - 실행 시 JSON 으로 주입, 세션 한정, 디스크 저장 없음
Project - 버전관리로 팀공유, .claude/agents 위치
User - 내 로컬 전체 설정, .claude/agents 위치
Plugin - 플러그인으로 등록된 agents, agents/

서브에이전트 파일 배치 규칙

- agents 디렉토리 하위로 구성

버전 관리 - Git 관리
일관성 - 프로젝트마다 같은 에이전트 활용 가능
우선순위 명시 - User 보다 Project 우선

# 기본 배치
my-project/
├── .claude/
│   └── agents/
│       ├── code-reviewer.md
│       ├── auth-reviewer.md
│       └── performance-checker.md
├── src/
└── package.json

# 계층화 배치
my-project/
└── .claude/
    └── agents/
        ├── review/
        │   ├── code-reviewer.md
        │   └── security-reviewer.md
        └── research/
            ├── auth-researcher.md
            └── api-researcher.md

서브 에이전트 파일 생성 시 몇 초내에 감지
Claude 세션 재시작 시 즉시 감지

2.3. 서브에이전트 파일 생성

Claude 에게 위임

- 자연어로 요구사항 전달

- 이후 수작업 병행

- 생성 후 즉시 호출 가능

code-reviewer 에이전트를 사용해서 최근 커밋의 변경분(git diff HEAD~1)을 검토해 주세요

name / description

- Claude 는 Description 을 읽고 위임 여부 판단

- Description 이 명확할수록 자동 위임 정확도 상승

name
- 소문자, 하이픈(-)
- 고유 식별자

description
- 시점 서술 - 무엇을 하는지보다 언제 쓰는 지 담아야 위임 판단 가능
- 능동 문구 - use proactively, MUST BE USED 문구 등이 자동 위임 강화
- 구체적 - 트리거 조건 명시
- 안티패턴 예시(Description 에 그냥 아래처럼만 써놓을 때 무시될 가능성 상승)
- 코드를 리뷰하는 에이전트
- 테스트 관련 도우미
- 보안 전문가
- 역할만 있고 시점이 없음
- Claude 위임 시점이 없음

tools / disallowedTools

- tools - 허용 / disallowedTools - 거부

- 둘 다 설정 시 deny 우선

tools
- 역할에 필요한 도구만 부여 - 허용 목록
- 생략 시 메인에 부여된 전체 도구 상속
- 명시할 경우 명시된 도구만 사용 가능

---
name: code-reviewer
description: Use after code changes to review for security and performance
model: sonnet
tools:
  - Read
  - Grep
  - Glob
---

---
name: dangerous-test
description: 의도적 권한 테스트용 에이전트. 사용 시점: 사용자가 이름으로 직접 지정할 때만.
tools: Read, Grep
model: haiku
---
당신은 테스트 에이전트입니다.
파일을 분석하고 결과를 보고하세요.

disallowedTools
- 차단 목록
- MCP 도 차단 가능

---
name: code-modifier
description: Use when implementing code changes
model: sonnet
disallowedTools:
  - Delete
  - Shell
  - some-dangerous-mcp

  # MCP 패턴
  - mcp__github        # GitHub MCP의 모든 도구 차단
  - mcp__slack         # Slack MCP의 모든 도구 차단
---

model

- 역할별 모델 배분

alias - sonnet, opus, haiku, fable
전체 ID - 버전 고정 필요 시(claude-opus-4-8)
inherit - 기본값, 버전 지정하지 않을 시 메인 대화 모델 상속
검증 - 조직 availableModels 허용 목록 확인 후 통과 시 사용 가능
사고 설정 - 확장 사고는 메인 설정 상속 (extended_thinking)

---
name: deep-analyzer
model: opus
extended_thinking: true  # 확장 사고 활성화
---

---
name: quick-reviewer
model: sonnet
extended_thinking: false # 확장 사고 비활성화
---

---
name: default-agent
# extended_thinking 생략
# → 메인 대화의 설정을 그대로 상속
---

permissionMode

- 에이전트별 권한 모드

default - 표준 확인 프롬프트
acceptEdits - 작업 경로 편집 자동 수락
auto - 명령과 보호 경로 쓰기 검토
dontAsk - 확인 프롬프트 자동 거부
plan - 읽기 전용 탐색

---
name: auto-fixer
description: Automatically fix code issues
model: sonnet
permissionMode: auto
# → 사용자 승인 없이 자동 실행
---

---
name: code-reviewer
description: Review code changes
model: sonnet
permissionMode: dontAsk
# → 읽기만 하므로 확인 안 함
---

---
name: careful-editor
description: Make code changes
model: opus
permissionMode: default
# → 매번 사용자 승인 받음
---

기타 필드

skills
- 스킬 프리로드
- 도메인 지식을 시작부터 주입

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

# 나열한 스킬의 본문 전체가 시작 컨텍스트에 주입
# 미나열 스킬도 Skill 도구로 실행 중 호출은 가능
# 스킬 호출 자체를 막으려면 tools에서 Skill 제외

mcpServers
- 해당 에이전트에게 MCP 서버 권한 부여

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  - playwright:            # 인라인: 이 에이전트 전용
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  - github                 # 참조: 기존 서버 공유
---

# 인라인 서버는 시작 시 연결, 종료 시 해제

memory
- 영속 메모리 설정

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: project
---

You are a code reviewer. As you review code, update
your agent memory with patterns, conventions, and
recurring issues you discover.

# 스코프: user / project(권장) / local
# MEMORY.md 첫 200줄 또는 25KB가 프롬프트에 포함

3. Agent 도구

3.1. Agent 도구 개요

- 메인 Claude 는 Agent 도구를 호출해 서브에이전트 생성

- Task = Agent

자동 위임 판단 - 요청 성격, 에이전트의 Description 등을 종합해 위임 결정
서브에이전트 명시적 호출
- 자연어 호출
- @멘션
- --agent : 메인 스레드가 에이전트가 됨

$ claude --agent code-reviewer

# 세션 자체가 그 에이전트의 시스템 프롬프트,
# 도구 제한, 모델로 실행

# 특성
# 기본 Claude Code 프롬프트를 완전 대체
# CLAUDE.md와 프로젝트 메모리는 그대로 로드
# 시작 헤더에 @이름 표시, resume 시에도 유지

# 프로젝트 기본값 고정 (.claude/settings.json)
# { "agent": "code-reviewer" }
# CLI 플래그가 설정보다 우선

병렬 호출

> 인증, 데이터베이스, API 모듈을 각각 별도 서브에이전트로 병렬 조사해줘. 각자 담당 영역의 구조와 핵심 흐름을 요약해서 보
고해.

# 동작
# 독립 에이전트 3개가 동시에 탐색
# 각자 자기 컨텍스트에서 파일을 소화
# 완료되는 대로 요약이 메인에 도착
# 메인 Claude가 세 보고를 종합

# 조건: 조사 경로가 서로 의존하지 않을 것

이 코드베이스를 종합 점검해 주세요. 다음 세 가지를 병렬로 진행해 주세요.
1) 코드 품질 리뷰
2) 테스트 커버리지 분석
3) README 문서 초안 작성

3.2. 중첩 서브에이전트

서브에이전트가 생성한 자기 서브에이전트
위임받은 작업이 다시 병렬 하위 작업으로 진행
5 Depth 까지 가능
활성 조건 : tools 에 Agent 포함 시 중첩 가능
트리 관측 : 패널 행에 하위 개수 표시

3.3. fork

- 대화 전체를 물려받는 특수 서브에이전트

> /fork 지금까지의 파서 변경에 대한 단위 테스트 초안 작성
# 지시문 첫 단어들로 이름이 자동 부여
# 패널에 행 추가, 백그라운드로 진행

# 패널 조작
# 위아래 화살표 행 이동
# Enter 트랜스크립트 열람, 후속 지시
# x 중지 또는 완료 정리
# Esc 프롬프트로 복귀

# 열람 중 /model, /fast는 메인 대상임을 안내

2주차 회고

이번에는 Claude Subagent 동작을 이해하고, 실제로 사용해봤다.

그 동안 서브에이전트 얘기만 들었고 실제로 정의해서 사용해보진 않았는데 이번 학습을 통해서 실무에도 서브에이전트를 정의하고 사용해보면 좋을 것 같아서 바로 적용해보려고 한다.

학습 내용이 PDF 로 되어있는 자료를 공부하고 간략한 실습 코드를 돌려보는 것이지만,

중간 중간 이해가 안되는 것들에 대해서 좀 더 깊게 공부하고 테스트 코드와 예시를 보면서 학습하니 얻는게 많다.

신규 지식을 최초 습득하는 것이라 모든 내용을 이해하고 내 것으로 만들었다고 말하는 건 과장이다.

다만 적어도 관련된 지식을 어떻게 찾아볼 수 있을 지에 대한 도메인 지식이 생겼다고는 말할 수 있을 것 같다.

'AI' 카테고리의 다른 글

LLM 스터디 1주차) LLM Transformer (0)	2026.08.08
LLM 스터디 1주차) 모델 서빙과 최적화 입문 (0)	2026.08.08
Claude Code Workshop - Chapter 1 Overview (0)	2026.08.01

Contents

새소식

인기 검색어