整合工作流程

你將學到什麼

結合自訂子代理、規則與 MCP 伺服器，因應真實開發情境的實用整合工作流程。

整合方法

方法	最適用於	設定
自訂子代理	AI 驅動的專門任務	`~/.verdent/subagents/*.md`
規則（AGENTS.md）	團隊標準與行為	專案根目錄 `AGENTS.md`
MCP 伺服器	符合協定的外部工具	`.mcp.json`（專案根目錄）

理念： 結合多種方法，打造符合你需求的完整工作流程。

常見整合模式

資料庫開發工作流程

技術組合： Migration Reviewer 子代理 + AGENTS.md 標準 + PostgreSQL MCP 伺服器

子代理：

---
name: migration-reviewer
description: Reviews database migrations for safety
---
Checks: Destructive operations, reversibility, indexing, blocking operations

AGENTS.md：

## Database Standards
- All migrations reviewed by @migration-reviewer
- Test on staging before production
- Include rollback procedures

MCP： PostgreSQL 伺服器，用於執行查詢、檢查結構描述、驗證遷移

工作流程： 撰寫遷移 → @migration-reviewer 驗證 → MCP 在 staging 環境測試 → PR 文件

帶安全性的 API 開發

技術組合： Security Auditor + AGENTS.md 規則 + 自訂 API 測試工具

組成元件：

子代理： @api-security-auditor - 輸入驗證、SQL 注入、認證、速率限制
規則： 所有端點都需要安全性審查、公開 API 需有速率限制
外部工具： 透過自訂整合進行自動化端點測試與安全性掃描

結果： 在 PR 核准前自動進行安全性審查。

API 測試與安全性掃描工具可透過自訂 MCP 伺服器實作或其他整合方法進行整合，視你的工具鏈而定。

前端無障礙性

技術組合： Accessibility Auditor + WCAG 規則 + Lighthouse 整合

工作流程：

Create component → @a11y-auditor reviews → Lighthouse tests accessibility → Rules enforce >90 score

Lighthouse 及其他無障礙性工具可透過自訂 MCP 伺服器或 CI/CD 管線整合，視你的工作流程而定。

MCP 設定範例

認識 MCP

Model Context Protocol（MCP） 是一種開放協定，標準化應用程式向 LLM 提供上下文的方式。MCP 伺服器是實作該協定的可執行檔。它們不是資料庫連線或 API 端點，而是執行並透過 JSON-RPC 2.0 通訊的程式。

關鍵概念：

MCP 伺服器：實作 MCP 協定的可執行檔（Node.js 套件、Python 指令稿等）
設定：告訴 Verdent 如何啟動伺服器（command + args）
通訊：伺服器自行處理其業務邏輯（查詢、API 呼叫等）

基本設定

位置： 專案根目錄下的 .mcp.json

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/myapp_dev"
      ]
    }
  }
}

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/myapp_dev"
      ]
    },
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

說明：

mcpServers - MCP 設定所需的最上層鍵
command - 要執行的可執行檔（Node.js 套件通常為 npx）
args - 傳遞給指令的引數（套件名稱、連線字串等）
env - 用於認證／設定的環境變數

多環境

{
  "mcpServers": {
    "postgres-dev": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${DEV_DATABASE_URL}"
      ]
    },
    "postgres-staging": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${STAGING_DATABASE_URL}"
      ]
    },
    "postgres-prod": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${PROD_DATABASE_URL}"
      ]
    }
  }
}

最佳實務： 使用環境變數存放連線字串，以確保憑證安全。MCP 伺服器會依其實作在內部處理唯讀行為。存取控制選項請參閱各伺服器的特定文件。

深入了解 MCP：

Model Context Protocol 規格
MCP 伺服器登錄 - 瀏覽可用的 MCP 伺服器
官方 MCP 伺服器 - PostgreSQL、GitHub、Filesystem 等

工作區整合

專案專屬設定

設定步驟：

儲存在專案根目錄：.mcp.json
提交至版本控制以供團隊共用
團隊成員自動使用專案的 MCP 伺服器

微服務範例：

{
  "mcpServers": {
    "users-db": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/users"
      ]
    },
    "orders-db": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5433/orders"
      ]
    }
  }
}

對於 Kafka 等其他服務，你會需要相容的 MCP 伺服器實作。官方 MCP 伺服器登錄 mcp.so/servers 列出了可用的社群伺服器。

團隊協作

共用的 AGENTS.md 標準

