조대협 (http://bcho.tistory.com)
왜 SubAgent가 필요한가?
Claude Code로 복잡한 작업을 하다 보면 한 가지 문제를 마주치게 된다. 코드베이스를 탐색하고, 분석하고, 수정하고, 테스트까지 하다 보면 context window가 빠르게 소모된다는 것이다. 그리고 한 AI가 "코드 리뷰어"이면서 동시에 "디버거"이고 "문서 작성자"가 되려다 보면 어느 것도 제대로 못하는 상황이 생긴다.
그렇다면 어떻게 하면 좋을까? 인간 세계에서는 이 문제를 이미 해결했다. 바로 전문화이다. 코드 리뷰는 시니어 개발자가, 테스트는 QA 엔지니어가, 배포는 DevOps가 맡는 것처럼 말이다. SubAgent는 바로 이 개념을 Claude Code에 도입한 것이라고 보면 된다.
마치 Java에서 스레드를 직접 관리하던 것을 ThreadPool이 대신해주는 것처럼, SubAgent는 복잡한 작업 분배를 Claude가 자동으로 처리해준다.
SubAgent란 무엇인가?
SubAgent는 특정 작업을 처리하는 전문화된 AI 어시스턴트이다. 각 SubAgent는 자체 context window, 커스텀 시스템 프롬프트, 특정 도구 접근 권한, 독립적인 퍼미션을 갖고 실행된다. Claude가 SubAgent의 description과 일치하는 작업을 만나면 해당 SubAgent에게 작업을 위임(delegate)하고, SubAgent는 독립적으로 작업을 수행한 후 결과만 반환하게 된다.
SubAgent를 사용하면 얻는 이점은 다음과 같다:
- context 보존: 탐색·분석 작업을 메인 대화에서 분리하여 context를 절약한다
- 제약 강화: 특정 도구만 사용하도록 제한하여 안전성을 높인다
- 재사용성: 유저 레벨로 정의하면 모든 프로젝트에서 재활용할 수 있다
- 전문화: 특정 도메인에 집중된 시스템 프롬프트로 전문성을 높인다
- 비용 절감: Haiku 같은 저렴한 모델로 라우팅하여 비용을 줄인다
> 여러 에이전트가 병렬로 작업하며 서로 소통해야 한다면 Agent Teams를 사용한다. SubAgent는 단일 세션 내에서 동작한다.
기본 제공 SubAgent (Built-in Subagents)
Claude Code에는 기본으로 내장된 SubAgent들이 있고, Claude가 상황에 맞게 자동으로 선택해서 쓴다. 각 SubAgent는 부모 대화의 퍼미션을 상속하되 도구 제한을 추가로 적용한다.
Explore
• 모델: Haiku (빠르고 저렴)
• 도구: 읽기 전용
• 코드베이스 탐색, 파일 검색, 코드 분석에 사용된다
• 메인 대화의 context를 소모하지 않고 별도 context에서 실행된다는 것이 핵심이다 Plan
• 모델: 부모 대화 상속
• 도구: 읽기 전용
• Plan 모드에서 context 수집 및 계획 수립에 사용된다
General-purpose
• 모델: 부모 대화 상속
• 도구: 전체 도구 사용 가능
• 복잡한 멀티스텝 작업, 탐색과 수정이 함께 필요한 작업에 사용된다
개인적으로 가장 유용하게 쓰는 것은 Explore SubAgent이다. 대형 코드베이스를 탐색할 때 메인 context를 소모하지 않고 별도로 실행해주기 때문에 긴 작업 세션을 유지할 때 특히 효과적이다.
SubAgent 만들기
SubAgent를 만드는 방법은 크게 두 가지이다. /agents 명령으로 인터랙티브하게 만들거나, 직접 Markdown 파일을 작성하는 방법이다.
/agents 명령 사용하기
아래 명령을 실행하면 인터랙티브 인터페이스가 열린다.
/agents
여기서 할 수 있는 것들이다:
- 현재 사용 가능한 SubAgent 목록 확인
- 새 SubAgent 생성 (가이드 방식 또는 Claude 자동 생성)
- 기존 SubAgent 편집 및 삭제
- Generate with Claude 옵션을 선택하고 아래와 같이 설명하면 Claude가 시스템 프롬프트와 설정을 자동으로 생성해준다:
A code improvement agent that scans files and suggests improvements
for readability, performance, and best practices.< 그림. /agents 명령으로 SubAgent를 생성하는 인터랙티브 화면 >
파일 직접 작성하기
SubAgent는 YAML 프론트매터가 포함된 Markdown 파일로 정의된다. 파일 상단 YAML이 설정이고, 그 아래 Markdown 본문이 시스템 프롬프트가 된다.
아래는 코드 리뷰어 SubAgent의 기본 구조이다.
---
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.
name 필드는 SubAgent를 호출할 때 사용하는 식별자이다. 소문자와 하이픈만 사용해야 한다. description은 Claude가 언제 이 SubAgent를 사용할지 결정하는 기준이므로 구체적으로 쓸수록 좋다.
주요 설정
저장 위치와 우선순위
SubAgent 파일은 저장 위치에 따라 적용 범위와 우선순위가 달라진다. 같은 name의 SubAgent가 여러 위치에 있으면 우선순위가 높은 쪽이 사용된다.
프로젝트 SubAgent(.claude/agents/)는 git에 커밋하면 팀원들과 공유할 수 있다. 팀 전체가 동일한 SubAgent를 쓰게 되므로 코드 리뷰 기준을 통일하는 데 특히 유용하다.
프론트매터 주요 필드
13개 필드 중 실제로 자주 쓰는 핵심 필드만 정리하면 다음과 같다:
• name (필수): 소문자와 하이픈으로 구성된 고유 식별자
• description (필수): Claude가 언제 위임할지 결정하는 기준 — 구체적일수록 좋다
• tools: 사용 가능한 도구 목록. 생략 시 전체 도구 상속
• model: 사용 모델 (haiku / sonnet / opus / inherit / 전체 모델 ID)
• permissionMode: 퍼미션 처리 방식
• memory: 세션 간 지식 축적 범위 (user / project / local)
모델 선택
적절한 모델을 선택하면 성능과 비용을 균형 있게 조절할 수 있다. 단순 탐색에 opus를 쓰는 건 낭비이다: • haiku: 빠르고 저렴. 단순 탐색, 읽기 전용 작업에 적합
• sonnet: 성능과 비용의 균형. 일반적인 코드 리뷰, 분석에 사용
• opus: 최고 성능. 복잡한 아키텍처 분석이나 난이도 높은 디버깅에만
• inherit: 메인 대화와 동일한 모델 사용. 생략 시 기본값
퍼미션 모드
permissionMode로 SubAgent의 퍼미션 처리 방식을 제어할 수 있다:
• default: 표준 퍼미션 체크. 퍼미션 프롬프트가 사용자에게 전달된다
• acceptEdits: 파일 편집 자동 수락
• dontAsk: 퍼미션 프롬프트 자동 거부 (명시적으로 허용된 도구는 동작)
• bypassPermissions: 모든 퍼미션 체크 건너뜀 — 꼭 필요한 경우에만 사용
• plan: Plan 모드 (읽기 전용 탐색)
> 주의: bypassPermissions는 모든 퍼미션 체크를 건너뛰므로 신중하게 사용해야 한다. 부모 대화가 bypassPermissions를 사용하면 이 설정이 우선하여 덮어쓸 수 없다.
고급 기능
지속적 메모리 (Persistent Memory)
memory 필드를 설정하면 SubAgent가 세션 간에 지식을 축적할 수 있다. 예를 들어 코드 리뷰 SubAgent가 이전에 발견한 패턴과 컨벤션을 기억해두고 다음 세션에서 활용하는 것이 가능하다. 반복적으로 쓰는 SubAgent에는 꼭 설정해두기를 권장한다.
범위 저장 위치 용도
| 범위 | 저장 위치 | 설명 |
| user | ~/.claude/agent-memory// | 모든 프로젝트에 걸쳐 학습 내용 기억 (권장) |
| project | .claude/agent-memory// | 프로젝트별 지식, 버전 관리로 공유 가능 |
| local | .claude/agent-memory-local// | 프로젝트별, 버전 관리 미포함 |
Hooks를 이용한 조건부 제어
특정 도구의 일부 기능만 허용하고 싶을 때는 PreToolUse Hook을 사용한다. Hook은 JSON을 stdin으로 받고, exit code 2로 실행을 차단할 수 있다. 아래는 읽기 전용 SQL 쿼리만 허용하는 SubAgent 예시이다.
---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/validate-readonly-query.sh"
---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)\b' > /dev/null; then
echo "Blocked: Only SELECT queries are allowed" >&2
exit 2
fi
exit 0INSERT, UPDATE, DELETE 등 쓰기 쿼리가 감지되면 exit 2로 차단하고, SELECT만 통과시키는 구조이다.
MCP 서버 연동
특정 SubAgent에만 MCP 서버를 연결할 수 있다. 메인 대화에는 노출하지 않고 SubAgent에만 특정 도구를 부여하는 것이 가능하다. 아래는 Playwright MCP 서버를 브라우저 테스트 SubAgent에만 연결하는 예시이다.
---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
- playwright:
type: stdio
command: npx
args: ["-y", "@playwright/mcp@latest"]
- github
--
SubAgent 활용 패턴
패턴 1: 대용량 출력 격리
테스트 실행, 로그 분석, 문서 fetching 등 대량의 출력을 생성하는 작업은 SubAgent에 위임하면 메인 context를 절약할 수 있다. 결과의 요약본만 메인 대화로 반환되므로 context 효율이 극대화된다.
Use a subagent to run the test suite and report only the
failing tests with their error messages패턴 2: 병렬 리서치
서로 독립적인 조사 작업은 여러 SubAgent를 동시에 실행하여 병렬로 처리할 수 있다. 각 SubAgent가 담당 영역을 독립적으로 탐색하고, Claude가 결과를 종합한다. 아래와 같이 지시하면 Claude가 알아서 병렬 SubAgent를 실행한다.
Research the authentication, database, and API modules
in parallel using separate subagentsAPI SubAgent
메인 대화
DB SubAgent Auth SubAgent
< 그림. 세 개의 SubAgent가 각 모듈을 병렬로 분석하고 메인 대화로 결과를 합산하는 흐름 >
패턴 3: SubAgent 체이닝
멀티스텝 워크플로우는 SubAgent를 순서대로 연결하여 처리할 수 있다. 각 SubAgent가 작업을 완료하면 결과를 Claude에게 반환하고, Claude가 관련 context를 다음 SubAgent에 전달하게 된다.
Use the code-reviewer subagent to find performance issues,
then use the optimizer subagent to fix them코드 변경 Code Reviewer
성능 이
발견 Optimizer 최적화 완료
< 그림. code-reviewer → optimizer 체이닝 실행 흐름 >
언제 SubAgent를 쓰고, 언제 쓰지 않을까?
그러면 다음 질문이 생긴다. "그냥 메인 대화에서 하면 안 되나?" 당연히 된다. 단지 다음 상황에서는 SubAgent가 훨씬 낫다:
- 대용량 출력이 발생하는 작업 (테스트 실행, 로그 분석)
- 특정 도구 제한이 필요한 작업 (읽기 전용, 쓰기 차단)
- 독립적으로 완결되는 작업
- 여러 영역을 동시에 조사해야 하는 경우 (병렬 실행)
반대로 메인 세션이 더 적합한 경우도 있다:
- 잦은 피드백 주고받기, 반복적 개선 작업
- 계획 → 구현 → 테스트가 연결된 긴 작업
- 빠른 단일 변경
TIP : SubAgent는 다른 SubAgent를 생성할 수 없다. 중첩 위임이 필요하다면 Skills를 활용하거나 메인 대화에서 SubAgent를 체이닝하는 방식을 사용한다.
실전 SubAgent 예시
Code Reviewer
읽기 전용으로 코드를 수정하지 않고 리뷰만 하는 SubAgent이다. Edit/Write 도구 없이 Read, Grep, Glob, Bash만 허용하여 의도치 않은 수정을 방지한다.
아래는 실제 사용하는 code-reviewer SubAgent 정의이다.
---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for
quality, security, and maintainability. Use immediately after code changes.
tools: Read, Grep, Glob, Bash
model: inherit
---
When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
Review checklist:
- Code clarity and readability
- Proper error handling and no exposed secrets
- Input validation and good test coverage
Provide feedback organized by priority:
Critical (must fix) / Warnings (should fix) / Suggestionsdescription에 "Use immediately after code changes"라고 명시해두면 Claude가 코드 수정 후 자동으로 이 SubAgent를 호출하게 된다.
Debugger
버그를 찾고 직접 수정까지 하는 SubAgent이다. Edit 도구가 포함된 것이 code-reviewer와의 핵심 차이점이다.
아래는 debugger SubAgent 정의이다.
---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected
behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---
When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works
마무리
SubAgent는 Claude Code를 훨씬 더 강력하게 만드는 핵심 기능이다. code-reviewer, debugger, data-scientist 같은 전문화된 SubAgent를 몇 개만 잘 만들어두면 작업 효율이 눈에 띄게 달라지고, git에 커밋해두면 팀 전체가 동일한 품질의 AI 도움을 받게 된다. 한번 만들어두면 계속 쓰게 되는, 꽤 실용적인 기능이다.
참고: https://code.claude.com/docs/en/sub-agents
참고 : 위의 글을 제 프롬프트를 통해서 클로드로 작성한 글입니다.