확장성 및 사용자 지정

배울 내용

사용자 지정 서브에이전트, 규칙 시스템, MCP 연동이라는 세 가지 강력한 확장 방법으로 Verdent for VS Code을 사용자 지정하고 확장하는 방법을 알아봅니다.

확장성 개요

Verdent for VS Code은 기능을 확장하고 동작을 사용자 지정할 수 있는 세 가지 주요 방법을 제공합니다.

사용자 지정 서브에이전트 - 도메인별 작업을 위한 전문 AI 에이전트를 생성합니다
규칙 시스템 - VERDENT.md, AGENTS.md, plan_rules.md를 통해 동작을 안내합니다
MCP 연동 - Model Context Protocol을 통해 외부 도구와 서비스를 연결합니다

각 방법은 서로 다른 사용자 지정 요구를 해결하며, 종합적인 워크플로 최적화를 위해 함께 사용할 수 있습니다.

방법 1: 사용자 지정 서브에이전트

개요

사용자 지정 서브에이전트는 전용 시스템 프롬프트, 호출 정책, 작업별 전문성을 갖춘 전문 AI 에이전트입니다. 프로젝트별 기능으로 Verdent의 기본 서브에이전트(@Verifier, @Explorer, @Code-reviewer)를 확장합니다.

저장 위치: ~/.verdent/subagents/

사용자 지정 서브에이전트 생성

파일 구조:

---
name: subagent-name
description: One-line purpose description
---
# System Prompt

[Behavior definition, personality, task interpretation approach]

Invocation policy (strict|flexible): Policy description

When to use:
- Scenario 1
- Scenario 2

When NOT to use:
- Avoid scenario 1
- Avoid scenario 2

생성 방법:

방법 1: 설정 메뉴

Settings → Subagents
"Create new subagent"
이름, 설명, 시스템 프롬프트를 정의합니다
호출 정책을 구성합니다
~/.verdent/subagents/에 저장합니다

방법 2: 직접 파일 생성

~/.verdent/subagents/로 이동합니다
마크다운 파일을 생성합니다(예: security-reviewer.md)
YAML frontmatter를 추가합니다
시스템 프롬프트와 사용 지침을 작성합니다

사용자 지정 서브에이전트 사용 사례

도메인별 전문성:

재무 계산: 세무 준수, 금융 규정
의료 HIPAA 준수: 환자 데이터 처리 표준
암호화: 보안 구현 모범 사례

팀별 워크플로:

코드 스타일 적용: linter 규칙을 넘어서는 팀 코딩 표준
문서 일관성: 문서가 팀 템플릿을 따르도록 보장
의존성 감사: 승인된 목록을 기준으로 타사 패키지 모니터링

기술 스택 전문가:

React 성능 최적화: 불필요한 재렌더링 식별
SQL 쿼리 최적화: 데이터베이스 성능 분석 및 개선
Docker 구성 리뷰: 컨테이너화 방식 검증

품질 보증:

테스트 커버리지 분석: 테스트되지 않은 코드 경로 식별
오류 처리 리뷰: 포괄적인 예외 처리 보장
로깅 표준 적용: 로깅 관행 검증

예시: API 문서 생성기

---
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-documenter document the /api/users endpoints

예시: 데이터베이스 마이그레이션 리뷰어

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

호출 정책

엄격한 정책:

서브에이전트는 @-mention으로 명시적으로 요청할 때만 실행됩니다
사용자가 호출을 완전히 제어합니다
전문적이고 가끔 사용하는 서브에이전트에 가장 적합합니다

유연한 정책:

작업 패턴 감지에 따라 자동 호출을 허용합니다
메인 에이전트가 일치하는 작업을 자동으로 라우팅합니다
자주 사용하고 명확히 정의된 서브에이전트에 가장 적합합니다

방법 2: 규칙 시스템

개요

규칙 파일은 코드 변경 없이 Verdent의 동작, 출력 형식, 의사결정을 안내하는 Markdown 문서입니다. 세 가지 규칙 유형이 종합적인 사용자 지정을 제공합니다.

규칙 유형	범위	우선순위	저장 위치
VERDENT.md	모든 프로젝트 전역	중간	`~/.verdent/VERDENT.md`
AGENTS.md	프로젝트별(팀)	가장 높음	프로젝트 루트 디렉터리
plan_rules.md	Plan Mode 형식	독립적	`~/.verdent/plan_rules.md`

규칙 우선순위

충돌이 발생하면:

AGENTS.md(가장 높음) - 프로젝트 규칙이 사용자 선호를 덮어씁니다
VERDENT.md(중간) - 프로젝트 충돌이 없을 때 적용됩니다
기본 동작(가장 낮음) - Verdent의 기본 내장값

충돌 예시:

VERDENT.md: "Use 2-space indentation"
AGENTS.md: "Use 4-space indentation for this project"
→ Result: 4-space indentation (project rules win)

VERDENT.md(전역 선호)

목적: 모든 프로젝트에 적용되는 개인 코딩 스타일과 선호

예시:

# User Rules

## TypeScript Preferences
- Use strict mode in tsconfig.json
- Prefer interfaces over type aliases
- Include return types on all functions