提交至版本控制以達成全團隊一致性：

# AGENTS.md

## Code Review Process
- Run @code-reviewer before PR
- Address all security warnings
- Minimum 80% test coverage

## Integration Requirements
- @migration-reviewer for database changes
- @api-security-auditor for new endpoints
- @a11y-auditor for UI components

## MCP Servers
- Use postgres-staging MCP server for queries
- Never use postgres-prod MCP server for exploratory queries

好處： 一致的行為、強制執行的標準、自動化的品質關卡。

多代理協調

複雜功能工作流程

範例： 新的付款端點

1. Developer request → 2. Main agent generates code →
3. @api-security-auditor reviews security →
4. @migration-reviewer validates schema →
5. MCP tests on staging →
6. Main agent generates tests and PR

結果： 套用了安全性與資料庫最佳實務、經完整審查的端點。

整合最佳實務

漸進式採用

第一階段： 基本規則

## Code Standards
- Use TypeScript strict mode
- Run tests before commit

第二階段： 加入專門子代理

## Code Review
- Run @security-reviewer before PR

第三階段： 整合 MCP

## Database Access
- Use MCP postgres-staging for queries

策略性組合

組合	用途	範例
規則 + 子代理	規則定義何時，子代理分析	AGENTS.md：「以 @security-reviewer 審查」
規則 + MCP	規則指定哪些伺服器，MCP 存取	AGENTS.md：「只使用 db-staging」
子代理 + MCP	子代理使用 MCP 取得外部資料	Security auditor 查詢 API 端點

團隊文件最佳實務

為團隊撰寫整合文件時，應包含：

自訂子代理：列出每個子代理的名稱、用途，以及何時呼叫它
AGENTS.md 規則：記錄規則並附上理由，說明每項標準背後的「為什麼」
MCP 伺服器：描述每個伺服器的用途、存取層級（唯讀／可寫），以及何時使用
整合工作流程：提供範例工作流程，展示各元件如何協同運作
疑難排解：記錄你特定設定中的常見問題及其解決方案

將整合文件與你的 .mcp.json 及 AGENTS.md 檔案一起提交，讓新團隊成員能快速理解你的設定。

疑難排解

問題： 子代理未在預期時呼叫

檢查：

位置：檔案存在於 ~/.verdent/subagents/[name].md

YAML Frontmatter：語法有效，且包含必要的 name 與 description 欄位

呼叫政策：與使用方式相符（strict 需要明確的 @ 提及）

描述：代理的 description 準確描述了應於何時使用該子代理

重新啟動：嘗試重新啟動 Verdent 以重新載入子代理定義

常見原因：

子代理檔案名稱或 @ 提及有錯字
frontmatter 中的 YAML 語法無效
子代理的 description 與任務上下文不符

問題： AGENTS.md 規則未套用

檢查：

位置：檔案位於專案根目錄

語法：有效的 Markdown，沒有解析錯誤

指令風格：使用明確的命令（用「永遠使用…」而非「試著…」）

工作階段：開啟新對話以測試規則是否重新套用

衝突：檢查使用者規則是否無意間覆蓋了專案規則

常見原因：

AGENTS.md 放在錯誤的目錄（必須在專案根目錄）
模糊的指示讓 AI 有不同的解讀
規則已套用但結果不如預期（請調整措辭）

問題： MCP 伺服器無法啟動或連線

檢查：

語法：.mcp.json 含有效的 JSON（使用 jq 驗證）

結構：最上層存在必要的 mcpServers 鍵

伺服器設定：每個伺服器都正確指定了 command 與 args

套件：MCP 伺服器套件可存取（npx 會自動下載套件；-y 旗標可略過確認提示）

環境：env 物件中的變數已在你的 shell 中正確設定

權限：伺服器可執行檔具有適當的執行權限

常見原因：

JSON 中有錯字（缺少逗號、括號未閉合）
args 陣列中的套件名稱錯誤
缺少或不正確的環境變數
網路／防火牆阻擋了 npx 套件安裝

除錯步驟：

驗證 JSON：cat .mcp.json | jq .
手動測試指令：npx -y @modelcontextprotocol/server-postgres "postgresql://..."
檢查環境：echo $GITHUB_TOKEN
查看 Verdent 記錄以取得具體的錯誤訊息

另請參閱

擴充性指南

完整的擴充方法總覽

MCP 整合

Model Context Protocol 詳細資訊

View source

整合工作流程

擴充性指南

MCP 整合

On this page