連携ワークフロー

このページで学べること

実際の開発シナリオに向けて、カスタムサブエージェント、ルール、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 がステージングでテスト → 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 Specification
MCP Server Registry - 利用可能な MCP サーバーを閲覧
Official MCP Servers - 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.so/servers にある公式の MCP サーバーレジストリには、利用可能なコミュニティサーバーが一覧表示されています。

チームコラボレーション

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

結果: セキュリティとデータベースのベストプラクティスが適用された、十分にレビュー済みのエンドポイント。

連携のベストプラクティス

段階的な導入

フェーズ 1: 基本的なルール

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

フェーズ 2: 専門的なサブエージェントを追加

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

フェーズ 3: MCP を統合

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

戦略的な組み合わせ

組み合わせ	目的	例
ルール + サブエージェント	ルールがタイミングを定義し、サブエージェントが分析する	AGENTS.md: 「@security-reviewer でレビューする」
ルール + MCP	ルールがどのサーバーかを指定し、MCP がアクセスする	AGENTS.md: 「db-staging のみを使用する」
サブエージェント + MCP	サブエージェントが外部データのために MCP を使用する	セキュリティ監査が API エンドポイントを照会する

チームドキュメントのベストプラクティス

チーム向けに連携をドキュメント化する際は、次の内容を含めます:

カスタムサブエージェント: 各サブエージェントの名前、目的、呼び出すタイミングを記載
AGENTS.md ルール: 各標準の「なぜ」を説明する根拠とともにルールを記載
MCP サーバー: 各サーバーの目的、アクセスレベル (読み取り専用 / 書き込み)、使用するタイミングを記載
連携ワークフロー: コンポーネントがどのように連携するかを示すワークフローの例を提供
トラブルシューティング: 自分のセットアップ固有のよくある問題とその解決策を記載

連携ドキュメントは .mcp.json や AGENTS.md ファイルと一緒にコミットしておくと、新しいチームメンバーがセットアップをすばやく理解できます。

トラブルシューティング

問題: 期待したタイミングでサブエージェントが呼び出されない

確認:

場所: ファイルが ~/.verdent/subagents/[name].md に存在するか

YAML フロントマター: 必須の name および description フィールドを含む有効な構文か

呼び出しポリシー: 使い方に一致しているか (strict は明示的な @メンションが必要)

説明: エージェントの description が、サブエージェントを使うべきタイミングを正確に記述しているか

再起動: Verdent を再起動してサブエージェント定義を再読み込みしてみる

よくある原因:

サブエージェントのファイル名や @メンションのタイプミス
フロントマターの YAML 構文が無効
サブエージェントの description がタスクのコンテキストに一致しない

問題: AGENTS.md のルールが適用されない

確認:

場所: ファイルがプロジェクトのルートディレクトリにあるか

構文: 解析エラーのない有効な Markdown か

指示の書き方: 具体的な命令を使う (「~~してみる」ではなく「常に~~を使う」)

セッション: 新しい会話を開始してルールの適用を新しい状態でテストする

競合: ユーザールールがプロジェクトルールを意図せず上書きしていないか確認する

よくある原因:

AGENTS.md が誤ったディレクトリにある (プロジェクトルートが必須)
AI が異なる解釈をしてしまう曖昧な指示
ルールは適用されているが結果が期待どおりでない (表現を調整する)

問題: MCP サーバーが起動または接続に失敗する

確認:

構文: .mcp.json が有効な JSON を含んでいるか (jq で検証)

構造: 必須の mcpServers キーがトップレベルに存在するか

サーバー設定: 各サーバーに command と args が正しく指定されているか

パッケージ: MCP サーバーパッケージにアクセスできるか (npx はパッケージを自動的にダウンロード、-y フラグで確認プロンプトをスキップ)

環境: env オブジェクト内の変数がシェルで正しく設定されているか

権限: サーバー実行可能ファイルに適切な実行権限があるか

よくある原因:

JSON のタイプミス (カンマ忘れ、括弧の閉じ忘れ)
args 配列のパッケージ名が誤っている
環境変数の欠落または誤り
ネットワーク / ファイアウォールが npx パッケージのインストールをブロック

デバッグ手順:

JSON を検証: cat .mcp.json | jq .
コマンドを手動でテスト: npx -y @modelcontextprotocol/server-postgres "postgresql://..."
環境を確認: echo $GITHUB_TOKEN
Verdent のログで具体的なエラーメッセージを確認

連携ワークフロー

このページで学べること

連携の方法

よくある連携パターン

データベース開発のワークフロー

セキュリティを考慮した API 開発

フロントエンドのアクセシビリティ

MCP の設定例

MCP を理解する

基本設定

マルチ環境

ワークスペース連携

プロジェクト固有の設定

チームコラボレーション

共有 AGENTS.md 標準

マルチエージェントの連携

複雑な機能のワークフロー

連携のベストプラクティス

段階的な導入

戦略的な組み合わせ

チームドキュメントのベストプラクティス

トラブルシューティング

関連項目

拡張機能ガイド

MCP 連携

On this page