클로드 맞춤형 코드 서브 에이전트 생성 방법 (구성 가이드)

어떤 단일 AI 코딩 세션이든 한계에 부딪히게 되는데, 바로 컨텍스트 창입니다. 대규모 리팩토링, 세 번의 테스트 출력, 코드 리뷰 등으로 하나의 대화를 가득 채우면 에이전트가 흐름을 놓치기 시작합니다. Claude Code 서브 에이전트가 이 문제의 해결책입니다. 하나의 에이전트가 모든 것을 하나의 컨텍스트에서 처리하는 대신, 자체 컨텍스트 창, 자체 지침, 자체 도구 권한을 가진 집중된 작업자를 생성할 수 있습니다. 이들은 하나의 작업을 수행하고, 결과를 반환하며, 메인 스레드를 깨끗하게 유지합니다.

이것은 실습 빌드 가이드입니다. 사용자 지정 서브 에이전트를 구성 파일로 만드는 방법, 각 프런트매터 필드가 하는 역할, Claude가 서브 에이전트에 작업을 위임하는 방법, 그리고 하나의 에이전트가 코드를 검토하는 동안 다른 에이전트가 병렬로 테스트를 작성하는 실용적인 설정을 연결하는 방법에 대해 설명합니다. 개념적인 개요를 먼저 원한다면, Claude Code 서브 에이전트란 무엇이며 왜 중요한가에 대한 글에서 기본 사항을 다루고 있습니다. 여기서는 서브 에이전트 구축과 테스트 서브 에이전트를 신뢰할 수 있는 검증 단계로 전환하는 API 테스트 측면에 중점을 둡니다.

요약

Claude Code 서브 에이전트는 `.claude/agents/` 디렉토리에 YAML 프런트매터가 포함된 마크다운 파일을 작성하여 생성합니다. 프런트매터에는 `name`, Claude에게 위임 시점을 알려주는 `description`, 선택적 `tools` 허용 목록, 선택적 `model`이 포함됩니다. 파일 본문은 서브 에이전트의 시스템 프롬프트가 됩니다. 각 서브 에이전트는 자체 도구를 사용하여 자체 컨텍스트 창에서 실행되므로 컨텍스트 격리, 병렬 처리 및 전문화를 얻을 수 있습니다. Claude는 설명에 따라 자동으로 위임하거나, 이름으로 서브 에이전트를 호출할 수 있습니다. 공식 참조 자료는 Claude Code 서브 에이전트 문서입니다.

60초 안에 서브 에이전트 이해하기

서브 에이전트는 메인 Claude Code 에이전트가 작업을 위임하는 별도의 에이전트 인스턴스입니다. 메인 에이전트가 선임 엔지니어라면, 서브 에이전트는 메인 에이전트가 불러들이는 전문가입니다. 전문가는 자체 컨텍스트 창과 시스템 프롬프트를 사용하여 자체 대화에서 작업한 후 결과만 반환합니다. 다음 세 가지 속성 때문에 서브 에이전트를 구성할 가치가 있습니다.

자체 컨텍스트 창. 서브 에이전트는 할당된 작업만 가지고 새로 시작하므로, 메인 스레드가 서브 에이전트의 중간 작업으로 가득 차는 일이 없습니다.
사용자 지정 시스템 프롬프트. 보안 취약점을 찾는 검토자, 사용자 규칙을 따르는 테스트 작성자처럼 서브 에이전트의 동작 방식을 직접 설정할 수 있습니다.
구성 가능한 도구. 각 서브 에이전트에 필요한 도구만 부여하므로, 검토자가 코드를 작성할 수 없고 테스트 실행자는 필요한 만큼의 셸 액세스만 가질 수 있습니다.

이것이 개념적인 기본입니다. 개념 개요에서는 왜 중요한지에 대해 더 자세히 다룹니다. 이 가이드의 나머지 부분은 서브 에이전트 구축에 관한 것으로, 개별 작업 수준에 적용된 Claude Code 에이전트 하네스와 동일한 원칙입니다.

서브 에이전트를 사용하는 이유

