# 서브에이전트 관리 (/ko/docs/verdent-for-vscode/agents-rules/subagent-management)
> Verdent에서 서브에이전트 이해 및 관리
서브에이전트는 자체 커스텀 시스템 프롬프트, 별도 컨텍스트 창, 격리된 실행 환경으로 동작하는 전문 AI 에이전트입니다. 메인 대화 컨텍스트를 오염시키지 않고 메인 에이전트가 위임한 특정 작업을 처리합니다.
**주요 특징:**
* **격리된 컨텍스트 창:** 각 서브에이전트는 별도의 컨텍스트 창을 유지합니다. 메인 에이전트의 컨텍스트 공간을 차지하는 것은 서브에이전트가 반환한 최종 결과뿐이며, 중간 처리 과정은 포함되지 않습니다.
* **커스텀 시스템 프롬프트:** 모든 서브에이전트에는 동작, 성격, 작업 해석 방식을 정의하는 전용 시스템 프롬프트가 있습니다.
* **자동 작업 위임:** 메인 에이전트는 적절한 작업 유형이 감지되면 자동 도구 선택과 비슷한 방식으로 서브에이전트를 자동 호출합니다.
* **수동 호출:** 사용자는 @-멘션(`@Verifier`, `@Explorer`, `@Code-reviewer`)으로 서브에이전트를 명시적으로 지정할 수 있습니다.
**두 가지 범주:**
* **기본 서브에이전트:** 내장형(Verifier, Explorer, Code-reviewer) - 즉시 사용할 수 있으며 미리 구성되어 있습니다
* **커스텀 서브에이전트:** 사용자가 생성하며 `~/.verdent/subagents/`에 저장됩니다 - 프로젝트별 요구에 맞게 조정됩니다
***
## 기본 서브에이전트 이해하기 [#기본-서브에이전트-이해하기]
Verdent for VS Code에는 미리 구성되어 있고 즉시 사용할 수 있으며 별도 설정이나 구성이 필요 없는 세 가지 내장 기본 서브에이전트가 포함되어 있습니다.
**전문 영역:** 빠른 코드 확인 및 검증
**기능:**
* 코드 로직 검증
* 문법 정확성 확인
* 요구사항 대비 구현 검증
**사용법:**
코딩 작업 중 참조합니다:
```
@Verifier check this authentication logic
```
**가장 적합한 경우:** 전체 코드 리뷰의 부담 없이 빠르게 검증할 때
**전문 영역:** 빠른 코드베이스 탐색 및 내비게이션
**기능:**
* 패턴이나 이름으로 파일 찾기
* 키워드/함수로 코드 검색
* 아키텍처 관련 질문에 답변
* 기능이 구현된 위치 식별
**사용법:**
코드베이스 관련 질문이 있거나 명시적으로 요청하면 자동 호출됩니다:
```
@Explorer find all API endpoints
```
**가장 적합한 경우:**
* 익숙하지 않은 코드베이스 이해
* 특정 구현 위치 찾기
* 아키텍처 분석
**성능:** 토큰 효율이 높으며, 복잡한 검색을 위해 여러 인스턴스를 병렬로 실행할 수 있습니다
**전문 영역:** 코드 품질 평가
**기능:**
* 새 코드와 수정된 코드를 선제적으로 스캔해 보안 취약점 확인
* 유지보수성 문제 식별
* 성능 문제 감지
**사용법:**
품질 확인을 위해 참조합니다:
```
@Code-reviewer review this authentication flow
```
**가장 적합한 경우:**
* 커밋 전 리뷰
* 통합 전에 문제 식별
* 코드 품질 기준 준수 보장
***
### 자동 호출과 수동 호출 [#자동-호출과-수동-호출]
**자동 선택 트리거:**
메인 에이전트는 작업 패턴 인식을 기반으로 서브에이전트를 자동 선택합니다:
**Explorer 서브에이전트:**
* 코드베이스 구조에 관한 질문("아키텍처가 어떻게 되어 있나요?", "X는 어디에 구현되어 있나요?")
* 파일 검색 요청("...하는 모든 파일을 찾아줘", "...와 관련된 컴포넌트를 보여줘")
* 코드 내비게이션 질의("인증은 어떻게 동작하나요?", "이 함수를 호출하는 곳은 어디인가요?")
**Code-reviewer 서브에이전트:**
* 보안 리뷰 요청("보안 취약점을 리뷰해줘", "SQL injection 위험을 확인해줘")
* 코드 품질 평가 프롬프트("코드 품질을 분석해줘", "유지보수성 문제를 찾아줘")
* 커밋 전 리뷰 시나리오(코드 변경사항이 제시될 때 암시적으로)
**Verifier 서브에이전트:**
* 검증 요청("이 로직을 검증해줘", "이 구현이 올바른지 확인해줘")
* 문법 및 정확성 확인("이 코드가 동작하나요?", "인증 플로를 검증해줘")
**수동 지정:**
사용자는 @-멘션으로 자동 라우팅을 재정의할 수 있습니다:
```
@Explorer find all authentication-related files
@Code-reviewer review the security of login flow
@Verifier check validation logic in middleware
```
**Add Subagent 버튼:**
Input Box에서 **Add Subagent** 버튼을 선택하면 다음을 수행할 수 있습니다:
* 사용 가능한 서브에이전트(기본 및 커스텀) 중에서 선택
* 선택한 서브에이전트에 작업을 명시적으로 위임
* 자동 라우팅 결정을 재정의
**수동 지정의 이점:**
* **정밀성:** 정확한 서브에이전트가 작업을 처리하도록 보장
* **재정의:** 여러 서브에이전트가 적용될 수 있을 때 특정 서브에이전트 선택
* **테스트:** 커스텀 서브에이전트 동작을 명시적으로 검증
* **일관성:** 동일한 서브에이전트로 작업을 반복해 일관된 결과 확보
커스텀 서브에이전트는 서브에이전트 시스템 프롬프트 호출 정책에 정의된 "When to use" 지침에 따라 자동 호출될 수 있습니다. 트리거 패턴 구성에 관한 자세한 내용은 현재 개발 중입니다.
***
## 커스텀 서브에이전트 만들기 [#커스텀-서브에이전트-만들기]
커스텀 서브에이전트를 사용하면 프로젝트별 요구, 도메인 전문성, 팀 워크플로에 맞춘 전문 에이전트를 만들 수 있습니다.
### 생성 방법 [#생성-방법]
**초보자에게 권장**
1. **Settings** → **Subagents**를 선택합니다
2. "Create new subagent"를 선택합니다
3. 서브에이전트 이름, 설명, 시스템 프롬프트를 정의합니다
4. 호출 정책과 사용 지침을 구성합니다
5. `~/.verdent/subagents/` 디렉터리에 저장합니다
이 방법은 검증과 유용한 프롬프트가 포함된 안내형 인터페이스로 서브에이전트를 만들 수 있게 해줍니다.
**고급 사용자에게 권장**
1. `~/.verdent/subagents/`로 이동합니다
2. Markdown 파일을 만듭니다(예: `security-reviewer.md`)
3. `name`와 `description`가 포함된 YAML frontmatter를 추가합니다
4. 동작을 정의하는 시스템 프롬프트를 작성합니다
5. 호출 정책과 "When to use" 지침을 지정합니다
이 방법은 파일 구조에 익숙한 사용자에게 더 많은 제어권을 제공하며 더 빠릅니다.
커스텀 서브에이전트를 \~/.verdent/subagents/에 저장하면 프로젝트 간에 공유할 수 있습니다. 모든 워크스페이스에서 사용할 수 있습니다.
***
### 파일 구조 [#파일-구조]
커스텀 서브에이전트 파일은 YAML frontmatter가 포함된 Markdown 형식을 사용합니다:
```markdown
---
name: subagent-name
description: Brief description of specialization
---
# System Prompt
[Behavior definition, personality, interpretation style]
Invocation policy (strict): Only run if explicitly requested.
When to use:
- Specific scenario 1
- Specific scenario 2
When NOT to use:
- Avoid scenario 1
- Avoid scenario 2
```
**YAML frontmatter(필수):**
* `name`: @-멘션에서 사용하는 서브에이전트 식별자
* `description`: 서브에이전트 목적에 대한 한 줄 설명
**시스템 프롬프트 섹션:**
서브에이전트 동작을 정의하는 Markdown 콘텐츠:
* 성격과 톤
* 작업 해석 방식
* 출력 형식 선호사항
* 의사결정 원칙
**호출 정책(필수):**
```
Invocation policy (strict|flexible): Policy description
```
* **strict:** 사용자가 명시적으로 요청할 때만 호출
* **flexible:** 작업 패턴에 따라 자동 호출 허용
**사용 지침:**
```
When to use the [name] agent:
- Bullet list of scenarios for invocation
When NOT to use:
- Bullet list of scenarios to avoid
```
***
### 커스텀 서브에이전트 예시 [#커스텀-서브에이전트-예시]
```markdown
---
name: api-documenter
description: Generates comprehensive API documentation from code
---
# System Prompt
You are an API documentation specialist.
Documentation approach:
- Extract endpoints, parameters, and responses from code
- Generate OpenAPI/Swagger specifications
- Include usage examples and error codes
- Document authentication requirements
Output format:
- Markdown tables for endpoints
- Code examples in multiple languages
- Authentication flow diagrams
Invocation policy (strict): Only run when explicitly requested.
When to use:
- User requests API documentation generation
- Need to document REST/GraphQL endpoints
- Creating developer guides
When NOT to use:
- Inline code comments
- User-facing documentation
```
**사용 사례:** 라우트 핸들러, 컨트롤러, 스키마 정의를 분석해 포괄적인 API 문서를 자동 생성합니다.
```markdown
---
name: migration-reviewer
description: Reviews database migrations for safety and correctness
---
# System Prompt
You are a database migration safety specialist.
Review checklist:
- Check for destructive operations (DROP, DELETE without WHERE)
- Verify reversible migrations (up/down compatibility)
- Identify potential data loss scenarios
- Validate index creation strategies
- Check for blocking operations on large tables
Risk assessment:
- Categorize migrations: low/medium/high risk
- Recommend staging environment testing for high-risk changes
- Suggest rollback procedures
Invocation policy (strict): Only run when explicitly requested.
When to use:
- User creates or modifies migration files
- Pre-deployment migration review
- Investigating migration failures
When NOT to use:
- Schema design from scratch
- Query optimization
```
**사용 사례:** 배포 전에 위험한 데이터베이스 작업을 식별해 프로덕션 사고를 예방합니다.
```markdown
---
name: a11y-auditor
description: Audits frontend code for accessibility compliance
---
# System Prompt
You are an accessibility compliance specialist (WCAG 2.1 Level AA).
Audit criteria:
- Semantic HTML structure
- ARIA labels and roles
- Keyboard navigation support
- Color contrast ratios
- Screen reader compatibility
- Focus management
Report format:
- Issues categorized by severity (critical/major/minor)
- WCAG guideline references
- Code examples showing fixes
- Testing recommendations
Invocation policy (flexible): May auto-invoke for UI component reviews.
When to use:
- User creates/modifies UI components
- Pre-deployment accessibility checks
- Compliance audits
When NOT to use:
- Backend API code
- Build configuration files
```
**사용 사례:** 배포 전에 웹 애플리케이션이 접근성 표준을 충족하도록 보장합니다.
***
### 커스텀 서브에이전트의 일반적인 사용 사례 [#커스텀-서브에이전트의-일반적인-사용-사례]
**도메인별 전문성**
* **재무 계산:** 세무 준수, 금융 규제에 특화된 서브에이전트
* **의료 HIPAA 준수:** 환자 데이터 처리 표준에 맞춰 코드 리뷰
* **암호화:** 보안 구현을 모범 사례에 비추어 분석
전문 지식 요구사항과 규제 제약이 있는 산업에 적합합니다.
**팀별 워크플로**
* **코드 스타일 강제 적용:** linter 규칙을 넘어 팀별 코딩 표준 확인
* **문서 일관성:** 문서가 팀 템플릿과 톤을 따르도록 보장
* **의존성 감사:** 승인된 목록을 기준으로 서드파티 패키지 사용 모니터링
팀 규칙을 적용하고 협업 프로젝트 전반의 일관성을 유지합니다.
**기술 스택 전문가**
* **React 성능 최적화 도구:** 불필요한 재렌더링과 메모이제이션 기회 식별
* **SQL 쿼리 최적화 도구:** 데이터베이스 쿼리 성능 분석 및 개선
* **Docker 구성 리뷰어:** 컨테이너화 모범 사례 검증
특정 프레임워크, 언어, 인프라 기술에 대한 깊은 전문성을 제공합니다.
**품질 보증**
* **테스트 커버리지 분석기:** 테스트되지 않은 코드 경로를 식별하고 테스트 시나리오 제안
* **오류 처리 리뷰어:** 포괄적인 예외 처리를 보장
* **로깅 표준 강제 적용:** 디버깅과 모니터링을 위한 로깅 관행 검증
코드 신뢰성과 유지보수성 기준을 유지하기 위한 자동화된 품질 확인입니다.
**컴플라이언스 및 보안**
* **GDPR 준수 검사기:** 개인정보 보호 요구사항에 맞춰 데이터 처리 리뷰
* **보안 취약점 스캐너:** 프레임워크별 문제에 특화된 감지
* **라이선스 준수 감사자:** 의존성의 라이선스 호환성 확인
배포 전에 법적, 보안, 라이선스 요구사항 준수를 보장합니다.
**프로젝트별 요구**
* **레거시 코드 현대화 도구:** 오래된 패턴을 식별하고 현대적인 대안 제안
* **마이그레이션 어시스턴트:** 프레임워크 또는 언어 버전 업그레이드 안내
* **성능 예산 강제 적용:** 번들 크기와 로드 시간을 임계값과 비교해 모니터링
고유한 프로젝트 과제와 기술 부채 관리에 맞춘 커스텀 솔루션입니다.
***
## 서브에이전트 동작 구성(AGENTS.md 패턴) [#서브에이전트-동작-구성agentsmd-패턴]
AGENTS.md는 주로 프로젝트 규칙 파일 역할을 하지만([규칙 시스템](/docs/verdent-for-vscode/agents-rules/rule-systems) 참고), 프로젝트별 서브에이전트 동작도 정의할 수 있습니다.
### 시스템 프롬프트 설계 원칙 [#시스템-프롬프트-설계-원칙]
**구체적이고 지시적으로 작성:**
일반적인 지침보다 정확한 동작 기대치를 정의합니다.
시스템 프롬프트는 구체적이고 지시적으로 작성하세요. '가능하면 최적화해봐'보다 '최적화하기 전에 프로파일링해'가 더 좋습니다.
**좋은 예:**
```markdown
Analysis approach:
- Profile before optimizing
- Focus on algorithmic improvements
- Provide before/after benchmarks
```
**피할 예:**
```markdown
Try to optimize code when possible
```
**성격과 톤 설정:**
특정 목적에 최적화된 구별되는 "페르소나"를 만듭니다:
```markdown
You are a performance optimization specialist.
```
**의사결정 원칙 정의:**
서브에이전트가 트레이드오프에 접근하는 방식을 안내합니다:
```markdown
When suggesting optimizations:
1. Measure first, optimize second
2. Prioritize readability over micro-optimizations
3. Only suggest changes with >10% performance improvement
```
**출력 형식 지정:**
결과가 표시되는 방식을 제어합니다:
```markdown
Output format:
- Markdown tables for endpoints
- Code examples in multiple languages
- Authentication flow diagrams
```
***
### 호출 정책 구성 [#호출-정책-구성]
**Strict 정책:**
```markdown
Invocation policy (strict): Only run when explicitly requested.
```
다음 경우에 사용합니다:
* 서브에이전트가 민감한 작업을 처리할 때(보안 리뷰, 데이터베이스 마이그레이션)
* 사용자가 호출 여부를 의식적으로 결정해야 할 때
* 자동 호출이 방해가 될 수 있을 때
**Flexible 정책:**
```markdown
Invocation policy (flexible): May auto-invoke based on task patterns.
```
다음 경우에 사용합니다:
* 서브에이전트가 방해 없이 유용한 컨텍스트를 제공할 때
* 자동 호출이 워크플로 효율을 높일 때
* 작업 패턴을 명확히 식별할 수 있을 때
**사용 지침 모범 사례:**
**"When to use" 섹션:**
* 트리거 시나리오를 구체적으로 작성합니다
* 해당 서브에이전트를 호출해야 하는 예시 프롬프트를 포함합니다
* 서브에이전트 전문 영역과 맞는 작업 특성을 설명합니다
**"When NOT to use" 섹션:**
* 부적절한 호출을 막기 위해 제외 항목을 명시적으로 나열합니다
* 관련 서브에이전트와의 경계를 명확히 합니다
* 범위가 불필요하게 확장되는 것을 방지합니다
***
## 작업 라우팅 및 디스패치 [#작업-라우팅-및-디스패치]
Verdent의 멀티 서브에이전트 시스템은 전문 에이전트 간 자동 라우팅과 조율을 통해 병렬 작업 실행을 지원합니다.
### 아키텍처 구성 요소 [#아키텍처-구성-요소]
**메인 에이전트(오케스트레이터):**
기본 에이전트는 사용자 요청을 분석하고 복잡한 작업을 분해한 뒤, 전문 작업을 적절한 서브에이전트에 위임합니다. 대화 컨텍스트를 유지하고 서브에이전트 결과를 조율합니다.
**서브에이전트 풀:**
자동 또는 수동으로 호출할 수 있는 사용 가능한 서브에이전트(기본 및 커스텀)의 모음입니다. 각 서브에이전트는 격리된 컨텍스트로 독립적으로 동작합니다.
**자동 작업 라우팅:**
메인 에이전트가 서브에이전트 전문 영역과 일치하는 작업 패턴을 감지하면 자동으로 작업을 디스패치합니다:
* 코드베이스 탐색 질문 → Explorer 서브에이전트
* 보안 리뷰 요청 → Code-reviewer 서브에이전트
* 검증 확인 → Verifier 서브에이전트
**병렬 실행:**
복잡한 작업에서는 여러 서브에이전트를 동시에 실행할 수 있습니다. 예: Explorer 서브에이전트가 코드베이스를 검색하는 동안 Code-reviewer가 동시에 보안을 분석해 더 빠르게 결과를 제공합니다.
병렬 서브에이전트 실행은 복잡한 작업을 가속합니다. Explorer가 검색하는 동안 Code-reviewer가 동시에 분석할 수 있습니다.
**결과 통합:**
서브에이전트 출력은 메인 에이전트로 반환되며, 메인 에이전트가 결과를 종합해 사용자에게 통합된 응답을 제공합니다.
서브에이전트 실행 스케줄링, 우선순위, 최대 동시 실행 제한, 오류 처리, 리소스 할당에 관한 자세한 정보는 현재 개발 중입니다. 구체적인 아키텍처 질문은 지원팀에 문의하세요.
***
## 서브에이전트 모니터링 [#서브에이전트-모니터링]
Verdent가 서브에이전트 작업과 결과를 표시하는 Chat View에서 서브에이전트 사용량과 성능을 추적할 수 있습니다.
### 모니터링 방법 [#모니터링-방법]
**Chat View 표시기:**
* 서브에이전트 호출이 대화 기록에 나타납니다
* 서브에이전트가 실행 중일 때 진행 표시기가 표시됩니다
* 결과에는 어떤 서브에이전트가 출력을 제공했는지 명시됩니다
**서브에이전트 출력 섹션:**
다음을 위한 전용 표시 영역입니다:
* 서브에이전트 작업 실행 결과
* 병렬 작업의 진행 표시기
* 작업 완료 시 통합 요약
**응답 출처 표시:**
Verdent는 응답에서 발견 사항을 특정 서브에이전트에 귀속해, 어떤 에이전트가 어떤 분석이나 검색을 수행했는지 명확하게 보여줍니다.
### 가시성과 투명성 [#가시성과-투명성]
**작업 투명성:**
Verdent는 다음을 표시합니다:
* 호출된 서브에이전트
* 호출이 자동이었는지 수동이었는지
* 작업 위임 이유
* 서브에이전트 실행 상태
**수동 지정 확인:**
@-멘션을 사용하면 Verdent가 지정한 서브에이전트가 작업을 처리하고 있음을 확인해, 사용자의 라우팅 선호가 반영되도록 보장합니다.
상세 실행 로그, 성능 지표(실행 시간, 토큰 사용량), 과거 호출 추적, 활동 가시성 설정, 사용량 분석 대시보드를 포함한 향상된 모니터링 기능은 현재 개발 중입니다.
***
## 함께 보기 [#함께-보기]
사용자 규칙, 프로젝트 규칙, 플랜 규칙을 통해 Verdent 동작을 구성합니다
사용 가능한 도구와 기능에 대한 전체 레퍼런스