조사 작업 위임, 병렬 처리, 독립적인 시각의 검토까지 — Claude Code 서브에이전트(subagent)가 진가를 발휘하는 상황과 메인 세션을 유지하는 편이 나은 경우를 짚어본다.
Claude Code는 복잡한 멀티스텝 프로젝트를 충분히 소화할 수 있지만, 세션이 길어질수록 부담도 커진다. 읽어들인 파일, 탐색한 코드, 미완성 상태로 남은 작업들이 모두 컨텍스트 윈도우(context window)에 쌓이면서 응답은 느려지고 토큰 비용은 올라간다.
대규모 TypeScript 모노레포(monorepo)에 새 기능을 추가한다고 생각해 보자. 핵심 작업은 구현이지만, 그 과정에서 자잘한 작업들이 계속 생겨난다. 기존 서비스의 인증 처리 방식을 추적하거나, 날짜 포맷용 공유 유틸을 찾거나, 디자인 시스템에 비슷한 컴포넌트가 이미 있는지 확인하는 일들이다. 이런 작업들은 프로젝트 전체 컨텍스트가 필요하지 않은데도 메인 세션 안에서 처리하면 잡음만 늘어난다. 이걸 병렬로 실행할 수 있다면 어떨까?
바로 이럴 때 서브에이전트가 필요하다. 서브에이전트는 독립된 컨텍스트 윈도우를 가진 격리된 Claude 인스턴스다. 작업을 받아 수행한 뒤, 결과만 반환한다. 브라우저의 탭처럼, 메인 흐름을 잃지 않으면서 곁가지 작업을 처리할 수 있는 공간이라고 생각하면 된다.
이 글에서는 서브에이전트를 언제 쓰는 게 적합한지, 어떻게 호출하는지, 그리고 굳이 쓰지 않아도 되는 경우는 언제인지를 살펴본다.
서브에이전트는 자체 컨텍스트 윈도우를 가진 독립적인 에이전트다. Claude가 서브에이전트를 생성하면, 해당 에이전트는 파일을 읽거나 코드를 탐색하거나 수정 작업을 독자적으로 수행한다. 작업이 끝나면 관련 결과만 메인 대화로 반환한다.
각 서브에이전트는 대화 기록이나 이전에 호출된 스킬의 영향을 받지 않고 깨끗한 상태에서 시작한다. 여러 서브에이전트를 병렬로 실행할 수 있으며, 각각 다른 권한을 부여할 수도 있다. 예를 들어, 조사용 서브에이전트는 읽기 전용 접근 권한을 갖고, 구현 담당 서브에이전트는 편집 권한을 갖는 식이다.
Claude Code에는 다음과 같은 기본 제공 서브에이전트 유형이 있다:
Claude Code는 맡은 작업을 처리하기 위해 스스로 서브에이전트를 생성하기도 한다. 물론 이 동작을 명시적으로 지시할 수도 있고, 재사용 가능한 전문 서브에이전트를 정의해 Claude가 자동으로 위임하도록 설정할 수도 있다. 핵심은 어떤 상황에서 서브에이전트를 써야 하는지 판단하는 것이다.
서브에이전트 위임이 확실히 효과적인 작업 유형이 있다. 이런 패턴을 익히면 기능을 훨씬 잘 활용할 수 있다.
무언가를 수정하기 전에 동작 방식을 파악해야 할 때, 서브에이전트가 코드베이스를 탐색하고 요약본을 반환하도록 하면 수십 개의 파일을 대화에 직접 쏟아붓지 않아도 된다.
판단 신호: 컨텍스트 파악을 위해 수십 개의 파일을 읽어야 하는 경우
기대 효과: 메인 대화가 깔끔하게 유지되고, 원본 내용 대신 정리된 분석 결과만 전달된다.
여러 파일에 걸친 오류 수정, 다수의 컴포넌트 패턴 업데이트처럼 서로 의존성이 없는 변경 작업은 병렬 서브에이전트로 더 빠르게 처리할 수 있다.
판단 신호: 세부 작업들 간 의존 관계가 없는 경우
기대 효과: 서브에이전트 세 개가 동시에 작업하면 하나가 순차적으로 처리할 때보다 훨씬 빨리 완료된다.
구현 결과를 편견 없이 검토해야 할 때, 서브에이전트는 메인 대화의 가정이나 선입견, 맹점을 전혀 물려받지 않은 깨끗한 상태로 시작한다.
판단 신호: 대화 기록의 영향 없이 독립적인 검증이 필요한 경우
기대 효과: 더 객관적이고 명확한 피드백을 얻을 수 있다.
Pro-tip: /clear 명령어도 컨텍스트와 대화 기록을 초기화해 비슷하게 편견 없는 상태를 만들 수 있다. 다만 기록이 완전히 사라진다는 단점이 있다. 서브에이전트를 쓰면 메인 대화는 그대로 유지하면서 동일한 효과를 얻을 수 있다.
변경 사항을 확정하기 전에, 독립적인 서브에이전트가 구현이 테스트에만 맞춰져 있지 않은지, 엣지 케이스를 놓치지는 않았는지 검증할 수 있다.
판단 신호: 코드를 커밋하기 전에 두 번째 검토가 필요한 경우
기대 효과: 코드에 익숙해진 탓에 놓치기 쉬운 문제를 잡아낼 수 있다.
작업이 설계, 구현, 테스트처럼 명확한 단계로 나뉠 때, 각 단계를 집중적으로 처리하면 더 좋은 결과를 얻을 수 있다.
판단 신호: 명확한 인계 지점이 있는 순차적 단계가 존재하는 경우
기대 효과: 각 서브에이전트가 자신의 단계에만 집중하므로, 다른 단계의 컨텍스트가 잡음으로 작용하지 않는다.
Pro-tip: 작업에 10개 이상의 파일 탐색이 필요하거나, 서로 독립적인 작업이 세 개 이상이라면 서브에이전트 사용을 적극적으로 고려할 시점이다.
서브에이전트를 호출하는 방법은 간단한 대화 입력부터 자동화 워크플로까지 다양하다. 어디서 시작할지는 워크플로에 따라 다르며, 패턴이 자리를 잡아가면서 점차 고도화할 수 있다.
가장 유연한 방법은 Claude에게 서브에이전트를 쓰도록 직접 요청하는 것이다. 터미널, VS Code, JetBrains, 웹, 데스크톱 앱 등 모든 Claude Code 인터페이스에서 동작한다.
서브에이전트를 안정적으로 호출하는 자연어 패턴의 예시는 다음과 같다:
명확하게 지시하는 것이 중요하다. 작업 범위를 구체적으로 정하고, 독립적인 작업이라면 병렬 실행을 명시적으로 요청하고, 원하는 결과물 형태를 설명하자.
효과적인 프롬프트 구조의 예시는 다음과 같다:
Use subagents to explore this codebase in parallel:
1. Find all API endpoints and summarize their purposes
2. Identify the database schema and relationships
3. Map out the authentication flow
Return a summary of each, not the full file contents.이 프롬프트가 효과적인 이유는 세 가지 독립 작업을 명확히 정의하고, 병렬 실행을 명시적으로 요청하며, 결과물 형태를 구체적으로 지정했기 때문이다. Claude는 의도를 파악해 적절한 서브에이전트를 생성한다.
대화형 호출을 효과적으로 활용하는 팁은 다음과 같다:
Pro-tip: 서브에이전트가 시간이 걸릴 때는 Ctrl+B로 백그라운드로 보낼 수 있다. 서브에이전트가 실행되는 동안 대화를 계속할 수 있고, 작업이 완료되면 결과가 자동으로 나타난다. /tasks 명령어로 백그라운드에서 실행 중인 작업을 확인할 수 있다.
보안 리뷰어, 테스트 작성자, 문서 교열 담당처럼 동일한 유형의 서브에이전트를 반복적으로 요청하게 된다면, 커스텀 서브에이전트로 한 번만 정의해 두면 된다.
이후부터는 관련 작업이 들어올 때마다 Claude가 별도 지시 없이 자동으로 위임한다.
커스텀 서브에이전트는 .claude/agents/ (프로젝트 단위, 팀 공유)나 ~/.claude/agents/ (사용자 단위, 전체 프로젝트에서 사용 가능)에 마크다운 파일로 저장된다. 각 서브에이전트에는 고유한 시스템 프롬프트와 도구 권한을 부여할 수 있고, 필요에 따라 별도 모델을 지정할 수도 있다.
가장 쉬운 생성 방법은 /agents 명령어를 쓰는 것으로, 대화형으로 설정을 진행하며 설명을 입력하면 초안을 자동으로 만들어 준다. 직접 파일을 작성하는 것도 가능하다. 예시는 다음과 같다:
---
name: security-reviewer
description: Reviews code changes for security vulnerabilities,
injection risks, auth issues, and sensitive data exposure.
Use proactively before commits touching auth, payments, or user data.
tools: Read, Grep, Glob
model: sonnet
---
You are a security-focused code reviewer. Analyze the provided
changes for:
- SQL injection, XSS, and command injection risks
- Authentication and authorization gaps
- Sensitive data in logs, errors, or responses
- Insecure dependencies or configurations
Return a prioritized list of findings with file:line references
and a recommended fix for each. Be critical. If you find nothing,
say so explicitly rather than inventing issues.설정이 완료되면 Claude는 해당 서브에이전트와 맞는 작업을 자동으로 위임한다. "staged 변경 사항을 security-reviewer에게 검토시켜 줘"처럼 이름으로 직접 호출하는 것도 가능하다.
커스텀 서브에이전트가 특히 유용한 경우는 다음과 같다:
Pro-tip: description 필드는 Claude가 언제 위임할지 판단하는 기준이다. 단순한 역할 설명보다 트리거 조건을 구체적으로 작성하는 것이 중요하다. "security expert"보다 "커밋 전 코드 보안 이슈를 검토한다"처럼 작성해야 더 정확하게 라우팅된다.
권한 모드나 프로젝트·사용자 서브에이전트의 상호작용 방식 등 전체 설정 레퍼런스는 Claude Code 서브에이전트 문서를 참고하자.
커스텀 서브에이전트가 전문가를 정의한다면, CLAUDE.md 파일은 언제 그 전문가를 활용할지에 대한 규칙을 정의한다. 모든 코드 리뷰는 읽기 전용 서브에이전트를 거쳐야 한다거나, 아키텍처 관련 질문이 나오면 먼저 조사 단계를 거쳐야 한다는 정책이 있다면 CLAUDE.md에 작성하면 된다. Claude는 매 대화 시작 시 이 파일을 읽으므로, 팀원 모두가 따로 요청하지 않아도 세션 전반에 걸쳐 일관된 동작이 유지된다.
다음과 같은 경우에 CLAUDE.md에 서브에이전트 지침을 작성하는 것이 적합하다:
다음은 특정 조건에서 서브에이전트를 트리거하는 간단한 CLAUDE.md 파일 예시다:
## Code review standards
When asked to review code, ALWAYS use a subagent with READ-ONLY access
(Glob, Grep, Read only). The review should ALWAYS check for:
- Security vulnerabilities
- Performance issues
- Adherence to project patterns in /docs/architecture.md
Return findings as a prioritized list with file:line references.위 CLAUDE.md 파일을 적용하면 코드 리뷰 요청이 있을 때마다 정의된 패턴대로 서브에이전트가 자동 실행되므로, 매번 별도로 지정할 필요가 없다.
CLAUDE.md 파일에 대한 자세한 내용은 코드베이스에 맞게 Claude Code 커스터마이징하기: CLAUDE.md 파일 설정 가이드와 Claude Code CLAUDE.md 파일 공식 문서를 참고하자.
반복적으로 실행하는 복잡한 멀티스텝 워크플로에는 스킬(skill)이 재사용 가능한 인터페이스를 제공한다. .claude/skills/에 스킬을 한 번 정의해 두면 /skill-name으로 직접 호출하거나, 작업이 스킬의 description 필드와 매칭될 때 Claude가 자동으로 불러올 수 있다.
스킬과 CLAUDE.md 파일의 차이는 적용 범위에 있다. CLAUDE.md 파일은 항상 로드되어 모든 상호작용에 영향을 미친다. 반면 스킬은 명시적으로 호출하거나 Claude가 현재 작업을 스킬의 description 필드와 매칭할 때만 로드된다. 따라서 스킬은 매 프롬프트에 적용할 필요는 없지만 필요할 때 쓸 수 있어야 하는 워크플로에 적합하다.
다음과 같은 경우에 스킬이 적합하다:
다음은 포괄적인 코드 리뷰를 위한 deep-review 스킬 예시다:
# .claude/skills/deep-review/SKILL.md
---
name: deep-review
description: Comprehensive code review that checks security,
performance, and style in parallel. Use when reviewing staged
changes before a commit or PR.
---
Run three parallel subagent reviews on the staged changes:
1. Security review - check for vulnerabilities, injection risks,
authentication issues, and sensitive data exposure
2. Performance review - check for N+1 queries, unnecessary iterations,
memory leaks, and blocking operations
3. Style review - check for consistency with project patterns
documented in /docs/style-guide.md
Synthesize findings into a single summary with priority-ranked issues.
Each issue should include the file, line number, and recommended fix.위 예시에서 /deep-review는 필요할 때 세 파트로 구성된 서브에이전트 분석을 실행한다. description에 "커밋 전 staged 변경 사항 검토"가 언급되어 있으므로, 해당 상황에서는 Claude가 이 스킬을 자동으로 활용할 수도 있다.
스킬은 단일 파일이 아닌 디렉터리 단위로 구성된다. SKILL.md, 외에도 Claude가 채워 넣을 템플릿, 예상 형식을 보여주는 출력 예시, 워크플로의 일부로 실행할 스크립트 등을 함께 둘 수 있다. 이전 방식인 레거시 .claude/commands/ 포맷은 단일 파일 구조였기 때문에 모든 내용을 프롬프트 안에 직접 넣어야 했다.
Claude Code에서 스킬을 활용하는 방법은 Claude Code 스킬 문서를 참고하자.
훅(hook)은 Claude Code 라이프사이클의 특정 시점에 자동으로 실행되는 사용자 정의 셸 명령어, HTTP 엔드포인트, 또는 LLM 프롬프트다. 훅을 활용하면 이벤트 기반으로 서브에이전트 워크플로를 자동화할 수 있으며, 수동 호출 없이도 특정 액션에 반응해 서브에이전트 작업을 트리거한다.
다음과 같은 경우에 훅이 적합하다:
다음은 테스트가 통과될 때까지 Claude의 턴 종료를 막는 Stop 훅 예시다:
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-tests.sh"
}
]
}
]
}
}그리고 .claude/hooks/check-tests.sh의 스크립트 내용은 다음과 같다:
#!/bin/bash
INPUT=$(cat)
STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false')
# Don't loop forever — if we already blocked once this turn, let it through
if [ "$STOP_HOOK_ACTIVE" = "true" ]; then
exit 0
fi
if ! npm test --silent > /dev/null 2>&1; then
jq -n '{
decision: "block",
reason: "Tests are failing. Run `npm test` to see the failures and fix them before finishing."
}'
exit 0
fi
exit 0Claude가 턴을 마치면 Stop 이벤트가 발생하고 스크립트가 테스트 스위트를 실행한다. 테스트가 실패하면 decision: "block"와 reason을 포함한 JSON을 반환한다. Claude Code는 이를 읽고 Claude의 종료를 막은 뒤, reason을 다시 대화에 넣어 작업을 계속하도록 지시한다. 상단의 stop_hook_active 가드는 무한 루프를 방지한다. 이전 Stop 훅으로 인해 이미 계속 실행 중인 상태라면 스크립트가 그냥 종료를 허용한다.
훅은 서브에이전트 오케스트레이션을 가장 높은 수준으로 자동화하는 방법이다. 시작은 대화형 호출이나 CLAUDE.md 지침으로 하고, 워크플로가 성숙해지면 그때 훅을 도입하는 것이 좋다.
훅 설정 전체 레퍼런스는 Claude Code 파워 유저 커스터마이징: 훅 설정 방법이나 Claude Code 훅 공식 문서를 참고하자.
아래 패턴들은 자주 접하는 시나리오에 서브에이전트 지시를 적용한 구체적인 예시다.
익숙하지 않은 코드에 기능을 추가할 때, 먼저 서브에이전트에 조사를 맡기면 구현 논의가 탐색적인 과정이 아닌 충분한 정보를 바탕으로 시작된다. 예시는 다음과 같다:
Before I implement user notifications, use a subagent to research:
- How are emails currently sent in this codebase?
- What notification patterns already exist?
- Where should new notification logic live based on the current architecture?
Summarize findings, then we'll plan the implementation together.수십 개의 파일 원본 대신 정리된 요약본이 전달되므로, 구현 논의를 탄탄한 기반에서 시작할 수 있다.
여러 파일에 걸쳐 동일한 패턴을 업데이트해야 할 때, 병렬 서브에이전트로 더 빠르게 처리하면서 집중도도 유지할 수 있다. 예시는 다음과 같다:
Use parallel subagents to update the error handling in these files:
- src/api/users.ts
- src/api/orders.ts
- src/api/products.ts
Each should follow the pattern established in src/api/auth.ts.
Work on all three simultaneously.세 서브에이전트가 병렬로 작업하면 하나가 순차적으로 처리할 때와 비슷한 시간에 완료된다. 각 에이전트는 자신의 파일에만 집중하므로 다른 파일의 컨텍스트로 인한 혼란이나 불일치가 발생하지 않는다.
복잡한 구현을 마친 뒤, 구현 과정의 영향을 받지 않은 서브에이전트에게 검증을 맡기면 익숙함 탓에 놓치기 쉬운 문제를 잡아낼 수 있다. 예시는 다음과 같다:
Use a fresh subagent with read-only access to review my implementation of the payment flow. It should not see our previous discussion. I want an unbiased review.
Check for: security vulnerabilities, unhandled edge cases, and error handling gaps. Be critical.검토 서브에이전트는 어떤 트레이드오프가 고려됐는지, 어떤 접근법이 기각됐는지, 어떤 가정이 있었는지 알지 못한 채 코드를 평가한다. 이 외부적 시각이 메인 대화에서 놓쳤을 문제를 수면 위로 끌어올린다.
여러 단계로 구성된 작업에서 단계 간 명확한 인계를 포함해 서브에이전트를 연결하면 각 단계의 집중도를 높일 수 있다. 예시는 다음과 같다:
Let's build this feature as a pipeline:
1. First subagent: Design the API contract and write it to docs/api-spec.md
2. Second subagent: Implement the backend endpoints based on that spec
3. Third subagent: Write integration tests for the implementation
Each stage should complete before the next begins. Use the output
files as the handoff mechanism between stages.파이프라인 워크플로를 활용하면 각 단계가 집중된 컨텍스트를 받는다. 설계 서브에이전트는 구현 세부 사항에 신경 쓰지 않고, 구현 서브에이전트는 깔끔한 명세서를 바탕으로 작업하며, 테스트 서브에이전트는 결과를 독립적으로 평가한다.
서브에이전트는 유용한 기능이지만 오버헤드도 따른다. 서브에이전트마다 자체 컨텍스트를 구성하고 토큰을 소비하며, 개발자와 작업 사이에 간접 레이어가 하나 더 생긴다. 컨텍스트 격리, 병렬 처리, 또는 독립적인 시각이 실질적으로 도움이 될 때라야 그 비용이 정당화된다.
작업 규모가 작거나 순차적으로 긴밀하게 연결된 작업이라면 메인 대화를 그대로 유지하는 편이 대체로 더 간단하다. 예를 들면 다음과 같다:
앞서 설명한 신호들, 즉 두 번째 의견이 필요하거나, 세부 작업 간 의존성이 없거나, 광범위한 조사가 필요한 경우가 서브에이전트 위임이 충분히 가치 있는 순간임을 알려준다.
서브에이전트는 의도적으로 사용할 때 제 가치를 발휘한다. Claude가 제공하는 자동 호출도 유용하지만, 조사 위임 시점, 병렬화 적용 시점, 독립적인 시각을 요청할 시점을 직접 파악해서 활용하면 더 나은 결과를 얻을 수 있다.
서브에이전트를 처음 쓴다면 대화형 프롬프트로 시작하자. 반복적으로 등장하는 요청 패턴에 주목하고, 패턴이 명확해지면 자동화를 도입하면 된다. 목표는 서브에이전트 위임을 자연스럽게 만들어 정작 중요한 작업에 집중할 수 있는 환경을 만드는 것이다.