세 가지 이유가 있으며, 이들은 서로 시너지를 냅니다.

컨텍스트 격리. 컨텍스트 창이 채워지면 긴 세션의 성능이 저하됩니다. 모든 파일 읽기, 모든 테스트 실행, 모든 곁가지 작업은 예산을 소모하고 집중력을 분산시킵니다. 큰 작업을 서브 에이전트에 위임하면 모든 작업이 서브 에이전트의 컨텍스트에 유지되고 메인 컨텍스트에는 쌓이지 않습니다. 메인 에이전트는 50,000 토큰의 중간 노이즈 대신 깨끗한 요약을 받게 됩니다. 이러한 격리는 또한 부풀려진 컨텍스트를 모든 단계에서 끌고 다니지 않기 때문에 비용 절감 효과도 있습니다. 에이전트 토큰 비용 절감에 대한 저희 글에서 경제적 측면을 다루고 있습니다.

병렬 처리. 독립적인 작업은 순서대로 실행될 필요가 없습니다. 메인 에이전트는 여러 서브 에이전트를 한 번에 파견할 수 있습니다. 예를 들어, 한 모듈을 검토하는 동안 다른 모듈을 테스트하고 세 번째 모듈을 문서화할 수 있습니다. 실제 소요 시간은 전체 합이 아니라 가장 느린 단일 작업의 시간으로 줄어듭니다. Claude Code의 동적 워크플로우는 이 기능을 극한으로 활용하여 단일 세션에서 수백 개의 병렬 서브 에이전트를 확장합니다.

전문화. 범용 에이전트는 모든 것을 잘하지만, 어떤 것도 탁월하게 잘하지 못합니다. 명확한 시스템 프롬프트와 올바른 도구를 갖춘 서브 에이전트는 한 가지 일에 탁월합니다. 적대적으로 프롬프트된 검토자는 일반적인 검토자보다 더 많은 버그를 찾아냅니다. 여러분의 단언 스타일을 아는 테스트 작성자는 실제로 유지할 테스트를 만듭니다. 여러분은 과부하된 한 명의 범용 전문가 대신 소규모 전문가 팀을 구축하는 것입니다.

사용자 지정 서브 에이전트를 만드는 방법

서브 에이전트는 일반 마크다운 파일입니다. 프로젝트 수준의 서브 에이전트는 `.claude/agents/`에, 개인 서브 에이전트는 `~/.claude/agents/`에 저장합니다. 각 파일에는 YAML 프런트매터와 서브 에이전트의 시스템 프롬프트가 되는 본문이 있습니다.

다음은 코드 검토자입니다:

---
name: code-reviewer
description: 버그, 보안 문제 및 규칙 위반에 대해 코드 변경 사항을 검토합니다. 코드를 작성하거나 편집한 후에 사용하세요.
tools: Read, Grep, Glob
model: sonnet
---

당신은 선임 코드 검토자입니다. diff 또는 파일 세트가 주어지면:

1. 정확성 버그, 보안 취약점 및 놓친 엣지 케이스를 찾으세요.
2. 코드가 프로젝트의 기존 규칙과 일치하는지 확인하세요.
3. 심각도별로 순위를 매겨 신뢰도 높은 문제만 보고하세요.

구체적으로 작성하세요. 파일과 줄 번호를 인용하세요. 형식적인 승인은 하지 마세요.

프런트매터 필드:

name — 서브 에이전트를 호출할 때 사용하는 식별자입니다.
description — 이것이 중요합니다. Claude는 이를 읽고 자동으로 위임할 시기를 결정합니다. 모호한 레이블이 아니라 명확한 트리거("코드 작성 후 사용")로 작성하세요.
tools — 허용 목록입니다. 생략하면 메인 에이전트의 도구를 상속하거나, 특정 도구를 나열하여 제한할 수 있습니다. 코드를 작성할 수 없는 검토자는 실수로 코드를 변경할 수 없습니다.
model — 선택적으로 모델을 고정할 수 있습니다. 기계적인 서브 에이전트에는 더 저렴하고 빠른 모델을 사용하고, 어려운 추론에는 더 강력한 모델을 사용하세요.

