어떤 단일 AI 코딩 세션이든 결국 컨텍스트 창 한계에 부딪힙니다. 대규모 리팩토링, 테스트 출력, 코드 리뷰, 디버깅 로그가 한 대화에 쌓이면 에이전트는 중요한 흐름을 놓치기 시작합니다. Claude Code 서브 에이전트는 이 문제를 작업 단위로 분리합니다. 하나의 에이전트가 모든 일을 같은 컨텍스트에서 처리하는 대신, 자체 컨텍스트 창, 자체 지침, 자체 도구 권한을 가진 전문 작업자를 만들어 특정 작업만 수행하게 할 수 있습니다.
이 글은 실습 중심의 빌드 가이드입니다. 사용자 지정 서브 에이전트를 구성 파일로 만드는 방법, YAML 프런트매터 필드의 역할, Claude가 위임 대상을 선택하는 방식, 그리고 코드 리뷰와 API 테스트 작성을 병렬로 실행하는 설정을 다룹니다. 개념부터 보고 싶다면 Claude Code 서브 에이전트란 무엇이며 왜 중요한가를 먼저 참고하세요. 여기서는 실제 구현과 API 테스트 검증 단계에 집중합니다.
요약
Claude Code 서브 에이전트는 .claude/agents/ 디렉토리에 YAML 프런트매터가 포함된 마크다운 파일을 추가해 만듭니다.
필수 구성은 다음과 같습니다.
---
name: code-reviewer
description: "버그, 보안 문제 및 규칙 위반에 대해 코드 변경 사항을 검토합니다. 코드를 작성하거나 편집한 후에 사용하세요."
tools: Read, Grep, Glob
model: sonnet
---
서브 에이전트의 시스템 프롬프트를 여기에 작성합니다.
각 서브 에이전트는 자체 컨텍스트 창에서 실행되고, 허용된 도구만 사용하며, 작업 결과만 메인 스레드로 반환합니다. Claude는 description을 읽고 자동으로 위임하거나, 사용자가 이름으로 직접 호출할 수 있습니다. 공식 참조는 Claude Code 서브 에이전트 문서입니다.
60초 안에 서브 에이전트 이해하기
서브 에이전트는 메인 Claude Code 에이전트가 작업을 위임하는 별도의 에이전트 인스턴스입니다.
메인 에이전트를 선임 엔지니어라고 보면, 서브 에이전트는 특정 업무를 맡는 전문가입니다. 예를 들어 다음처럼 나눌 수 있습니다.
-
code-reviewer: 변경된 코드에서 버그와 보안 이슈를 찾음 -
api-test-writer: 새 엔드포인트에 대한 API 테스트 작성 -
docs-updater: 변경 사항에 맞춰 문서 수정 -
security-auditor: 인증, 권한, 입력 검증을 집중 점검
서브 에이전트를 쓰는 이유는 세 가지입니다.
- 컨텍스트 격리: 중간 로그, 파일 읽기, 테스트 출력이 메인 대화에 쌓이지 않습니다.
- 전문화된 시스템 프롬프트: 검토자, 테스터, 문서 작성자마다 다른 지침을 줄 수 있습니다.
- 도구 권한 제한: 검토자는 읽기만 가능하게 하고, 테스트 작성자는 필요한 경우에만 쓰기와 셸 실행을 허용할 수 있습니다.
이 구조는 작업 단위에 적용한 Claude Code 에이전트 하네스와 같은 접근입니다.
서브 에이전트를 사용하는 이유
1. 컨텍스트 격리
긴 세션에서는 다음과 같은 정보가 계속 누적됩니다.
- 파일 탐색 결과
- 테스트 실패 로그
- 디버깅 출력
- 임시 설계 논의
- 리뷰 코멘트
- 실패한 접근 방식
이 모든 것이 메인 컨텍스트에 남으면 이후 작업의 품질이 떨어질 수 있습니다.
서브 에이전트를 사용하면 메인 에이전트는 다음처럼 짧은 결과만 받습니다.
code-reviewer 결과:
- payment.ts:42에서 null 처리 누락
- order-controller.ts:88에서 권한 검증 누락 가능성
- 테스트 커버리지에 400 응답 케이스 없음
중간 탐색 과정은 서브 에이전트 컨텍스트에 머물고, 메인 스레드는 깨끗하게 유지됩니다. 토큰 비용 측면에서도 유리합니다. 관련 내용은 에이전트 토큰 비용 절감 글에서 더 자세히 다룹니다.
2. 병렬 처리
독립적인 작업은 순차적으로 실행할 필요가 없습니다.
예를 들어 새 주문 API를 구현한 뒤 다음 작업을 동시에 실행할 수 있습니다.
메인 에이전트
├─ code-reviewer: 변경된 diff 검토
├─ api-test-writer: API 테스트 작성 및 실행
└─ docs-updater: API 문서 업데이트
전체 소요 시간은 세 작업의 합이 아니라 가장 오래 걸리는 작업에 가까워집니다. Claude Code의 동적 워크플로우는 이 방식을 더 큰 규모의 병렬 작업으로 확장합니다.
3. 전문화
범용 에이전트는 여러 작업을 처리할 수 있지만, 각 작업에 최적화되어 있지는 않습니다.
예를 들어 코드 리뷰용 서브 에이전트에는 다음처럼 지시할 수 있습니다.
형식적인 칭찬은 하지 마세요.
실제 버그, 보안 취약점, 회귀 가능성만 보고하세요.
파일과 줄 번호를 포함하세요.
확신이 낮은 추측은 제외하세요.
테스트 작성자에게는 다른 지침을 줄 수 있습니다.
성공 케이스만 작성하지 마세요.
검증 오류, 인증 실패, 권한 오류, 스키마 불일치를 반드시 포함하세요.
테스트를 실행하고 실패 원인을 요약하세요.
이렇게 하면 하나의 과부하된 에이전트 대신 작은 전문가 팀을 운영할 수 있습니다.
사용자 지정 서브 에이전트 만드는 방법
프로젝트 단위 서브 에이전트는 다음 경로에 둡니다.
.claude/agents/
개인용 전역 서브 에이전트는 다음 경로에 둡니다.
~/.claude/agents/
파일은 일반 마크다운입니다.
mkdir -p .claude/agents
touch .claude/agents/code-reviewer.md
예시 1: 코드 리뷰 서브 에이전트
.claude/agents/code-reviewer.md:
---
name: code-reviewer
description: 버그, 보안 문제 및 규칙 위반에 대해 코드 변경 사항을 검토합니다. 코드를 작성하거나 편집한 후에 사용하세요.
tools: Read, Grep, Glob
model: sonnet
---
당신은 선임 코드 검토자입니다. diff 또는 파일 세트가 주어지면:
1. 정확성 버그, 보안 취약점 및 놓친 엣지 케이스를 찾으세요.
2. 코드가 프로젝트의 기존 규칙과 일치하는지 확인하세요.
3. 심각도별로 순위를 매겨 신뢰도 높은 문제만 보고하세요.
출력 형식:
## 판정
- 통과 또는 수정 필요
## 주요 문제
- [심각도] 파일:라인 — 문제 설명
- 재현 조건 또는 영향
- 제안 수정 방향
## 테스트 누락
- 누락된 테스트 케이스 목록
구체적으로 작성하세요. 파일과 줄 번호를 인용하세요. 형식적인 승인은 하지 마세요.
프런트매터 필드 설명
| 필드 | 역할 |
|---|---|
name |
서브 에이전트를 호출할 때 사용하는 식별자 |
description |
Claude가 자동 위임 시점을 판단하는 설명 |
tools |
서브 에이전트가 사용할 수 있는 도구 허용 목록 |
model |
선택적으로 사용할 모델 지정 |
description은 특히 중요합니다. 단순히 "코드 리뷰어"라고 쓰는 것보다 다음처럼 트리거를 포함하는 편이 좋습니다.
description: 버그, 보안 문제 및 규칙 위반에 대해 코드 변경 사항을 검토합니다. 코드를 작성하거나 편집한 후에 사용하세요.
본문은 서브 에이전트의 시스템 프롬프트입니다. 신입 팀원에게 업무를 맡긴다고 생각하고 작성하세요.
- 무엇을 해야 하는가
- 무엇을 우선해야 하는가
- 어떤 출력 형식을 따라야 하는가
- 무엇을 하지 말아야 하는가
- 어떤 프로젝트 규칙을 따라야 하는가
프로젝트 규칙은 design.md 또는 AGENTS.md와 함께 관리하면 반복을 줄일 수 있습니다.
서브 에이전트를 호출하는 방법
서브 에이전트는 두 가지 방식으로 실행됩니다.
1. 자동 위임
Claude는 사용 가능한 서브 에이전트의 description을 읽고, 현재 작업과 맞는 에이전트를 자동으로 선택합니다.
예를 들어 code-reviewer의 설명에 다음 문장이 있으면:
description: 버그, 보안 문제 및 규칙 위반에 대해 코드 변경 사항을 검토합니다. 코드를 작성하거나 편집한 후에 사용하세요.
Claude는 코드 편집 후 리뷰 작업을 이 서브 에이전트에 넘길 수 있습니다.
자동 위임을 잘 동작하게 하려면 설명을 이렇게 작성하세요.
# 나쁜 예
description: 코드 리뷰어
# 좋은 예
description: 코드 변경 후 버그, 보안 문제, 규칙 위반을 검토할 때 사용하세요.
2. 명시적 호출
특정 서브 에이전트를 직접 지정할 수도 있습니다.
주문 모듈 변경 사항에 대해 code-reviewer 서브 에이전트를 사용하세요.
또는:
새로 추가한 POST /orders 엔드포인트에 대해 api-test-writer 서브 에이전트를 사용해서 테스트를 작성하고 실행하세요.
위임 흐름을 더 확정적으로 제어해야 한다면 슬래시 명령이나 SDK를 사용하는 편이 좋습니다. 구성 표면은 Claude Code 개요를 참고하세요.
서브 에이전트 vs 에이전트 SDK vs 동적 워크플로우
| 도구 | 제어 모델 | 최적의 용도 |
|---|---|---|
| 서브 에이전트 | 모델이 위임 시점을 결정하거나 사용자가 직접 지정 | 세션 내 전문화, 경량 병렬 처리 |
| 동적 워크플로우 | 모델이 하나의 세션에서 대규모 확장 조율 | 많은 병렬 작업, 광범위한 처리 |
| 에이전트 SDK | 코드에서 제어 흐름을 직접 작성 | 확정적 루프, 예약 실행, 무인 실행 |
실무 기준은 간단합니다.
- Claude Code 세션 안에서 전문가 몇 명이 필요하다면 서브 에이전트
- 많은 독립 작업을 한 세션에서 확장하려면 동적 워크플로우
- 예약 실행, CI, 무인 루프가 필요하다면 에이전트 SDK
프로그래밍 방식의 오케스트레이션이 필요하다면 Claude 에이전트 SDK를 사용하세요. 호스팅 옵션과 직접 구축을 비교하려면 관리형 에이전트 vs 에이전트 SDK를 참고할 수 있습니다.
실용적인 예시: 코드 리뷰와 API 테스트 병렬 실행
새로운 주문 엔드포인트를 구현했다고 가정해 보겠습니다.
POST /orders
필요한 후속 작업은 두 가지입니다.
- 변경된 코드 리뷰
- API 테스트 작성 및 실행
이 작업들은 서로 독립적이므로 병렬로 실행할 수 있습니다.
1단계: 코드 리뷰 서브 에이전트 만들기
.claude/agents/code-reviewer.md:
---
name: code-reviewer
description: 버그, 보안 문제 및 규칙 위반에 대해 코드 변경 사항을 검토합니다. 코드를 작성하거나 편집한 후에 사용하세요.
tools: Read, Grep, Glob
model: sonnet
---
당신은 선임 코드 검토자입니다.
다음을 확인하세요:
1. 정확성 버그
2. 보안 취약점
3. 인증 및 권한 누락
4. 입력 검증 누락
5. 프로젝트 규칙 위반
6. 놓친 엣지 케이스
출력 형식:
## 판정
통과 또는 수정 필요
## 문제 목록
- [심각도] 파일:라인 — 설명
- 영향
- 수정 제안
확신이 높은 문제만 보고하세요.
2단계: API 테스트 작성 서브 에이전트 만들기
.claude/agents/api-test-writer.md:
---
name: api-test-writer
description: 새롭거나 변경된 엔드포인트에 대한 API 테스트 케이스를 작성합니다. 엔드포인트가 구현된 후에 사용하세요.
tools: Read, Grep, Write, Bash
model: sonnet
---
당신은 프로젝트의 OpenAPI 사양에 따라 API 테스트를 작성합니다.
작업 순서:
1. OpenAPI 사양과 엔드포인트 구현을 읽으세요.
2. 성공 케이스를 작성하세요.
3. 유효성 검사 오류 케이스를 작성하세요.
4. 인증 실패 케이스를 작성하세요.
5. 권한 오류 케이스가 필요하면 추가하세요.
6. 상태 코드를 단언하세요.
7. 응답 본문을 스키마에 대해 검증하세요.
8. 테스트 스위트를 실행하세요.
9. 통과/실패와 실패 이유를 보고하세요.
출력 형식:
## 테스트 파일
- 생성 또는 수정한 파일 목록
## 커버리지
- 성공 케이스
- 검증 오류
- 인증/권한
- 스키마 검증
## 실행 결과
- 명령어
- 통과/실패
- 실패 원인
3단계: 메인 에이전트에 병렬 작업 요청하기
Claude Code에서 다음처럼 요청합니다.
POST /orders 구현이 끝났습니다.
code-reviewer 서브 에이전트로 변경 사항을 검토하고,
api-test-writer 서브 에이전트로 API 테스트를 작성하고 실행하세요.
두 작업은 독립적이므로 병렬로 진행하세요.
기대하는 결과는 다음과 같습니다.
code-reviewer 결과:
- order.service.ts:73에서 재고 부족 처리 누락
- order.controller.ts:45에서 인증 사용자 확인 필요
api-test-writer 결과:
- orders.e2e.spec.ts 추가
- 201 성공 케이스 통과
- 400 validation error 케이스 통과
- 401 인증 실패 케이스 통과
이 구조의 핵심은 테스트 서브 에이전트가 검증 게이트 역할을 한다는 점입니다. 에이전트가 “완성됐다”고 말하는 것이 아니라, 실제 테스트가 엔드포인트 동작을 검증해야 합니다. 이는 코딩 에이전트 루프의 핵심 원칙입니다.
API 테스트를 더 신뢰할 수 있게 만들려면 테스트 서브 에이전트를 실제 API 테스트 플랫폼에 연결하세요. Apidog를 사용하는 팀은 서브 에이전트를 Apidog 테스트 시나리오와 연결해 응답을 스키마에 대해 검증할 수 있습니다. 또한 에이전트의 라이브 엔드포인트 호출을 Apidog AI 에이전트 디버거를 통해 라우팅하면 사람이 디버깅하듯 요청과 응답을 확인할 수 있습니다.
이 설정을 루프로 감싸면 사용자 없이 실행되는 Claude 워크플로우처럼 무인 검증 워크플로우로 확장할 수 있습니다. 테스트 게이트가 스키마를 인식하도록 하려면 Apidog를 다운로드하세요.
모범 사례
서브 에이전트당 하나의 책임만 부여하세요
좋은 분리:
code-reviewer → 리뷰만 수행
api-test-writer → 테스트 작성 및 실행
docs-updater → 문서 수정
security-auditor → 보안 점검
나쁜 분리:
super-agent → 리뷰, 테스트, 문서, 보안, 리팩토링을 모두 수행
모든 일을 하는 서브 에이전트는 사실상 메인 에이전트를 하나 더 만든 것과 같습니다.
description을 트리거 중심으로 작성하세요
자동 위임은 description 품질에 크게 의존합니다.
# 나쁜 예
description: 테스트 작성자
# 좋은 예
description: 새롭거나 변경된 API 엔드포인트가 구현된 후 테스트 케이스를 작성하고 실행할 때 사용하세요.
최소 권한 원칙을 적용하세요
리뷰어는 코드를 수정할 필요가 없습니다.
tools: Read, Grep, Glob
테스트 작성자는 파일 작성과 테스트 실행이 필요할 수 있습니다.
tools: Read, Grep, Write, Bash
권한을 의도적으로 제한하면 자동화 중 원치 않는 변경을 줄일 수 있습니다.
작업별로 모델을 고정하세요
기계적인 작업은 빠르고 저렴한 모델을 사용할 수 있습니다. 복잡한 추론이 필요한 보안 감사나 설계 검토는 더 강한 모델을 지정하세요.
model: sonnet
결과 형식을 고정하세요
서브 에이전트가 매번 다른 형식으로 보고하면 메인 에이전트가 후속 조치를 하기 어렵습니다.
다음처럼 출력 구조를 지정하세요.
## 판정
통과 / 수정 필요
## 문제 목록
- [심각도] 파일:라인 — 설명
## 실행 결과
- 명령어
- 통과/실패
- 실패 원인
## 다음 조치
- 우선순위순 수정 목록
과도하게 중첩하지 마세요
서브 에이전트가 또 다른 서브 에이전트를 호출하고, 그 서브 에이전트가 다시 다른 서브 에이전트를 호출하면 추적이 어려워지고 비용도 증가합니다.
실무에서는 다음 정도의 얕은 구조가 관리하기 좋습니다.
메인 에이전트
├─ code-reviewer
├─ api-test-writer
└─ docs-updater
이 원칙은 에이전트 워크플로우 도구 연결 패턴에서도 동일하게 적용됩니다.
서브 에이전트를 언제 사용해야 하는가
다음 조건을 만족하면 서브 에이전트가 적합합니다.
- 작업 경계가 명확함
- 메인 작업과 독립적임
- 중간 출력이 많음
- 병렬 실행 가치가 있음
- 결과를 요약해서 받을 수 있음
좋은 예:
- 코드 리뷰
- API 테스트 작성
- 테스트 실패 원인 분석
- 보안 감사
- 특정 모듈 문서화
- 버그 재현
- 마이그레이션 영향 범위 조사
예를 들어 새 엔드포인트 구현 후 리뷰와 테스트를 병렬로 실행하는 작업은 서브 에이전트에 잘 맞습니다.
서브 에이전트를 사용하지 말아야 하는 경우
다음 작업에는 서브 에이전트를 쓰지 않는 편이 낫습니다.
- 변수명 하나 변경
- 한 줄짜리 버그 수정
- 메인 에이전트가 이미 필요한 모든 컨텍스트를 보고 있는 작업
- 강하게 순차적인 작업
- 서브 에이전트에게 설명해야 할 맥락이 너무 많은 작업
일반 규칙은 다음과 같습니다.
한 단락으로 설명할 수 있을 만큼 독립적이고, 병렬 실행할 가치가 있으면 위임하세요. 그렇지 않으면 메인 스레드에서 처리하세요.
많은 동시 서브 에이전트로 확장할 때는 동적 워크플로우의 오케스트레이션 패턴을 참고하세요.
흔한 실수
모호한 설명
description: 리뷰어
이런 설명은 자동 위임에 도움이 되지 않습니다.
대신:
description: 코드 변경 후 버그, 보안 문제, 프로젝트 규칙 위반을 검토할 때 사용하세요.
하나의 비대한 서브 에이전트
하나의 서브 에이전트에 리뷰, 테스트, 문서, 보안 감사를 모두 넣으면 전문화 이점이 사라집니다. 책임별로 나누세요.
모든 도구를 기본 상속
tools를 생략하면 서브 에이전트가 메인 에이전트의 도구를 상속할 수 있습니다. 신뢰할 수 있는 수동 작업에는 괜찮을 수 있지만, 자동화된 작업에서는 위험합니다.
가능하면 명시적으로 제한하세요.
tools: Read, Grep, Glob
검증 서브 에이전트 없음
리뷰만 있고 테스트 실행이 없으면 “그럴듯한 코드”가 통과할 수 있습니다. 특히 API 작업에서는 실제 테스트를 실행하는 서브 에이전트를 두는 것이 좋습니다.
서브 에이전트를 SDK처럼 사용
서브 에이전트는 세션 내에서 모델이 파견하는 작업자입니다. 확정적인 예약 실행, CI 루프, 무인 자동화가 필요하면 서브 에이전트 더미가 아니라 에이전트 SDK를 사용하세요.
Anthropic의 효과적인 에이전트 구축에서도 같은 방향을 제안합니다. 더 큰 프롬프트보다 명확한 구조와 역할 분리가 중요합니다.
자주 묻는 질문
Claude Code 서브 에이전트란 무엇인가요?
메인 Claude Code 에이전트가 작업을 위임하는 별도의 에이전트 인스턴스입니다. 각 서브 에이전트는 자체 컨텍스트 창, 사용자 지정 시스템 프롬프트, 구성 가능한 도구 세트를 가집니다.
Claude Code 서브 에이전트는 어떻게 만드나요?
프로젝트에서는 .claude/agents/, 개인 설정에서는 ~/.claude/agents/에 마크다운 파일을 만듭니다. 파일 상단에 name, description, 선택적 tools, 선택적 model을 포함한 YAML 프런트매터를 작성하고, 본문에 시스템 프롬프트를 추가합니다.
Claude는 어떤 서브 에이전트를 사용할지 어떻게 결정하나요?
각 서브 에이전트의 description을 읽고 현재 작업과 일치하면 자동으로 위임합니다. 사용자가 "code-reviewer 서브 에이전트를 사용하세요"처럼 명시적으로 호출할 수도 있습니다.
서브 에이전트와 Claude 에이전트 SDK의 차이점은 무엇인가요?
서브 에이전트는 Claude Code 세션 안에서 모델이 파견하는 전문가입니다. 에이전트 SDK는 코드로 제어 흐름을 작성하는 프로그래밍 방식입니다. 대화형 전문화에는 서브 에이전트를, 예약 실행이나 무인 루프에는 SDK를 사용하세요.
서브 에이전트는 병렬로 실행될 수 있나요?
네. 메인 에이전트는 독립적인 작업을 여러 서브 에이전트에 동시에 위임할 수 있습니다. 예를 들어 코드 리뷰, API 테스트 작성, 문서 업데이트를 동시에 진행할 수 있습니다.
서브 에이전트가 API 테스트에 어떻게 도움이 되나요?
OpenAPI 사양을 읽고 API 테스트를 작성·실행하는 서브 에이전트를 만들 수 있습니다. 이 서브 에이전트는 엔드포인트가 실제로 동작하는지 확인하는 검증 게이트가 됩니다. Apidog 같은 플랫폼과 연결하면 응답을 스키마에 따라 검증할 수 있습니다.
핵심 요약
Claude Code 서브 에이전트는 하나의 컨텍스트 창에 모든 작업을 넣는 문제를 줄여줍니다. 각 작업에 자체 컨텍스트, 지침, 도구 권한을 부여하면 메인 에이전트는 더 깨끗한 상태를 유지하고, 전문 작업자는 병렬로 실행될 수 있습니다.
처음에는 두 개만 만들어도 충분합니다.
.claude/agents/
├─ code-reviewer.md
└─ api-test-writer.md
code-reviewer는 읽기 전용으로 제한하고, api-test-writer는 테스트 작성과 실행에 필요한 도구만 허용하세요. 그리고 테스트 서브 에이전트를 실제 API 스위트에 연결해 검증 게이트로 사용하세요.
엔드포인트 작업에서는 Apidog가 해당 게이트에 필요한 스키마와 테스트 흐름을 제공합니다. 다운로드해서 테스트 서브 에이전트가 코드가 실제로 동작함을 증명하게 만드세요.
Top comments (0)