擴充性與自訂

你將學到什麼

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

擴充性總覽

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

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

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

方法一：自訂子代理

總覽

自訂子代理是具備專屬系統提示詞、調用策略與任務專業知識的專業化 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

建立方法：

方法一：設定選單

設定 → Subagents
「建立新子代理」
定義名稱、描述、系統提示詞
設定調用策略
儲存至 ~/.verdent/subagents/

方法二：直接建立檔案

前往 ~/.verdent/subagents/
建立 markdown 檔案（例如 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 明確要求時才執行
使用者完全掌控調用
最適合專業化、偶爾使用的子代理

彈性策略：

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

方法二：規則系統

總覽

規則檔案是引導 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

存取方式： 設定 → 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

存取方式： 設定 → 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 輸出控制
領域專業（財務、醫療）	自訂子代理	應用專業知識

範例：三種方法的組合

情境： 具備嚴格合規要求的全端開發團隊

自訂子代理：

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