본문은 시스템 프롬프트입니다. 여기에 전문화가 담겨 있으므로, 신입 직원에게 브리핑하듯이 작성하세요. 무엇을 할지, 무엇을 우선순위에 둘지, 무엇을 피할지 등을요. 프로젝트 design.md 또는 AGENTS.md와 함께 사용하면, 모든 파일에 반복할 필요 없이 서브 에이전트에 여러분의 규칙을 알려줄 수 있습니다.

서브 에이전트를 호출하는 방법

서브 에이전트는 두 가지 방식으로 실행됩니다.

자동 위임. Claude는 사용 가능한 모든 서브 에이전트의 description 필드를 읽고, 작업이 일치할 때 스스로 위임합니다. 파일을 편집하고 나면 메인 에이전트가 `code-reviewer`에게 지시하지 않아도 diff를 넘길 수 있는데, 이는 description에 "코드 작성 후 사용"이라고 명시되어 있기 때문입니다. 좋은 설명은 좋은 위임으로 이어집니다.

명시적 호출. 직접 이름을 지정하여 호출할 수도 있습니다. 예를 들어, "주문 모듈의 변경 사항에 대해 code-reviewer 서브 에이전트를 사용하세요."라고 말이죠. 이는 위임을 우연에 맡기고 싶지 않을 때 특정 전문가를 강제로 사용하게 하는 방법입니다.

어느 쪽이든, 서브 에이전트는 자체 컨텍스트에서 실행되어 작업을 수행하고 결과를 메인 스레드에 반환합니다. 위임이 발생하는 것을 볼 수 있으며, 얼마나 많은 세부 정보를 표시할지 구성할 수 있습니다. 서브 에이전트를 확정적이고 반복 가능한 순서로 연결하려면 슬래시 명령과 SDK가 임시 프롬프트보다 더 많은 제어를 제공합니다. Claude Code 개요에서 구성 표면을 다룹니다.

서브 에이전트 vs 에이전트 SDK vs 동적 워크플로우

이들은 서로 겹치는 부분이 있으므로, 각 기능이 언제 적합한지 알아보겠습니다.

도구	제어 모델	최적의 용도
서브 에이전트	모델이 위임 시점을 결정 (또는 직접 지정)	세션 내 전문화 및 경량 병렬 처리
동적 워크플로우	모델이 하나의 세션에서 대규모 확장 조율	수백 개의 병렬 작업, 광범위한 처리
에이전트 SDK	코드에서 제어 흐름을 직접 작성	확정적 루프, 예약 또는 무인 실행

서브 에이전트는 세션 내에서 대화형으로 사용할 수 있는 옵션입니다. Claude Code에서 작업하면서 한두 명의 전문가가 필요할 때 사용합니다. 사람 없이 일정에 따라 실행되는 프로그래밍 방식의 루프가 필요할 때는 Claude 에이전트 SDK를 사용하여 직접 오케스트레이션을 작성합니다. 호스팅 옵션과 직접 구축하는 것을 저울질하고 있다면, 관리형 에이전트 vs 에이전트 SDK 비교 글에서 장단점을 분석합니다. 이 세 가지는 경쟁 관계라기보다는 상호 작용적인 방식부터 완전 자동화까지 이르는 사다리의 여러 단계라고 할 수 있습니다.

실용적인 예시: 병렬 검토 및 테스트 작성

이제 이를 종합해 봅시다. 메인 에이전트가 새로운 주문 엔드포인트를 구현했다고 가정해 봅시다. 이 엔드포인트는 검토와 테스트가 필요하며, 이들이 순차적으로 진행될 이유는 없습니다.

두 개의 서브 에이전트를 정의합니다. 위에서 설명한 `code-reviewer`와 테스트 작성자입니다:

---
name: api-test-writer
description: 새롭거나 변경된 엔드포인트에 대한 API 테스트 케이스를 작성합니다. 엔드포인트가 구현된 후에 사용하세요.
tools: Read, Grep, Write, Bash
model: sonnet
---

