서브에이전트 관리

서브에이전트는 자체 커스텀 시스템 프롬프트, 별도 컨텍스트 창, 격리된 실행 환경으로 동작하는 전문 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 버튼을 선택하면 다음을 수행할 수 있습니다:

• 사용 가능한 서브에이전트(기본 및 커스텀) 중에서 선택
• 선택한 서브에이전트에 작업을 명시적으로 위임
• 자동 라우팅 결정을 재정의

수동 지정의 이점:

• 정밀성: 정확한 서브에이전트가 작업을 처리하도록 보장
• 재정의: 여러 서브에이전트가 적용될 수 있을 때 특정 서브에이전트 선택
• 테스트: 커스텀 서브에이전트 동작을 명시적으로 검증
• 일관성: 동일한 서브에이전트로 작업을 반복해 일관된 결과 확보

커스텀 서브에이전트 만들기

커스텀 서브에이전트를 사용하면 프로젝트별 요구, 도메인 전문성, 팀 워크플로에 맞춘 전문 에이전트를 만들 수 있습니다.

생성 방법

파일 구조

커스텀 서브에이전트 파일은 YAML frontmatter가 포함된 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

커스텀 서브에이전트 예시

---
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

---
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

---
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

커스텀 서브에이전트의 일반적인 사용 사례

서브에이전트 동작 구성(AGENTS.md 패턴)

AGENTS.md는 주로 프로젝트 규칙 파일 역할을 하지만(규칙 시스템 참고), 프로젝트별 서브에이전트 동작도 정의할 수 있습니다.

시스템 프롬프트 설계 원칙

구체적이고 지시적으로 작성: 일반적인 지침보다 정확한 동작 기대치를 정의합니다.

좋은 예:

Analysis approach:
- Profile before optimizing
- Focus on algorithmic improvements
- Provide before/after benchmarks

피할 예:

Try to optimize code when possible

성격과 톤 설정: 특정 목적에 최적화된 구별되는 "페르소나"를 만듭니다:

You are a performance optimization specialist.

의사결정 원칙 정의: 서브에이전트가 트레이드오프에 접근하는 방식을 안내합니다:

When suggesting optimizations:
1. Measure first, optimize second
2. Prioritize readability over micro-optimizations
3. Only suggest changes with >10% performance improvement

출력 형식 지정: 결과가 표시되는 방식을 제어합니다:

Output format:
- Markdown tables for endpoints
- Code examples in multiple languages
- Authentication flow diagrams

호출 정책 구성

Strict 정책:

Invocation policy (strict): Only run when explicitly requested.

다음 경우에 사용합니다:

• 서브에이전트가 민감한 작업을 처리할 때(보안 리뷰, 데이터베이스 마이그레이션)
• 사용자가 호출 여부를 의식적으로 결정해야 할 때
• 자동 호출이 방해가 될 수 있을 때

Flexible 정책:

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가 동시에 보안을 분석해 더 빠르게 결과를 제공합니다.

결과 통합: 서브에이전트 출력은 메인 에이전트로 반환되며, 메인 에이전트가 결과를 종합해 사용자에게 통합된 응답을 제공합니다.

서브에이전트 모니터링

Verdent가 서브에이전트 작업과 결과를 표시하는 Chat View에서 서브에이전트 사용량과 성능을 추적할 수 있습니다.

모니터링 방법

Chat View 표시기:

• 서브에이전트 호출이 대화 기록에 나타납니다
• 서브에이전트가 실행 중일 때 진행 표시기가 표시됩니다
• 결과에는 어떤 서브에이전트가 출력을 제공했는지 명시됩니다

서브에이전트 출력 섹션: 다음을 위한 전용 표시 영역입니다:

• 서브에이전트 작업 실행 결과
• 병렬 작업의 진행 표시기
• 작업 완료 시 통합 요약

응답 출처 표시: Verdent는 응답에서 발견 사항을 특정 서브에이전트에 귀속해, 어떤 에이전트가 어떤 분석이나 검색을 수행했는지 명확하게 보여줍니다.

가시성과 투명성

작업 투명성: Verdent는 다음을 표시합니다:

• 호출된 서브에이전트
• 호출이 자동이었는지 수동이었는지
• 작업 위임 이유
• 서브에이전트 실행 상태

수동 지정 확인: @-멘션을 사용하면 Verdent가 지정한 서브에이전트가 작업을 처리하고 있음을 확인해, 사용자의 라우팅 선호가 반영되도록 보장합니다.

함께 보기