# 확장성 및 사용자 지정 (/ko/docs/verdent-for-vscode/advanced-features/extensibility)

> 사용자 지정 서브에이전트, 규칙, MCP 연동으로 Verdent의 기능을 확장합니다



### 배울 내용 [#배울-내용]

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

***

## 확장성 개요 [#확장성-개요]

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

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

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

***

## 방법 1: 사용자 지정 서브에이전트 [#방법-1-사용자-지정-서브에이전트]

### 개요 [#개요]

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

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

### 사용자 지정 서브에이전트 생성 [#사용자-지정-서브에이전트-생성]

**파일 구조:**

```markdown
---
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: 설정 메뉴**

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

**방법 2: 직접 파일 생성**

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

### 사용자 지정 서브에이전트 사용 사례 [#사용자-지정-서브에이전트-사용-사례]

**도메인별 전문성:**

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

**팀별 워크플로:**

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

**기술 스택 전문가:**

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

**품질 보증:**

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

### 예시: API 문서 생성기 [#예시-api-문서-생성기]

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

### 예시: 데이터베이스 마이그레이션 리뷰어 [#예시-데이터베이스-마이그레이션-리뷰어]

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

### 호출 정책 [#호출-정책]

**엄격한 정책:**

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

**유연한 정책:**

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

***

## 방법 2: 규칙 시스템 [#방법-2-규칙-시스템]

### 개요 [#개요-1]

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

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

### 규칙 우선순위 [#규칙-우선순위]

충돌이 발생하면:

1. **AGENTS.md**(가장 높음) - 프로젝트 규칙이 사용자 선호를 덮어씁니다
2. **VERDENT.md**(중간) - 프로젝트 충돌이 없을 때 적용됩니다
3. **기본 동작**(가장 낮음) - 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(전역 선호) [#verdentmd전역-선호]

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

**예시:**

```markdown
# 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(프로젝트 규칙) [#agentsmd프로젝트-규칙]

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

**예시:**

```markdown
# 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_rulesmd플랜-사용자-지정]

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

**예시:**

```markdown
# 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 연동 [#방법-3-mcp-연동]

### 개요 [#개요-2]

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

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

### MCP 기능 [#mcp-기능]

**외부 시스템 접근:**

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

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

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

### MCP vs. 사용자 지정 서브에이전트 vs. 규칙 [#mcp-vs-사용자-지정-서브에이전트-vs-규칙]

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

### 예시: 세 가지 방법 모두 결합 [#예시-세-가지-방법-모두-결합]

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

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

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

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

```markdown
## 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
```

***

## 확장성 모범 사례 [#확장성-모범-사례]

### 단순하게 시작하고 점진적으로 확장 [#단순하게-시작하고-점진적으로-확장]

**단계적 도입:**

1. **1단계:** 기본 규칙(VERDENT.md 또는 AGENTS.md)부터 시작합니다
2. **2단계:** 반복되는 전문 작업에 사용자 지정 서브에이전트를 추가합니다
3. **3단계:** 외부 시스템 연결을 위해 MCP을 연동합니다

### 방법을 전략적으로 결합 [#방법을-전략적으로-결합]

**시너지 예시:**

**규칙 + 서브에이전트:**

* AGENTS.md가 사용자 지정 서브에이전트를 호출할 시점을 지정합니다
* 규칙으로 서브에이전트 권장사항을 따르도록 합니다

**규칙 + MCP:**

* AGENTS.md가 사용 승인된 MCP 서버를 정의합니다
* 규칙이 외부 데이터 접근이 필요한 시점을 지정합니다

**서브에이전트 + MCP:**

* 사용자 지정 서브에이전트가 MCP 도구를 사용해 외부 시스템에 접근합니다
* 서브에이전트가 전문성을 바탕으로 MCP 결과를 해석합니다

### 사용자 지정 내용 문서화 [#사용자-지정-내용-문서화]

**팀 문서:**
사용자 지정 서브에이전트와 프로젝트 규칙(AGENTS.md)의 경우:

* 명확하지 않은 규칙이나 서브에이전트의 근거를 문서화합니다
* 올바른 사용 예시를 제공합니다
* 문제 해결 가이드를 포함합니다
* 코드와 함께 버전 관리합니다

**개인 문서:**
VERDENT.md와 개인 서브에이전트의 경우:

* 복잡한 규칙에는 이유를 주석으로 남깁니다
* 규칙을 정리된 상태로 최신화합니다
* 오래된 규칙은 즉시 제거합니다

### 철저히 테스트 [#철저히-테스트]

**검증 절차:**

1. 사용자 지정 항목(서브에이전트/규칙/MCP 구성)을 생성합니다
2. 새 대화를 시작해 테스트합니다
3. 동작이 기대와 일치하는지 확인합니다
4. 결과를 바탕으로 다듬습니다
5. 성공적인 패턴을 문서화합니다

**일반적인 테스트 시나리오:**

* 예상한 시점에 서브에이전트가 자동 호출되나요?
* 프로젝트 규칙이 사용자 규칙을 올바르게 덮어쓰나요?
* MCP 서버가 연결되고 작업을 실행하나요?
* 결합된 방법들이 충돌 없이 상호작용하나요?

***

## 확장성 문제 해결 [#확장성-문제-해결]

### 사용자 지정 서브에이전트 문제 [#사용자-지정-서브에이전트-문제]

**서브에이전트가 호출되지 않음:**

* 호출 정책을 확인합니다(엄격 모드는 명시적 @-mention이 필요함)
* "When to use" 지침이 요청과 일치하는지 확인합니다
* 파일이 `~/.verdent/subagents/` 디렉터리에 있는지 확인합니다
* YAML frontmatter 문법을 확인합니다

**예상치 못한 서브에이전트 동작:**

* 시스템 프롬프트가 명확한지 검토합니다
* "When to use"와 "When NOT to use" 지침을 다듬습니다
* 명시적 @-mention으로 테스트해 동작을 분리합니다
* 결과를 바탕으로 시스템 프롬프트를 반복 개선합니다

### 규칙 충돌 [#규칙-충돌]

**규칙이 적용되지 않음:**

* 규칙 우선순위를 확인합니다(AGENTS.md > VERDENT.md)
* 파일이 올바른 위치에 있는지 확인합니다
* 새 대화를 시작해 새로 적용되는지 테스트합니다
* 규칙을 더 구체적이고 지시적으로 만듭니다

**예상치 못한 동작:**

* 같은 파일 안에 서로 모순되는 규칙이 있는지 확인합니다
* 규칙이 너무 모호하지 않은지 확인합니다
* 올바른 규칙 파일을 편집 중인지 확인합니다
* 명시적인 표현을 사용합니다("Always", "Never", "Prefer")

### MCP 연동 문제 [#mcp-연동-문제]

**연결 실패:**

* `mcp.json` 문법을 확인합니다
* 인증 자격 증명을 확인합니다
* MCP 서버가 실행 중이고 접근 가능한지 확인합니다
* 네트워크 연결을 검증합니다

**도구 호출 문제:**

* MCP 서버가 예상 도구를 노출하는지 확인합니다
* 도구 매개변수 형식을 확인합니다
* 오류가 있는지 MCP 서버 로그를 검토합니다
* MCP 서버를 독립적으로 테스트합니다

***

## 함께 보기 [#함께-보기]

<CardGroup cols="2">
  <Card title="서브에이전트 관리" icon="users" href="/docs/verdent-for-vscode/agents-rules/subagent-management">
    자세한 서브에이전트 생성 가이드
  </Card>

  <Card title="규칙 시스템" icon="book" href="/docs/verdent-for-vscode/agents-rules/rule-systems">
    전체 규칙 문서
  </Card>

  <Card title="MCP 연동" icon="plug" href="/docs/verdent-for-vscode/advanced-features/mcp">
    MCP 설정 및 구성
  </Card>

  <Card title="도구 참조" icon="wrench" href="/docs/verdent-for-vscode/advanced-features/tool-reference">
    기본 제공 도구 기능
  </Card>
</CardGroup>