당신은 프로젝트의 OpenAPI 사양에 따라 API 테스트를 작성합니다.

1. 사양과 엔드포인트 구현을 읽으세요.
2. 성공, 유효성 검사 오류 및 인증을 다루는 테스트를 작성하세요.
3. 상태 코드를 단언하고 스키마에 대해 응답 본문을 검증하세요.
4. 테스트 스위트를 실행하고 통과/실패 및 이유를 보고하세요.

이제 메인 에이전트는 두 서브 에이전트를 동시에 파견합니다. 검토자는 diff를 읽고, 테스트 작성자는 사양을 읽고 커버리지를 작성합니다. 두 명의 전문가, 두 개의 격리된 컨텍스트가 병렬로 실행됩니다. 메인 스레드는 깨끗하게 유지되며, 검토 보고서와 테스트 결과라는 두 가지 요약을 받게 됩니다.

그 테스트 결과는 이 시스템을 신뢰할 수 있게 만드는 부분입니다. API 스위트를 실행하는 서브 에이전트는 검증 게이트 역할을 하며, 엔드포인트가 완성된 것처럼 보이는지 여부가 아니라 실제로 작동하는지 여부를 확정적으로 확인합니다. 이것이 코딩 에이전트 루프의 핵심 아이디어입니다. 에이전트 자체의 확신은 중요하지 않으며, 게이트의 판정이 중요합니다. 테스트 서브 에이전트를 실제 API 테스트 플랫폼에 연결하면 피드백이 더욱 명확해집니다. Apidog를 사용하는 팀은 서브 에이전트를 Apidog 테스트 시나리오에 연결하여 모든 응답이 스키마 유효성 검사를 거치도록 하고, 에이전트의 라이브 엔드포인트 호출을 Apidog AI 에이전트 디버거를 통해 라우팅하여 사람이 테스트하듯이 요청을 검사할 수 있습니다. 동일한 설정을 루프로 감싸면, 사용자 없이 실행되는 Claude 워크플로우에서 구축한 무인 워크플로우를 얻을 수 있습니다. 테스트 게이트가 기본적으로 스키마를 인식하도록 하려면 Apidog를 다운로드하세요.

모범 사례

몇 가지 습관은 서브 에이전트를 혼란스럽지 않고 유용하게 유지하는 데 도움이 됩니다.

서브 에이전트당 하나의 책임. 검토자는 검토만 합니다. 테스터는 테스트만 합니다. 모든 것을 다 하는 서브 에이전트를 만들지 마세요. 그것은 단지 추가 단계가 있는 메인 에이전트에 불과합니다.
위임을 위한 설명을 작성하세요. description 필드는 Claude가 서브 에이전트를 호출할 시기를 결정하는 방법입니다. 제목이 아닌 명확한 트리거로 만드세요. "버그 검토를 위해 코드 편집 후 사용"이 "코드 검토자"보다 낫습니다.
최소 권한 부여. 각 서브 에이전트가 필요한 도구만 나열하세요. 쓰기 액세스 권한이 없는 검토자는 검토하는 내용을 변경할 수 없습니다. 이는 무인 실행 시 더욱 중요합니다.
작업별로 적절한 모델 고정. 기계적인 서브 에이전트는 더 빠르고 저렴한 모델에서 실행할 수 있습니다. 어려운 추론을 수행하는 서브 에이전트에는 가장 강력한 모델을 남겨두세요. 이는 속도와 비용을 모두 제어합니다.
구조화된 결과 반환. 서브 에이전트에게 일관된 형식(판정, 문제 목록, 통과/실패)으로 보고하도록 요청하세요. 구조화된 출력은 메인 에이전트와 여러분이 조치하기에 더 쉽습니다.
과도하게 중첩하지 마세요. 서브 에이전트가 서브 에이전트를 호출하고 또 다른 서브 에이전트를 호출하는 방식은 따라가기 어렵고 비용이 많이 듭니다. 계층 구조를 얕게 유지하세요.

