하위 에이전트(종종 작성됨 하위 대리인 or 하위 에이전트)는 에이전트 개발자 툴링의 가장 명확한 실질적 발전 중 하나입니다. 이를 통해 전문화된 AI 보조원으로 구성된 소규모 팀을 구성할 수 있습니다. 클로드 코드각각 고유한 역할, 도구 및 컨텍스트 창을 갖습니다. 이 아이디어는 간단하지만 강력합니다. 하나의 범용 모델에 모든 작업을 맡기는 대신, 메인 오케스트레이터가 작업을 위임할 수 있는 간결하고 단일 목적의 에이전트를 정의하는 것입니다(자동으로 또는 명시적으로 요청할 경우). 이를 통해 복잡한 워크플로의 컨텍스트, 도구 및 비용/지연 시간 균형을 관리하는 방식이 달라집니다.
하위 대리인이란 무엇입니까?
간단한 정의. 서브에이전트는 클로드 코드가 작업을 위임할 수 있는 미리 구성된, 작업 특화 AI "인격"입니다. 각 서브에이전트는 자체 시스템 프롬프트, (격리된) 컨텍스트 창, 명시적으로 부여된 도구, 그리고 선택적으로 모델 선택 권한을 갖습니다. 서브에이전트는 프로젝트 또는 사용자 수준에서 생성될 수 있으며, 클로드가 자동으로 호출하거나 사용자가 명시적으로 호출할 수 있습니다.
하위 대리인의 주요 속성
- 특수 목적 및 시스템 프롬프트. 시스템 프롬프트에서 하위 에이전트의 역할, 제약 및 접근 방식을 설명하여 좁은 도메인에 대해 예측 가능하게 동작하도록 합니다(예: 코드 검토자, 디버거, 데이터 과학자).
- 격리된 컨텍스트 창. 각 하위 에이전트는 자체 대화 기록과 컨텍스트를 유지하여 메인 스레드의 컨텍스트가 저수준 세부 정보로 오염되는 것을 방지합니다. 이는 단일 대화의 컨텍스트를 고갈시키는 워크플로를 확장하는 데 핵심적인 역할을 합니다.
- 도구 범위 및 권한. 하위 에이전트가 사용할 수 있는 내부 도구 또는 외부 모델 컨텍스트 프로토콜(MCP) 도구를 허용하거나 제한할 수 있습니다. 이는 중요한 안전 및 거버넌스 기능입니다.
- 코드로 구성. 하위 에이전트는 YAML 프런트 매터(이름, 설명, 도구, 모델)가 포함된 Markdown 파일로 정의되며 프로젝트 수준에서 저장됩니다.
.claude/agents/) 또는 사용자 수준(~/.claude/agents/). 프로젝트 정의가 우선합니다.
자동 위임과 명시적 호출이란 무엇입니까?
클로드 코드는 자동적으로 귀하의 프롬프트 또는 하위 에이전트가 작업을 위임할 때 하위 에이전트에게 작업을 위임합니다. description 작업에 맞는지 확인하십시오. 또는 명시 적으로 에이전트 요청(예: > Use the code-reviewer subagent to check my recent changes). 만들어라 description 행동 지향적 ("Use PROACTIVELY", "MUST BE USED") 자동 위임을 촉진하기 위해 Claude Code에서 하위 에이전트를 사용하는 두 가지 상호 보완적인 방법이 있습니다.
- 자동 위임 — 클로드는 요청을 검토하고 매칭된 작업을 사전에 하위 에이전트에게 위임합니다.
- 명시적 호출 — 프롬프트/명령에서 하위 에이전트를 이름으로 호출합니다(예:
Use the code-reviewer subagent to check my changes).
두 접근 방식 모두 UX 및 엔지니어링 측면에서 서로 다른 장단점을 가지고 있습니다. 아래에서 각각을 자세히 살펴보겠습니다.
자동 위임
사용자에게 어떻게 보이는가. 고수준 명령(예: "이 새로운 라이브러리에 대한 보안 감사를 준비하세요")을 내리면 Claude는 하나 이상의 하위 에이전트가 적합한 것으로 감지합니다. description 구성의 필드입니다. 사전 예방적 사용을 위해 구성된 경우 하위 에이전트가 자동으로 전송되고 구조화된 출력으로 결과가 반환됩니다.
팀이 이를 사용하는 이유.
- 인지 부하가 낮아집니다. 모든 하위 에이전트 이름을 기억하거나 입력할 필요가 없습니다.
- 특정 작업은 항상 동일한 전문가가 처리해야 하는 공유 워크플로에 대한 온보딩을 더욱 원활하게 만듭니다.
주의사항
- 당신은 엔지니어링해야합니다
description그리고 시스템은 의도적으로 프롬프트를 표시하여 클로드가 올바른 하위 에이전트를 안정적으로 선택할 수 있도록 합니다. - 너무 과하게 위임하면 많은 하위 에이전트가 유사한 작업에 참여하게 되어 토큰 사용량과 노이즈가 증가할 수 있습니다. 설명은 보수적으로 작성하세요.
명시적 호출
사용자에게 어떻게 보이는가. 하위 에이전트를 명시적으로 호출합니다. > Use the test-runner subagent to run the project tests오케스트레이션은 결정적입니다. 클로드는 미리 구성된 권한과 프롬프트를 사용하여 명명된 하위 에이전트를 호출합니다.
팀이 이를 사용하는 이유.
- 완벽한 제어: 어떤 전문가가 실행할지 정확히 결정하므로 디버깅과 재현성이 간소화됩니다.
- CI 또는 자동화된 스크립트에서 비용과 도구 접근성에 대한 추론이 더 쉬워졌습니다.
주의사항
- 타이핑과 규율이 더 필요합니다. 개발자나 자동화는 올바른 하위 에이전트 이름을 알아야 합니다.
- 기회주의가 덜합니다. 주요 에이전트가 자동으로 좋은 하위 에이전트를 감지하는 편의성이 다소 떨어집니다.
하위 에이전트의 작동 방식 - 기술 개요
아래에서는 하위 에이전트를 만들고 사용할 때 어떤 일이 일어나는지 실용적이고 구현 지향적으로 살펴보겠습니다.
하위 에이전트 정의(코드로 구성)
하위 에이전트는 YAML 머리말이 포함된 마크다운 파일입니다. 주요 필드는 다음과 같습니다.
name— 고유한 소문자 ID(하이픈으로 연결됨)description— 자동 위임 매칭에 사용되는 자연어 설명tools— 허용되는 도구의 선택적 쉼표 목록(또는 모든 도구를 상속하려면 생략)model— 선택적 별칭 (sonnet,opus,haiku) 또는inherit주요 대화 모델을 사용하려면
간단한 예(개념적이며 문서에서 그대로 나온 것은 아님):
---
name: code-reviewer
description: Expert code reviewer. Proactively reviews code for quality, security, and maintainability.
tools: Read, Grep, Bash
model: inherit
---
You are a senior code reviewer. Focus on security, correctness, and maintainability.
이 파일은 다음 위치에 있습니다. .claude/agents/ (프로젝트 범위) 또는 ~/.claude/agents/ (사용자 범위). 프로젝트 파일이 우선적으로 적용되므로 하위 에이전트의 공유 및 버전 관리가 간편해집니다.
모델 선택 및 도구
- 모델 필드: 하위 에이전트에 대해 특정 모델 별칭을 선택하거나 기본 대화 모델을 상속하도록 할 수 있습니다. 이를 통해 비용/품질 균형을 맞출 수 있습니다. (예: 대용량 데이터 스캐닝 하위 에이전트에는 저렴한 모델을 사용하고 최종 합성에는 고품질 모델을 사용하는 방식)
- 도구 범위: 각 하위 에이전트에게 최소한의 도구 세트를 제공하면 폭발 반경을 줄이고 안전성에 대한 추론을 간소화할 수 있습니다. 도구에는 표준 Claude Code 기본 요소(Read, Grep, Bash, Edit 등)와 MCP에서 제공하는 통합 기능이 포함됩니다.
런타임 동작 및 컨텍스트 처리
클로드가 하위 에이전트에게 위임하면 해당 하위 에이전트는 다음을 받습니다.
- 시스템 프롬프트(YAML/Markdown 내용)
- 필요한 컨텍스트(자체 컨텍스트 창)만 있습니다.
- 구성에서 허용된 도구 접근입니다.
각 하위 에이전트가 격리된 컨텍스트를 유지하므로 장기 조사나 대용량 파일 분석 시 모든 것을 하나의 컨텍스트에 강제로 저장하지 않고도 여러 개의 작은 컨텍스트로 분해할 수 있습니다. 이는 신뢰성과 해석 가능성 측면에서 큰 이점입니다.
하위 에이전트를 위한 아키텍처 패턴
가장 일반적인 아키텍처는 다음과 같습니다. 오케 스트레이터 (주 에이전트)는 고수준 작업을 분해하고, 여러 하위 에이전트를 생성한 후, 그 결과를 합성하거나 검증합니다. 실제 환경에서는 두 가지 표준 패턴이 나타납니다.
1) 오케스트레이터 + 전문가
한 명의 에이전트( 오케 스트레이터)는 여러 하위 에이전트를 병렬 또는 직렬로 조정합니다. 오케스트레이터는 호출할 전문가를 결정하고, 출력을 집계하고, 일관성을 검증하고, 최종 통합을 수행합니다. 이는 일반적인 "관리자가 팀원에게 위임하는" 방식이며, 클로드 코드 자료의 많은 예시 및 권장 설계와 일치합니다. 이 방법의 장점은 병렬 처리, 더 명확한 관심사 분리, 그리고 더 쉬운 오류 억제(버그가 있는 하위 에이전트는 해당 범위에만 영향을 미침)입니다.
사용시기 : 독립적인 하위 문제가 있는 복잡한 작업(예: "테스트 생성", "정적 분석 실행", "모듈 다시 작성", 그런 다음 "종단 간 테스트 통합 및 실행")
장단점: 오케스트레이션 논리가 복잡해질 수 있으며, 왕복 횟수가 늘어나면 지연 시간이 약간 늘어날 수 있습니다.
2) 파이프라인/체인 전문가
여기서 하위 에이전트는 한 에이전트의 출력이 다음 에이전트의 입력이 되는 순서로 배열됩니다(예: 사양 → 스캐폴드 → 구현 → 테스트 → 최적화). 이는 본질적으로 에이전트로 표현된 함수 합성으로, 단계적 변환과 단계 간 데이터 흐름에 대한 엄격한 보장이 필요할 때 유용합니다. 선형 워크플로우에서는 개념적으로 더 간단하고, 때로는 디버깅하기도 더 쉽습니다.
사용시기 : 결정론적 다단계 변환(예: 설계 문서를 스캐폴드 코드로 변환한 다음, 테스트를 거쳐 최적화).
장단점: 광범위한 탐색(연구, 브레인스토밍)이 필요한 작업에는 자연스럽지 않으며, 끊어진 링크 하나만 있어도 파이프라인 전체가 중단될 수 있습니다.
하위 에이전트는 단순한 역할 기반 프롬프트와 무엇이 다릅니까?
1) 별도의 컨텍스트 창
각 하위 에이전트는 역할과 관련된 교환, 파일 및 메타데이터를 저장하는 자체 컨텍스트 버퍼를 갖습니다. 이를 통해 메인 세션의 컨텍스트가 노이즈가 많은 중간 메시지로 인해 오염되는 것을 방지할 수 있으며, 각 기능에 대한 히스토리를 보존하거나 제한할 수 있습니다. Claude Code를 사용하면 토큰 비용이나 모든 것을 하나의 프롬프트에 담는 인지적 오버헤드 없이 특수 작업에 대한 장기적이고 신호가 높은 컨텍스트를 유지할 수 있습니다.
2) 시스템 프롬프트 및 페르소나
서브에이전트는 역할, 톤, 제약 조건을 정의하는 시스템 수준의 명령어(예: "리팩토링 전문가로만 동작하고, 셸 명령은 실행하지 마십시오" 또는 "Pytest 스타일로 단위 테스트를 생성하고, 공개 인터페이스만 사용하십시오")를 통해 생성됩니다. 이러한 명령어는 서브에이전트의 작업 설명처럼 작동하며, 클로드 코드 런타임에 의해 런타임에 적용됩니다.
3) 도구 바인딩 및 권한 범위
중요한 실질적인 차이점은 하위 에이전트가 파일 시스템, 프로세스 실행, 외부 API 또는 권한이 부여된 데이터 세트 등 특정 도구에 대한 접근 권한을 부여하거나 거부할 수 있다는 것입니다. 이는 하위 에이전트를 다음과 같은 용도로 강력하게 만듭니다. 최소 권한 설계: 문서 생성기는 임의 명령 실행을 차단할 수 있지만, CI 하위 에이전트에는 격리된 샌드박스가 부여됩니다. 많은 커뮤니티 게시물에서는 하위 에이전트를 모델 컨텍스트 프로토콜(MCP) 또는 후크 기반 MCP 서버와 연결하여 비밀 및 I/O에 대한 보안 액세스를 관리할 것을 권장합니다.
4) 모델 선택 및 비용 대비 성능 균형
서브에이전트는 모듈식이므로 작업 복잡성에 따라 다양한 기본 모델을 할당할 수 있습니다. 심층 추론에는 고성능 Sonnet 모델을 사용하고, 빠르고 반복적인 작업에는 가벼운 Haiku 모델을 사용하세요. 이러한 이기종 배포는 지연 시간, 토큰 비용, 그리고 성능 간의 균형을 맞추는 데 도움이 됩니다. Anthropic의 제품 업데이트와 커뮤니티 게시글은 비용 효율적인 확장을 위해 소규모 모델의 병렬 배포를 강조합니다.
5) 의사소통 패턴
하위 에이전트는 구조화된 메시지나 파일을 통해 오케스트레이터(또는 다른 에이전트)와 통신합니다. 일반적인 패턴은 다음과 같습니다.
- 구조화된 JSON 페이로드 반환(프로그래밍 오케스트레이션에 권장됨)
- 공유 작업 공간의 범위가 지정된 파일에 쓰기
- 또는 신뢰 점수와 근거를 포함한 최종 포맷된 메시지를 오케스트레이터에게 다시 보냅니다.
커뮤니티 실험 결과, 팀은 모호성을 피하기 위해 명시적이고 기계가 읽을 수 있는 핸드오프를 선호하는 것으로 나타났습니다.
성능 이점
하위 에이전트는 단순히 디자인이 깔끔한 것이 아니라, 올바르게 사용하면 실용적인 성능과 품질적 이점을 제공합니다.
1) 병렬화를 통한 벽시계 시간 단축
오케스트레이터는 여러 워커를 동시에 디스패치함으로써(예: 저장소 폴더당, 마이크로서비스당 또는 데이터 청크당 하나의 워커) 대규모 복합 작업을 완료하는 데 필요한 경과 시간을 단축합니다. 버그 보고서 분류, 여러 모듈에 대한 문서 생성, 여러 서비스 감사와 같은 사용 사례에 적합합니다. 워크로드가 실제로 병렬화될 수 있는 경우 개발자 워크플로의 속도가 크게 향상됩니다.
각 역할에 고유한 맥락을 부여함으로써 불필요한 과거 잡음으로 인한 즉각적인 과대 광고를 방지하고 환각 위험을 줄일 수 있습니다. 즉, 맥락 관련 실패가 줄어들고 전문화된 작업에 대한 출력의 일관성이 향상됩니다. 커뮤니티 보고서와 Anthropic의 자체 연구에 따르면 다중 에이전트 구성은 너비 우선 작업에서 단일 에이전트보다 성능이 뛰어난 경우가 많습니다. Anthropic의 한 내부 평가에서는 리드 에이전트 + 서브 에이전트 아키텍처를 사용하는 연구 스타일 작업에서 극적인 개선이 보고되었습니다.
주의: 병렬 처리는 하위 작업이 서로 독립적일 때 가장 큰 효과를 발휘합니다. 작업자가 끊임없이 서로를 기다리거나 무거운 상태 데이터를 공유해야 하는 경우, 효과가 점점 줄어듭니다.
2) 더 나은 컨텍스트 활용 및 토큰 낭비 감소
모든 중간 검색 결과를 단일 글로벌 컨텍스트에 채우는 대신, 워커는 관련 있는 결과만 자체 창에 저장하고 정제된 출력을 반환합니다. 이를 통해 오케스트레이터의 토큰 소비를 줄이고 컨텍스트 제한에 도달할 위험을 줄일 수 있습니다. 대규모 코드베이스, 긴 로그 또는 대용량 문서 저장소를 사용할 때 실질적인 이점이 있습니다. SDK의 압축/요약 기능은 장기 실행 에이전트의 유효 메모리를 더욱 확장합니다.
3) 전문가 프롬프트의 정확도 향상
좁은 범위의 전문가로 구성된 하위 에이전트는 보안 검사, 코드 스타일 또는 규정 준수 추출과 같은 해당 분야의 정밀성을 최적화하도록 시스템 프롬프트 및 툴셋을 통해 조정할 수 있습니다. 좁은 범위의 프롬프트는 에이전트의 허용 가능한 작업 공간과 예상 출력이 제한되어 있기 때문에 환각 현상을 줄이는 경향이 있습니다. 조직은 모든 작업을 전문가에게 맡기는 대신 해당 분야별 하위 에이전트를 사용할 때 자동화된 코드 검토와 같은 작업에서 더 높은 품질의 출력을 보고합니다.
팀이 실제로 하위 에이전트를 사용하는 방법 - 예시 워크플로
아래에 이를 덜 추상적으로 만들어 줄 구체적인 예를 들어보겠습니다.
예시 A - 리팩토링 파이프라인(오케스트레이터 + 전문가)
- 오케스트레이터는 "구성 요소 X 리팩토링" 요청을 받습니다.
- 오케스트레이터 호출
analysis-subagent(쓰기 권한 없음) 복잡성 핫스팟과 위험한 종속성을 식별합니다. - 오케스트레이터 호출
refactor-subagent(브랜치와 유사한 샌드박스에 권한을 작성하여) 리팩토링된 파일을 생성합니다. - 오케스트레이터 호출
test-gen-subagent(코드에 대한 읽기 전용) 단위 테스트를 생성합니다. - Orchestrator는 CI를 실행합니다.
ci-runner-subagent(샌드박스 실행) 및 인간 검토를 위한 결과 집계.
이 패턴은 각 단계를 분리하고, 위험을 포함하고, 감사 추적을 깔끔하게 유지합니다.
예시 B - 연구 + 프로토타입(파이프라인)
literature-subagent참조 내용을 스크랩하고 요약합니다(파일 쓰기 없음, 규제된 웹 접근).prototype-subagent요약에서 최소한의 PoC를 스캐폴딩합니다.benchmark-subagent샌드박스에서 마이크로벤치마크를 실행하고 결과를 보고합니다.
이러한 체인은 책임을 명확하게 유지하는 동시에 연구 업무의 순차적 성격을 강화합니다.
모범 사례 및 패턴
디자인 및 구성
- 작고 좁은 역할부터 시작하세요. 각 하위 에이전트가 하나의 명확한 업무에 책임을 지도록 하세요. 책임이 좁아지면 디버깅이 훨씬 수월해집니다.
- 버전 제어
.claude/agents/폴더에 있습니다. 하위 에이전트 정의를 코드처럼 검토, 테스트, 고정 버전으로 처리하세요. 이렇게 하면 편차가 줄어들고 감사가 수월해집니다. - 도구와 모델을 의도적으로 고정합니다.
model: inherit주요 대화와 일관된 동작을 원할 경우, 백그라운드 스캔에 대해 비용이 낮은 모델 별칭을 지정하세요. 공격 표면을 최소화하기 위해 도구를 잠그세요.
운영 패턴
- 결정적 자동화를 위해 명시적 호출을 사용하세요. CI 작업이나 후크를 실행하는 경우 예측 가능한 결과를 보장하려면 특정 하위 에이전트를 호출하세요.
- 대화형 세션에서 자동 위임을 사용합니다. 탐색 작업의 경우 Claude가 마찰을 줄이기 위해 하위 에이전트를 선택하도록 합니다.
description필드는 자동화가 예기치 않게 실행되지 않도록 의도적으로 설계되었습니다. - 합성을 위한 구조화된 출력을 설계합니다. 하위 에이전트가 오케스트레이터가 읽을 수 있는 파일에 쓰거나 JSON을 생성하도록 강제합니다. 이렇게 하면 축소 단계와 감사가 간소화됩니다.
테스트, 모니터링 및 거버넌스
- 대표적인 평가를 작성합니다. 하위 에이전트가 실패하는 부분을 추적하고 해당 실패 모드를 적용하는 테스트를 구축합니다. Anthropic은 대표적인 테스트 세트와 반복적인 개선을 권장합니다.
- 토큰과 도구 사용을 모니터링합니다. 각 하위 에이전트의 사용을 계측하고 폭주 비용이나 속도 제한 조건을 감지하기 위한 알림을 추가합니다.
하위 에이전트를 사용하지 않는 경우
하위 에이전트는 강력하지만 항상 올바른 도구는 아닙니다.
- 간단한 작업: 짧고 일회성 프롬프트나 사소한 변환의 경우 하위 에이전트는 불필요한 복잡성을 더합니다.
- 엄격한 지연 시간 제약: 오케스트레이션 왕복은 오버헤드를 증가시킵니다. 단일 턴, 매우 낮은 지연 시간 응답이 필요한 경우 모놀리식 접근 방식이 더 간단할 수 있습니다.
- 인프라가 부족한 소규모 팀: 비밀, 관찰 가능성, 샌드박스를 위한 도구가 없다면 서브에이전트는 운영상의 위험을 증가시킬 수 있습니다. 커뮤니티 게시물에서는 소규모로 시작하여 모듈화가 필요할 때 서브에이전트를 추가하는 것을 강조합니다.
클로드 코드 cli를 사용하는 것이 가장 권장되는 곳입니다.
CometAPI가 이제 강력한 Claude Code CLI를 완벽하게 지원한다는 소식을 전해드리게 되어 기쁩니다. Claude Code에서 Comet API 모델을 사용하려면 Claude Code를 설치하고 얻은 Comet API 키와 기본 주소로 인증하기만 하면 됩니다.
CometAPI를 통해 클로드 코드를 사용해야 하는 이유는 무엇입니까?
인공지능의 주요 기능: 개발자를 위해 특별히 구축된 모델을 사용하여 코드를 쉽게 생성, 디버깅 및 최적화합니다.
- 유연한 모델 선택: 포괄적인 모델 범위를 통해 보다 원활하게 개발할 수 있습니다.
- 원활한 통합: API는 항상 사용 가능합니다. Claude Code를 기존 워크플로에 단 몇 분 만에 통합하세요.
- **CometAPI를 통해 Claude Code를 사용하면 더 많은 비용을 절감할 수 있습니다.**CometAPI에서 제공하는 Claude API는 공식 가격에서 20% 할인되어 있으며, 공식에서 최신 모델로 업데이트됩니다.
Claude Code cli를 사용할 준비가 되셨나요? API 가이드 자세한 지침은
AI에 대한 더 많은 팁, 가이드 및 뉴스를 알고 싶다면 저희를 팔로우하세요. VK, X 및 디스코드!
도 참조 CometAPI를 통해 Claude 코드를 설치하고 실행하는 방법은 무엇입니까?
결론 - 왜 지금 하위 대리인이 중요한가
서브에이전트는 팀에 에이전트 워크플로우의 가능성을 실현합니다. 역할, 권한, 컨텍스트, 비용 및 병렬화에 대해 명시적으로, 그리고 일급 객체로서 추론할 수 있도록 합니다. 서브에이전트를 현명하게 사용하면 개발자의 작업 속도를 높이고, 다단계 작업의 품질을 향상시키며, 더욱 예측 가능한 거버넌스를 구현할 수 있습니다. 하지만 이러한 서브에이전트는 프로덕션 소프트웨어와 마찬가지로 설계, 테스트 및 모니터링해야 하지만, 이러한 투자는 신속한 엔지니어링을 안정적인 엔지니어링 실무로 전환합니다.
