---
title: 擴充性與自訂
description: 透過自訂子代理、規則與 MCP 整合來擴展 Verdent 的能力
---



### 你將學到什麼

如何使用三種強大的擴充方法來自訂與擴展 Verdent for VS Code：自訂子代理、規則系統以及 MCP 整合。

---

## 擴充性總覽

Verdent for VS Code 提供三種主要方法來擴展其能力並自訂行為：

1. **自訂子代理** - 為特定領域任務建立專業化 AI 代理
2. **規則系統** - 透過 VERDENT.md、AGENTS.md 與 plan_rules.md 引導行為
3. **MCP 整合** - 透過 Model Context Protocol 連接外部工具與服務

每種方法滿足不同的自訂需求，並可組合運用以全面優化工作流程。

---

## 方法一：自訂子代理

### 總覽

自訂子代理是具備專屬系統提示詞、調用策略與任務專業知識的專業化 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. 設定 → Subagents
2. 「建立新子代理」
3. 定義名稱、描述、系統提示詞
4. 設定調用策略
5. 儲存至 `~/.verdent/subagents/`

**方法二：直接建立檔案**
1. 前往 `~/.verdent/subagents/`
2. 建立 markdown 檔案（例如 `security-reviewer.md`）
3. 加入 YAML frontmatter
4. 撰寫系統提示詞與使用指南

### 自訂子代理的使用情境

**特定領域專業知識：**
- **財務計算：** 稅務合規、金融法規
- **醫療 HIPAA 合規：** 病患資料處理標準
- **密碼學：** 安全實作最佳實務

**團隊專屬工作流程：**
- **程式碼風格執行者：** 超越 linter 規則的團隊程式碼標準
- **文件一致性：** 確保文件遵循團隊範本
- **相依套件稽核者：** 對照核可清單監控第三方套件

**技術堆疊專家：**
- **React 效能優化者：** 找出不必要的重新渲染
- **SQL 查詢優化者：** 分析並改善資料庫效能
- **Docker 設定審查者：** 驗證容器化實務

**品質保證：**
- **測試覆蓋率分析者：** 找出未測試的程式碼路徑
- **錯誤處理審查者：** 確保完善的例外處理
- **日誌標準執行者：** 驗證日誌實務

### 範例：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 明確要求時才執行
- 使用者完全掌控調用
- 最適合專業化、偶爾使用的子代理

**彈性策略：**
- 允許根據任務模式偵測自動調用
- 主代理會自動路由相符的任務
- 最適合常用、定義明確的子代理

---

## 方法二：規則系統

### 總覽

規則檔案是引導 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（全域偏好）

**目的：** 適用於所有專案的個人程式碼風格與偏好

**範例：**
```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
```

**存取方式：** 設定 → Rules → User Rules

### AGENTS.md（專案規則）

**目的：** 團隊共通的程式碼標準與專案專屬慣例

**範例：**
```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 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
```

**存取方式：** 設定 → Rules → Plan Rules

### 規則撰寫最佳實務

**具體且明確：**
```
✓ Good: "Always use async/await for asynchronous operations"
✗ Vague: "Try to use modern JavaScript"
```

**邏輯化組織：**
- 將相關規則歸類於章節標題下
- 分離不同關注點（風格、測試、文件、安全）
- 在各檔案間使用一致的結構

**優先排序關鍵規則：**
- 將重要規則放在每個章節的最前面
- 對不可妥協的標準加上強調：`**NEVER** commit credentials`
- 聚焦於錯誤預防與安全

**測試成效：**
- 開啟新對話以驗證規則套用
- 根據代理實際行為調整規則
- 隨專案演進更新規則

---

## 方法三：MCP 整合

### 總覽

Model Context Protocol（MCP）透過連接外部工具、資料來源與服務來擴展 Verdent。MCP 伺服器扮演 Verdent 與外部系統之間的橋樑。

**設定方式：** 透過 設定 → MCP Servers 設定 `~/.verdent/mcp.json`

### MCP 能力

**外部系統存取：**
- 資料庫查詢工具（PostgreSQL、MySQL、MongoDB）
- 雲端服務 API（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_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. **階段一：** 從基本規則開始（VERDENT.md 或 AGENTS.md）
2. **階段二：** 為重複的專業化任務加入自訂子代理
3. **階段三：** 整合 MCP 以連接外部系統

### 策略性地組合各方法

**綜效範例：**

**規則 + 子代理：**
- AGENTS.md 指定何時調用自訂子代理
- 規則確保子代理的建議獲得遵循

**規則 + MCP：**
- AGENTS.md 定義哪些 MCP 伺服器獲核可使用
- 規則指定何時需要外部資料存取

**子代理 + MCP：**
- 自訂子代理使用 MCP 工具存取外部系統
- 子代理以專業知識解讀 MCP 結果

### 為自訂內容撰寫文件

**團隊文件：**
針對自訂子代理與專案規則（AGENTS.md）：
- 記錄非顯而易見的規則或子代理的理由
- 提供正確用法範例
- 包含疑難排解指南
- 與程式碼一同納入版本控制

**個人文件：**
針對 VERDENT.md 與個人子代理：
- 為複雜規則加上說明理由的註解
- 保持規則井然有序並持續更新
- 及時移除過時的規則

### 徹底測試

**驗證流程：**
1. 建立自訂內容（子代理／規則／MCP 設定）
2. 開啟全新對話進行測試
3. 驗證行為是否符合預期
4. 根據結果調整
5. 記錄成功的模式

**常見測試情境：**
- 子代理是否在預期時自動調用？
- 專案規則是否正確覆蓋使用者規則？
- MCP 伺服器是否能連接並執行操作？
- 組合方法之間是否能互動而無衝突？

---

## 擴充性疑難排解

### 自訂子代理問題

**子代理未調用：**
- 檢查調用策略（嚴格策略需要明確的 @-mention）
- 確認「何時使用」指南與你的請求相符
- 確保檔案位於 `~/.verdent/subagents/` 目錄
- 檢查 YAML frontmatter 語法

**子代理行為異常：**
- 檢視系統提示詞是否清晰
- 調整「何時使用」與「何時不使用」指南
- 以明確的 @-mention 測試以隔離行為
- 根據結果反覆調整系統提示詞

### 規則衝突

**規則未套用：**
- 檢查規則優先順序（AGENTS.md > VERDENT.md）
- 確認檔案位於正確位置
- 開啟新對話以測試全新套用
- 讓規則更具體、更明確

**行為異常：**
- 查看同一檔案中是否有相互矛盾的規則
- 檢查規則是否過於模糊
- 確認正在編輯正確的規則檔案
- 使用明確的措辭（「總是」、「永不」、「優先」）

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