이러한 내용은 에이전트 워크플로우 도구 연결 패턴에서 다룬 배선 패턴을 반영하며, 서브 에이전트가 두 개든 스무 개든 동일하게 적용됩니다.

서브 에이전트를 언제 사용하고 언제 사용하지 말아야 하는가

서브 에이전트는 기본값이 아니라 도구입니다. 언제 서브 에이전트를 건너뛰어야 할지 알면 설정을 빠르고 저렴하게 유지할 수 있습니다.

작업이 경계가 명확하고, 독립적이며, 노이즈가 많을 때 서브 에이전트를 사용하세요. 코드 리뷰는 경계가 명확하고(명확한 끝이 있음), 독립적이며(메인 스레드의 실행 상태가 필요하지 않음), 노이즈가 많습니다(메인 컨텍스트를 막히게 하고 싶지 않은 많은 중간 읽기 작업을 생성). 테스트 스위트 작성, 버그 재현 또는 보안 문제에 대한 모듈 감사도 마찬가지입니다. 이러한 작업은 완벽한 위임 대상입니다. 작업을 격리하고 판정을 받으세요.

작업이 작고, 밀접하게 연결되어 있거나, 주요 작업과 순차적일 때는 서브 에이전트를 건너뛰세요. 변수 이름 변경, 한 줄짜리 버그 수정, 또는 메인 에이전트가 이미 필요한 컨텍스트를 보고 있는 경우 등은 핸드오프의 이점을 얻지 못합니다. 그런 경우 서브 에이전트를 생성하는 것은 지연 시간과 컨텍스트 왕복만 추가할 뿐 얻는 것이 없습니다. 메인 에이전트가 서브 에이전트에게 대화의 절반을 설명해야 한다면, 메인 스레드에서 작업을 유지하세요.

일반적인 규칙은 다음과 같습니다. 한 단락으로 설명할 수 있을 만큼 독립적이고 병렬로 실행할 가치가 있는 작업을 위임하세요. 검토하고 테스트할 새로운 엔드포인트는 적합합니다. 오타 수정은 그렇지 않습니다. 많은 동시 서브 에이전트로 확장할 때 동적 워크플로우의 오케스트레이션 패턴이 주도하지만, 동일한 판단이 적용됩니다. 독립적인 작업은 병렬 처리하고, 연결된 작업은 함께 유지하세요.

흔한 실수

모호한 설명. description이 레이블에 불과하면 예상대로 자동 위임이 작동하지 않습니다. 사용 트리거로 작성하세요.
하나의 비대한 서브 에이전트. 모든 작업을 하나의 서브 에이전트에 몰아넣으면 전문화의 이점을 없앱니다. 책임별로 분할하세요.
기본적으로 모든 도구 상속. tools를 설정하지 않으면 서브 에이전트가 메인 에이전트가 가진 모든 것을 갖게 됩니다. 신뢰할 수 있는 작업에는 괜찮지만, 자동화된 작업에는 위험합니다. 의도적으로 허용 목록을 작성하세요.
검증 서브 에이전트 없음. 테스트 게이트가 없는 검토-빌드 설정은 겉보기에 괜찮아 보이는 코드를 배포하지만, 예외 상황에서 고장납니다. 항상 실제로 테스트를 실행하는 서브 에이전트를 포함하세요.
서브 에이전트를 SDK처럼 다루기. 서브 에이전트는 모델에 의해 파견되며 세션 내에서 작동합니다. 확정적이고 예약된 제어 흐름이 필요하다면, 그것은 에이전트 SDK의 역할이지, 서브 에이전트 무더기의 역할이 아닙니다.

이러한 점들을 올바르게 적용하면, 몇 개의 잘 정의된 서브 에이전트가 Claude Code를 하나의 바쁜 비서에서 작고 집중된 팀으로 변화시킵니다. Anthropic의 효과적인 에이전트 구축은 더 큰 관점에서 다음과 같이 말합니다. 모델 중심의 구조가 더 큰 프롬프트보다 낫습니다.

자주 묻는 질문

