들어가며
24차시(스킬 개념), 25차시(스킬 작성법), 26차시(실전 스킬 세 개) — 여기까지가 Skills의 흐름이었다. 그중 26차시의 PR 리뷰 스킬에서 한 줄을 슬쩍 썼다 — context: fork + agent: Explore. 이번 차시는 그 한 줄이 무엇이었는지를 끝까지 풀어낸다.
Subagent는 메인 대화에서 분리된, 자기 컨텍스트 창과 자기 시스템 프롬프트, 자기 도구 권한을 가진 보조 에이전트다. 메인 대화는 지휘/통합 컨텍스트로 두고, verbose 출력이나 권한이 다른 작업은 subagent에 위임한다. 끝나면 결과 요약만 메인에 돌아온다.
이번 차시에서 다루는 것:
- 빌트인 subagent 3종 —
Explore,Plan,general-purpose - 커스텀 subagent —
.claude/agents/에 정의 파일 한 개 - 두 방향의 Skills + Subagents 통합
- Skill이 subagent에서 실행되는 길 (
context: fork+agent) - Subagent가 Skill을 preload하는 길 (
skillsfield)
- Skill이 subagent에서 실행되는 길 (
- 운영 패턴 — 격리, 권한 enforce, persistent memory, hooks
- Agent teams와의 차이 — 본 차시 범위 vs 다음 단계
Subagent란
핵심 개념이다.
각 subagent는 다음을 자기 것으로 가진다.
- 컨텍스트 창 — 메인의 대화 기록과 분리된 fresh start
- 시스템 프롬프트 — 본문(body)이 그대로 시스템 프롬프트가 됨
- 도구 권한 —
toolsallowlist 또는disallowedToolsdenylist로 제한 - 모델 —
sonnet/opus/haiku/full ID 중 자유 선택, 또는inherit
Claude는 task 설명이 subagent의 description과 매치된다고 판단하면 자동으로 위임한다. 위임된 subagent는 자기 컨텍스트에서 작업하고 결과 요약만 메인 대화로 돌려준다 — 작업 중 생성된 검색 결과, 로그, 큰 파일 내용은 메인에 들어오지 않는다.
이게 가치를 만드는 이유:
- 컨텍스트 절약 — verbose한 출력(테스트 로그, 거대 diff, grep 결과)이 메인에 누적되지 않음
- 권한 제약 — Edit/Write 없는 read-only로 묶거나, 특정 도구만 허용
- 모델 라우팅 — 가벼운 탐색은 Haiku로, 복잡한 분석은 Opus로
- 재사용 — 한 번 정의 후 여러 프로젝트에서
빌트인 Subagent 3종
Claude Code는 별도 정의 없이 쓰는 빌트인 subagent를 셋 깔고 들어온다. 적절한 상황에서 Claude가 자동으로 위임한다.
Explore
| 모델 | Haiku (fast, low-latency) |
| 도구 | Read-only (Write/Edit 거부) |
| 용도 | 코드베이스 탐색 |
코드 구조 파악, 파일 검색, grep, 키워드 추적 같은 read-only 작업에 최적화된다. 변경하지 않고 이해만 하는 게 주 작업이다.
호출 시 thoroughness 레벨을 셋 중 하나로 지정한다 — quick(targeted lookup), medium(balanced), very thorough(comprehensive analysis).
Plan
| 모델 | 메인 세션 모델 상속 |
| 도구 | Read-only |
| 용도 | plan mode에서 컨텍스트 수집 |
Plan mode가 켜져 있을 때 자동으로 사용된다. 코드베이스를 이해해야 plan을 짤 수 있는데, 그 연구 부분을 Plan subagent에게 위임한다. (Subagent는 자기 subagent를 spawn 못 하므로 무한 nesting이 막힘.)
general-purpose
| 모델 | 메인 세션 모델 상속 |
| 도구 | 모든 도구 |
| 용도 | 탐색 + 수정 둘 다 필요한 복합 작업 |
탐색만으로 부족하고 modification까지 필요할 때, 또는 multiple dependent steps가 들어가는 작업에 사용된다.
부속:
statusline-setup(Sonnet,/statusline실행 시),claude-code-guide(Haiku, Claude Code 기능 질문 시)도 자동 위임된다 — 직접 호출할 필요 없음.
커스텀 Subagent — 파일 형식
빌트인이 부족하면 직접 만든다. Subagent는 마크다운 파일 한 개다 — YAML frontmatter + 본문(시스템 프롬프트).
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.
본문이 시스템 프롬프트가 된다. Claude Code의 기본 시스템 프롬프트는 적용되지 않는다 — 환경 정보(작업 디렉토리)와 CLAUDE.md만 별도로 로드된다.
Frontmatter 필드
name과 description만 필수, 나머지는 모두 옵션.
| 필드 | 설명 |
|---|---|
name | 소문자/숫자/하이픈 |
description | 언제 위임할지 — Claude가 자동 라우팅 결정에 사용 |
tools | allowlist (생략 시 모두 상속, MCP 도구 포함) |
disallowedTools | denylist (tools보다 먼저 적용) |
model | sonnet/opus/haiku/full ID/inherit. 기본 inherit |
permissionMode | default/acceptEdits/auto/dontAsk/bypassPermissions/plan |
maxTurns | 최대 agentic turn 수 |
skills | 시작 시 preload할 스킬 (full content 주입) |
mcpServers | 이 subagent에서만 쓸 MCP 서버 (인라인 정의 또는 이름 참조) |
hooks | subagent lifecycle 훅 |
memory | user/project/local — persistent memory 활성화 |
background | 항상 background로 |
effort | low/medium/high/xhigh/max |
isolation | worktree로 git worktree 격리 |
color | UI 색 |
initialPrompt | --agent로 main session으로 실행 시 자동 전송 |
위치와 우선순위
같은 이름이면 높은 우선순위가 win.
| 위치 | 범위 | 우선순위 |
|---|---|---|
| Managed settings | 조직 전체 | 1 (최고) |
--agents CLI flag | 현재 세션 | 2 |
.claude/agents/ | 프로젝트 | 3 |
~/.claude/agents/ | 모든 프로젝트 | 4 |
Plugin’s agents/ | 플러그인 | 5 (최저) |
프로젝트 subagent는 git에 체크인해 팀과 공유한다. 사용자 subagent는 개인용으로 모든 프로젝트에서 쓴다.
작업 디렉토리
Subagent는 메인 세션의 cwd에서 시작한다. cd는 Bash 호출 사이에 persist 안 되고 메인의 cwd에도 영향을 주지 않는다. 격리 카피가 필요하면 isolation: worktree로 — 이 경우 Claude Code가 임시 git worktree를 만들어 그 안에서 작업하고, 변경이 없으면 자동 정리된다 (자세한 건 Worktrees 문서).
/agents 명령으로 만들기
.claude/agents/에 직접 파일을 쓰는 것 외에, 인터랙티브 인터페이스가 있다.
> /agents
탭 두 개:
- Running — 실시간 subagent 보기/중단
- Library — 모든 정의 보기/생성/편집/삭제. “Generate with Claude” 옵션으로 자연어 → 정의 자동 생성
추천 워크플로:
/agents실행- Library 탭 → Create new agent → Personal 또는 Project 선택
- (옵션) Generate with Claude — 설명 한 단락 입력하면 identifier/description/system prompt 자동 생성
- 도구 선택 (read-only면 Read-only tools만)
- 모델 선택
- 색 선택
memory스코프 —user/project/local/None- 저장 후 즉시 사용 가능 (restart 불필요)
직접 파일을 편집했다면 세션을 재시작해야 적용된다.
/agents로 만든 건 즉시 반영.
CLI에서 인터랙티브 없이 목록만 보려면:
claude agents
CLI에서 ad-hoc 정의
자동화 스크립트나 빠른 테스트에 유용한 길이다 — JSON으로 한 번에 정의해 세션 한정으로 활성화한다.
claude --agents '{
"code-reviewer": {
"description": "Expert code reviewer. Use proactively after code changes.",
"prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
"tools": ["Read", "Grep", "Glob", "Bash"],
"model": "sonnet"
}
}'
prompt가 시스템 프롬프트(파일 기반의 본문에 해당)다. 디스크에 저장되지 않는다.
호출 방법 — 네 가지
1. 자동 위임
description이 task 요청과 매치되면 Claude가 알아서 위임한다. “use proactively”나 “use immediately after…” 같은 phrase가 description에 들어 있으면 더 적극적으로 트리거된다.
2. 자연어로 명시
> Use the code-reviewer subagent to look at my recent changes
> Have the test-runner subagent fix failing tests
힌트 — Claude가 거의 항상 위임한다.
3. @-mention
> @"code-reviewer (agent)" look at the auth changes
→ 해당 subagent를 반드시 호출. Claude의 결정에 맡기지 않는다. 플러그인 subagent는 @agent-<plugin-name>:<agent-name>.
4. 세션 전체를 subagent로
claude --agent code-reviewer
→ 메인 thread 자체가 그 subagent의 시스템 프롬프트/도구/모델을 입게 된다. --system-prompt 효과와 같다. 헤더에 @code-reviewer가 표시되어 활성화 확인 가능.
프로젝트 기본값으로 만들고 싶다면 .claude/settings.json에:
{
"agent": "code-reviewer"
}
CLI flag가 setting을 덮어쓴다.
자동 위임을 부드럽게 하는 description
빌트인 예제(code-reviewer)가 보여주는 패턴이다.
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
세 가지가 들어 있다.
- 무엇을 하는지 — “Expert code review specialist”
- 언제 위임해야 하는지 — “Use immediately after writing or modifying code”
- 자동 호출 트리거 — “Proactively reviews”
25차시의 description 최적화 원칙이 그대로 적용된다 — 명령형, 사용자 의도 중심, pushy하게.
도구 제어 — tools vs disallowedTools
tools (allowlist)
tools: Read, Grep, Glob, Bash
→ 이 도구들만 사용. 다른 모든 도구(Edit, Write, MCP 도구 포함) 차단.
disallowedTools (denylist)
disallowedTools: Write, Edit
→ Write/Edit만 차단. Bash/MCP 등 모두 상속.
둘 다 설정한 경우
disallowedTools 먼저 적용, 그 다음 tools. 양쪽에 있으면 제거된다.
Skill 처리
스킬을 invoke하는 능력은 Skill 도구다. subagent에서 tools로 묶을 때 빠뜨리면 다른 스킬을 호출할 수 없다.
미리 알아둘 것:
skillsfield로 preload된 스킬 본문은 시스템 프롬프트에 이미 들어가 있어 별도 invoke가 필요 없다. 그 밖의 스킬을 추가로 호출하려면Skill도구가 있어야 한다.
Permission mode
Subagent는 메인의 permission context를 inherit하지만 override 가능하다 (몇 가지 예외 있음).
| Mode | 동작 |
|---|---|
default | 표준 권한 검사 (prompts) |
acceptEdits | 작업 디렉토리 내 file edit과 일반 filesystem 명령 자동 승인 |
auto | Auto mode (background classifier가 검토) |
dontAsk | 권한 prompt 자동 거부 (allow 규칙은 통과) |
bypassPermissions | 모든 prompt 스킵 — 위험 |
plan | Plan mode (read-only) |
부모가 bypassPermissions / acceptEdits / auto면 자식이 inherit하고 override 무시. 부모가 auto인 경우 subagent의 permissionMode frontmatter는 완전히 무시된다 — classifier가 부모와 같은 규칙으로 판정.
Skills + Subagents — 두 방향
이번 차시의 핵심이다. 둘은 같은 시스템의 양면이다.
방향 1: Skill에 context: fork + agent
스킬 본문이 subagent의 프롬프트가 된다. 26차시의 PR 리뷰 스킬이 이 패턴이었다.
---
description: Research a topic thoroughly in the codebase
context: fork
agent: Explore
---
Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references
호출하면 다음이 일어난다.
- 새 격리 컨텍스트가 생성됨
- subagent가 SKILL.md 본문을 task 프롬프트로 받음
agentfield가 실행 환경(model, tools, permissions) 결정- 결과만 메인에 돌아옴
agent 옵션:
- 빌트인 —
Explore,Plan,general-purpose - 커스텀 —
.claude/agents/의 정의 이름 - 생략 시 —
general-purpose
주의 —
context: fork는 task가 있는 스킬에만 의미가 있다. “use these conventions” 같은 guideline-only 본문이면 subagent가 받을 actionable prompt가 없어 결과가 비어 나온다.
방향 2: Subagent에 skills field
Subagent 시작 시 스킬 본문을 시스템 프롬프트에 주입한다.
---
name: api-developer
description: Implement API endpoints following team conventions
skills:
- api-conventions
- error-handling-patterns
---
Implement API endpoints. Follow the conventions and patterns from the
preloaded skills.
→ 시작 시 api-conventions와 error-handling-patterns 두 스킬의 full content가 시스템 프롬프트에 자동 주입된다 (description만 들어가는 일반 세션과 다른 점).
여기서 skills는 preload될 스킬을 지정한다. 접근 가능한 스킬을 지정하는 게 아니다. subagent는 다른 스킬도 Skill 도구로 invoke 가능하다 (그 기능을 차단하려면 tools에서 Skill을 제외하거나 disallowedTools에 추가).
disable-model-invocation: true인 스킬은 preload 불가하다. 누락되거나 disable된 스킬은 skip되고 debug log에 경고만 남는다.
차이점 요약
Skill with context: fork | Subagent with skills field | |
|---|---|---|
| 시스템 프롬프트 | agent type에서 (Explore, Plan 등) | subagent의 markdown body |
| Task | SKILL.md 내용 | Claude의 위임 메시지 |
| 추가 로드 | CLAUDE.md | Preloaded skills + CLAUDE.md |
| 사용 시점 | 한 번의 task 실행 | subagent가 살아있는 동안 모두 |
같은 스킬-서브에이전트 시스템이지만 어느 쪽이 task를 정의하느냐가 다르다. Skill이 task고 subagent가 환경이면 방향 1. Subagent가 task 흐름이고 skill이 reference면 방향 2.
실전 예제 1: Explore에 위임하는 deep-research 스킬
빌트인 Explore에 task만 위임하는 단순한 케이스다. 코드베이스 깊은 조사가 필요할 때 메인 컨텍스트가 검색 결과로 도배되는 걸 막는다.
.claude/skills/deep-research/SKILL.md:
---
description: >
Investigate a topic in the codebase deeply. Use when the user asks how
something works, where a feature is implemented, or wants a write-up on
an unfamiliar area.
context: fork
agent: Explore
---
Research $ARGUMENTS in depth:
1. Use Glob/Grep to find related files
2. Read implementations
3. Summarize architecture, key files, and gotchas
Output format:
- Overview (1 paragraph)
- Key files with one-line descriptions
- How the pieces fit together
- Things to watch out for
호출:
> /deep-research authentication flow
→ Explore subagent에서 격리 실행. read-only 도구만 사용. 모델은 Haiku — 빠르고 저렴. 메인엔 요약만 돌아온다.
실전 예제 2: 커스텀 read-only DB subagent
데이터 분석 작업에서 절대 쓰기를 못 하게 강제하고 싶을 때다. 도구 제한만으로는 부족하면 hook으로 검증 게이트를 건다.
.claude/agents/db-reader.md:
---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
model: sonnet
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/validate-readonly-query.sh"
---
You are a database analyst with read-only access. Execute SELECT queries
to answer questions about the data.
When asked to analyze data:
1. Identify which tables contain the relevant data
2. Write efficient SELECT queries with appropriate filters
3. Present results clearly with context
You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify
schema, explain that you only have read access.
검증 스크립트 scripts/validate-readonly-query.sh:
#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
echo "Blocked: Only SELECT queries are allowed" >&2
exit 2
fi
exit 0
chmod +x로 실행 권한 추가. PreToolUse hook이 모든 Bash 호출 전에 실행되어 INSERT/UPDATE/DELETE 등이 감지되면 exit code 2로 차단한다 — Claude는 차단 사유를 stderr로 받는다.
호출:
> @"db-reader (agent)" 지난 7일 활성 사용자 수를 알려줘
→ db-reader가 SELECT 쿼리를 작성·실행. 만약 모델이 실수로 INSERT 류를 쏘면 hook에서 차단됨.
실전 예제 3: Skill이 커스텀 Subagent에서 실행되기
위 두 패턴을 합친 것 — 우리가 정의한 subagent 안에서 스킬이 돌게 한다.
.claude/skills/data-report/SKILL.md:
---
description: >
Generate a data report from the warehouse for a given metric. Use when
the user wants daily/weekly/monthly numbers, dashboards, or analytics
summaries.
context: fork
agent: db-reader
---
Pull the data for $ARGUMENTS:
1. Find the relevant tables (users, events, orders)
2. Compose efficient SELECT queries
3. Run them
4. Format result as a markdown table with totals
If the metric is ambiguous, ask which definition to use before running queries.
호출:
> /data-report MAU for April
→ skill 내용이 db-reader subagent의 task 프롬프트가 됨. db-reader의 시스템 프롬프트(read-only 강조), 도구 제한(Bash만), hook(SQL 검증)이 모두 적용됨. Skill에서 정한 task 흐름은 그 환경에서 안전하게 실행됨.
실전 예제 4: Skills를 preload한 Subagent
API endpoint를 작성하는 작업에서, 팀 컨벤션 두 개를 자동으로 알게 하고 싶다.
먼저 두 스킬을 만든다 — api-conventions와 error-handling-patterns.
.claude/skills/api-conventions/SKILL.md:
---
description: API design conventions for this codebase
---
When writing API endpoints:
- Use RESTful naming: /users (not /getUsers)
- Return consistent error format: {error: {code, message}}
- All POST/PUT bodies validated with zod
- Authenticate with session cookie (not Bearer)
- Pagination: ?limit=N&cursor=...
.claude/skills/error-handling-patterns/SKILL.md:
---
description: Error handling patterns for this project
---
Errors flow through a single ErrorHandler middleware:
- AppError class with .toJSON() for response
- Database errors caught and rethrown with context
- 4xx/5xx separated cleanly
- Stack traces only in dev (NODE_ENV check)
이제 subagent에서 둘을 preload.
.claude/agents/api-developer.md:
---
name: api-developer
description: Implement API endpoints following team conventions and error handling patterns. Use when adding or modifying REST endpoints.
tools: Read, Edit, Write, Glob, Grep, Bash
model: sonnet
skills:
- api-conventions
- error-handling-patterns
memory: project
---
You are a senior API developer for this project. Implement endpoints following
the preloaded conventions and error handling patterns.
Workflow:
1. Read the relevant route file and adjacent endpoints for style
2. Check schemas in src/schemas/ for existing types
3. Write the endpoint
4. Add validation with zod
5. Test the endpoint with curl or the test suite
Update your agent memory with patterns and pitfalls you discover, so the next
endpoint task starts more informed.
호출:
> Use the api-developer agent to add GET /users/:id/sessions
→ api-developer가 시작 시 두 스킬 본문이 시스템 프롬프트에 이미 주입된 채로 시작. 매번 description만 보고 invoke할지 고민할 필요 없음. memory: project로 작업하며 발견한 패턴이 .claude/agent-memory/api-developer/에 누적됨.
Persistent memory
memory field로 cross-session knowledge를 활성화한다.
| Scope | Location | 사용 |
|---|---|---|
user | ~/.claude/agent-memory/<name>/ | 모든 프로젝트에서 공유 |
project | .claude/agent-memory/<name>/ | 프로젝트 한정, version control 공유 |
local | .claude/agent-memory-local/<name>/ | 프로젝트 한정, version control 제외 |
활성화 시 자동으로:
- 시스템 프롬프트에 read/write 지침 포함
MEMORY.md의 처음 200줄 또는 25KB 자동 첨부- Read/Write/Edit 도구 자동 활성화
기본은 project 추천 — 팀 공유 가능. 사용 팁:
> Review this PR, and check your memory for patterns you've seen before.
> Now that you're done, save what you learned to your memory.
본문에 명시 instruction을 넣으면 자동으로 maintain된다 (예제 4 참고).
Foreground vs Background
- Foreground — 메인 대화 block. 끝날 때까지 기다림. permission prompt와 clarifying question(
AskUserQuestion) pass-through. - Background — 동시 실행. 시작 전에 도구 권한을 한 번에 pre-approval. 그 외 권한은 auto-deny. clarifying question 못 함 (그러나 subagent는 계속).
Claude가 task 성격에 맞춰 결정한다. 명시 요청 가능 — “이걸 background로 돌려줘”, 또는 진행 중에 Ctrl+B로 토글.
전체 비활성화: CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1.
Forked subagents (실험)
Fork 모드는 v2.1.117+에서 CLAUDE_CODE_FORK_SUBAGENT=1로 활성화하는 실험 기능이다.
Fork = “전체 대화를 inherit한 subagent”. 메인의 system prompt, tools, model, message history를 그대로 받는다 — fresh start와 정반대다. 자기 tool calls는 메인에 누적되지 않고 최종 결과만 돌아온다. 메인 컨텍스트와 prompt cache를 공유 — 새 subagent보다 cheap.
활성화 시 변화 셋:
general-purpose자리에 fork 사용 (named subagent는 그대로)- 모든 subagent spawn이 background
/fork명령 활성화
> /fork draft unit tests for the parser changes so far
→ panel에 추가, background에서 실행, 끝나면 message로 결과.
Fork vs Named Subagent
| Fork | Named subagent | |
|---|---|---|
| Context | 전체 history | Fresh + 프롬프트 |
| System prompt | 메인과 동일 | 정의 파일 |
| Model | 메인과 동일 | 정의 파일 |
| Permissions | terminal에서 prompt | pre-approve, 그 외 auto-deny |
| Prompt cache | 메인과 공유 | 별도 |
정리: “한 화제를 메인 흐름에서 잠깐 떼어내” 다른 시도를 해보고 싶을 땐 fork. “전혀 다른 환경에서 fresh로” 격리하고 싶을 땐 named subagent.
운영 패턴
High-volume 격리
> Use a subagent to run the test suite and report only the failing tests with their error messages
→ verbose 출력은 subagent 컨텍스트에 머무름. 요약만 메인.
Parallel research
> Research the authentication, database, and API modules in parallel using separate subagents
→ 각 subagent가 독립 영역 탐색. Claude가 findings를 종합. 단, 결과가 다 메인으로 돌아오면 그것도 컨텍스트를 먹는다 — 너무 많이 띄우진 말 것.
Chain
> Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them
→ subagent 결과를 다음 subagent에게 컨텍스트로 전달.
메인 vs Subagent 결정 트리
메인 사용:
- 잦은 back-and-forth, iterative refinement
- 여러 phase가 컨텍스트를 공유 (planning → implementation → testing)
- 빠른 targeted 변경
- latency 중요 (subagent는 fresh start, gather context 시간이 듦)
Subagent 사용:
- verbose 출력이 메인에 필요 없음
- 도구 제한/권한 enforce
- self-contained, 요약만 받으면 됨
Skill 사용 (subagent 대신):
- 재사용 가능한 prompt/workflow
- 메인 컨텍스트에서 돌아도 됨
비활성화
특정 subagent 차단:
// .claude/settings.json
{
"permissions": {
"deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
}
}
CLI:
claude --disallowedTools "Agent(Explore)"
Agent Teams와의 차이 (briefly)
| Subagents | Agent teams | |
|---|---|---|
| Context | 자기 컨텍스트, 결과는 caller로 | 자기 컨텍스트, 완전 독립 |
| Communication | main으로만 보고 | teammate끼리 직접 메시지 |
| Coordination | main이 모두 관리 | shared task list, self-coord |
| Best for | focused task | discussion 필요한 작업 |
| Token cost | 낮음 (요약만) | 높음 (각 teammate 별도) |
Agent teams는 experimental(CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, v2.1.32+) 기능으로 여러 독립 세션을 팀으로 묶어 직접 통신시킨다. 본 차시 범위는 subagent — agent teams는 단일 task 격리를 넘어선 패턴이 필요할 때의 다음 단계다 (자세한 건 Agent teams 문서).
흔한 함정
-
fork 본문이 task 없는 guideline-only
- “use these conventions” 같이 task 없는 본문이면 subagent가 받을 actionable prompt 없음 → 무의미 결과
-
toolsallowlist에Skill빼먹음- subagent에서 다른 스킬 invoke 못 함 (preload된 건 OK)
-
부모 mode override 시도
- 부모가
bypassPermissions/acceptEdits/auto면 자식 inherit, override 무시
- 부모가
-
Subagent에서 자기 spawn
- subagent는 더 깊은 subagent spawn 불가
- 필요하면 chain (메인이 순차 호출) 또는 Skill (메인 컨텍스트에서 실행)
-
세션 시작 후 파일 변경
- subagent 파일은 세션 시작 시 로드 — 직접 편집했으면 restart
/agents로 만든 건 즉시 적용
-
memory 켜놓고 instruction 안 넣음
- 자동 read/write 지침은 들어가지만 “consult your memory before starting”을 명시하면 효과 큼
정리
핵심 요점
- Subagent = 분리된 컨텍스트/시스템 프롬프트/도구/모델 — verbose 작업은 격리, 메인에 요약만
- 빌트인 3종 —
Explore(read-only, Haiku),Plan(plan mode 자동),general-purpose(만능) - 커스텀 정의 —
.claude/agents/<name>.md에 frontmatter + 본문(시스템 프롬프트) /agentsUI — 인터랙티브 생성·관리, “Generate with Claude”로 자동 생성- 우선순위 — managed > CLI(
--agents) > project > user > plugin - Skill에
context: fork+agent— Skill 본문이 subagent task 프롬프트, agent가 실행 환경 - Subagent의
skillsfield — 시작 시 스킬 본문을 시스템 프롬프트에 preload - 도구 제어 —
toolsallowlist 또는disallowedToolsdenylist, 둘 다 시 deny 우선 - Permission mode — 부모의
bypassPermissions/acceptEdits/auto는 inherit, override 무시 - Persistent memory —
memory: user/project/local로 cross-session knowledge - Hooks —
PreToolUse/PostToolUse로 도구 검증,SubagentStart/SubagentStop로 lifecycle - Foreground vs Background — pre-approval 필요한 background, blocking foreground
- Fork 모드 —
CLAUDE_CODE_FORK_SUBAGENT=1, 전체 대화 inherit,/fork명령 isolation: worktree— git worktree로 격리, 변경 없으면 자동 정리- Agent teams는 다른 패턴 — 여러 독립 세션이 직접 통신하는 experimental 기능
다음 단계
이번 차시까지 섹션 5(커스텀 Skills)가 끝난다. 28차시부터 섹션 6: Hooks 자동화로 넘어간다 — 이번 차시에서 잠깐 본 PreToolUse/PostToolUse/SubagentStart/SubagentStop을 본격적으로 다룬다. 어느 이벤트가 있는지, settings.json 어디에 어떻게 정의하는지, 보안 게이트와 자동 포맷팅 같은 실전 패턴을 차례로 본다.