## Code Organization
- One component per file
- Named exports instead of default exports
- Organize imports: external, internal, types

## Documentation
- TSDoc comments for public APIs
- Include @param and @returns tags

## Communication
- Provide explanations before showing code
- Highlight breaking changes explicitly

접근: Settings → Rules → User Rules

AGENTS.md(프로젝트 규칙)

목적: 팀 전체 코딩 표준과 프로젝트별 규칙

예시:

# AGENTS.md

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to navigate
- Run `pnpm install --filter <project_name>` for dependencies
- Check package.json name field for correct package name

## Testing instructions
- Run `pnpm turbo run test --filter <project_name>`
- From package root: `pnpm test`
- Focus on one test: `pnpm vitest run -t "<test name>"`
- Fix all errors before merge

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing

접근: 프로젝트 루트 디렉터리(버전 관리됨)

plan_rules.md(플랜 사용자 지정)

목적: Plan Mode 출력 형식과 상세 수준 제어

예시:

# Plan Rules

## Plan Structure
- Start with brief summary (2-3 sentences)
- Include estimated time for each major step
- List prerequisites before implementation steps
- Identify potential risks

## Level of Detail
- Break tasks into subtasks of 15-30 minutes
- Include specific file paths for modifications
- List functions/components to create/modify

## Format
- Use numbered lists for sequential steps
- Use bullet points for options
- Include code snippets for complex changes

접근: Settings → Rules → Plan Rules

규칙 작성 모범 사례

구체적이고 지시적으로 작성:

✓ Good: "Always use async/await for asynchronous operations"
✗ Vague: "Try to use modern JavaScript"

논리적으로 구성:

관련 규칙을 섹션 제목 아래에 묶습니다
관심사를 분리합니다(스타일, 테스트, 문서, 보안)
파일 전반에 일관된 구조를 사용합니다

중요 규칙 우선 배치:

각 섹션에서 중요한 규칙을 먼저 배치합니다
협상 불가능한 표준에는 강조를 사용합니다: **NEVER** commit credentials
버그 예방과 보안에 집중합니다

효과 검증:

새 대화를 시작해 규칙 적용을 확인합니다
실제 에이전트 동작을 바탕으로 규칙을 다듬습니다
프로젝트가 발전함에 따라 업데이트합니다

방법 3: MCP 연동

개요

Model Context Protocol(MCP)은 외부 도구, 데이터 소스, 서비스를 연결해 Verdent을 확장합니다. MCP 서버는 Verdent과 외부 시스템 사이의 브리지 역할을 합니다.

구성: Settings → MCP Servers를 통해 ~/.verdent/mcp.json

MCP 기능

외부 시스템 접근:

데이터베이스 쿼리 도구(PostgreSQL, MySQL, MongoDB)
클라우드 서비스 APIs(AWS, Azure, GCP)
프로젝트 관리(Jira, Linear, Asana)
CI/CD 파이프라인(Jenkins, GitHub Actions)
모니터링 서비스(Datadog, New Relic)

사용자 지정 도구 개발: 독점 시스템을 위한 MCP 서버를 생성합니다.

내부 API 연동
레거시 시스템 브리지
특수 데이터 소스
워크플로 자동화 도구

MCP vs. 사용자 지정 서브에이전트 vs. 규칙

필요	가장 적합한 방법	이유
전문 AI 분석	사용자 지정 서브에이전트	사용자 지정 컨텍스트를 활용한 AI 추론이 필요합니다
코딩 표준 적용	규칙(AGENTS.md)	간단한 동작 지침입니다
외부 데이터베이스 접근	MCP 연동	외부 시스템 연결이 필요합니다
개인 코딩 선호	규칙(VERDENT.md)	전역 동작 사용자 지정입니다
팀 규칙	규칙(AGENTS.md)	공유 프로젝트 표준입니다
API 연동	MCP 연동	외부 서비스 상호작용입니다
Plan 형식 사용자 지정	규칙(plan_rules.md)	Plan Mode 출력 제어입니다
도메인 전문성(재무, 의료)	사용자 지정 서브에이전트	전문 지식 적용입니다

예시: 세 가지 방법 모두 결합

시나리오: 엄격한 컴플라이언스 요구사항이 있는 풀스택 개발팀

사용자 지정 서브에이전트:

---
name: compliance-auditor
description: Audits code for regulatory compliance (SOC2, HIPAA)
---
[System prompt for compliance checking]

AGENTS.md(프로젝트 규칙):

## Security Standards
- All API endpoints must validate inputs
- Never log PII or credentials
- Encrypt sensitive data at rest and in transit

## Compliance
- Run @compliance-auditor before all PRs
- Document data retention policies in code comments
- Include audit trails for data access

MCP 연동:

컴플라이언스 데이터베이스 MCP 서버: 컴플라이언스 규칙에 맞춰 작업을 확인합니다
감사 로그 MCP 서버: 모든 민감 데이터 접근을 기록합니다

워크플로:

User: "Create endpoint for user profile updates"
Verdent: [Applies AGENTS.md rules]
         [Generates secure endpoint with validation]
         [Automatically invokes @compliance-auditor]
         [Uses MCP to log operation in audit system]
         Result: Compliant, secure, audited endpoint