Claude Code 서브 에이전트란 무엇인가요? 메인 Claude Code 에이전트가 작업을 위임하는 별도의 에이전트 인스턴스입니다. 각 서브 에이전트는 자체 컨텍스트 창, 사용자 지정 시스템 프롬프트 및 구성 가능한 도구 세트를 가집니다. 집중된 작업을 수행하고 결과를 반환하여 메인 대화를 깔끔하게 유지하고 전문가를 병렬로 실행할 수 있도록 합니다.

Claude Code 서브 에이전트는 어떻게 만드나요? `.claude/agents/` (프로젝트) 또는 `~/.claude/agents/` (개인)에 마크다운 파일을 만드세요. `name`, `description`, 선택적 `tools`, 선택적 `model`을 포함하는 YAML 프런트매터를 추가한 다음, 본문에 시스템 프롬프트를 작성하세요. 설명은 Claude에게 언제 자동으로 위임해야 하는지 알려줍니다.

Claude는 어떤 서브 에이전트를 사용할지 어떻게 결정하나요? 사용 가능한 각 서브 에이전트의 description 필드를 읽고, 작업이 일치할 때 자동으로 위임합니다. “code-reviewer 서브 에이전트를 사용하세요.”처럼 이름으로 명시적으로 호출할 수도 있습니다. 명확한 트리거 방식의 설명은 자동 위임을 신뢰할 수 있게 만듭니다.

서브 에이전트와 Claude 에이전트 SDK의 차이점은 무엇인가요? 서브 에이전트는 세션 내에서 모델에 의해 파견됩니다. Claude Code에서 작업하면서 전문가를 불러들이는 방식입니다. 에이전트 SDK는 확정적이거나 무인 실행을 위해 코드 내에서 제어 흐름을 작성하는 프로그래밍 방식입니다. 대화형 전문화에는 서브 에이전트를, 예약된 루프에는 SDK를 사용하세요.

서브 에이전트는 병렬로 실행될 수 있나요? 네, 그렇습니다. 메인 에이전트는 독립적인 작업을 위해 여러 서브 에이전트를 동시에 파견할 수 있으므로, 검토, 테스트 및 문서화가 순차적으로가 아니라 동시에 이루어집니다. 대규모 확장을 위해 Claude Code의 동적 워크플로우는 이를 하나의 세션에서 많은 병렬 서브 에이전트로 확장합니다.

서브 에이전트가 API 테스트에 어떻게 도움이 되나요? OpenAPI 사양에 대해 API 테스트를 작성하고 실행하는 서브 에이전트를 정의하세요. 이것은 엔드포인트가 단순히 완성된 것처럼 보이는지 여부가 아니라 실제로 작동하는지 여부를 확인하는 검증 게이트가 됩니다. Apidog와 같은 플랫폼에 연결하면 피드백이 스키마를 인식하게 되어 모든 응답이 계약에 따라 유효성 검사를 받습니다.

핵심 요약

Claude Code 서브 에이전트는 하나의 컨텍스트 창이 모든 것을 담을 수 없다는 문제를 해결합니다. 각 작업에 자체 컨텍스트, 지침 및 도구를 부여함으로써, 단일 과부하된 에이전트 대신 병렬로 작업하고 깔끔하게 보고하는 소규모 전문가 팀을 얻을 수 있습니다. 설정은 마크다운 파일로 간단하며, 그 보상은 집중력, 속도, 그리고 적절한 작업에 적절한 모델을 투입할 수 있는 능력입니다.

두 가지로 시작하세요. 검토자와 테스터입니다. Claude가 스스로 위임하도록 명확한 설명을 작성하고, 각 에이전트에게 필요한 도구만 부여하며, 테스터를 API 스위트에 연결하여 실제 검증 게이트로 만드세요. 엔드포인트와 관련된 모든 것에 대해 Apidog는 해당 게이트에 검사할 스키마를 제공합니다. 다운로드하여 테스트 서브 에이전트가 여러분의 코드가 작동함을 증명하게 한 후에 diff를 읽으세요.