AI Agent Architecture

日本語 (Japanese)

English

日本語 (Japanese)

English

Appearance

MCP/Skills アンチパターン集 ​

このドキュメントでは、MCP と Skills の設計・運用で陥りやすい失敗パターンと、その回避方法を整理する。

1. over-MCPization（MCPの過剰使用） ​

症状 ​

チーム内部の知識やガイドラインまでMCPサーバーとして実装してしまう。

問題のあるアプローチ ​

❌ チームのコーディング規約を取得するMCPサーバーを構築
❌ デザイン原則をAPIとして提供
❌ 社内ワークフローをMCPツール化

なぜ問題か ​

  • MCPサーバーの責務が肥大化
  • サーバー運用コストの増加
  • エージェント側でのカスタマイズが困難
  • 認証・デプロイの複雑化

正しいアプローチ ​

✅ チーム内部の知識 → Skill として定義
✅ 外部APIへのアクセス → MCP として実装

判断基準: 「これは外部サービスか、チームの知識か？」

2. over-Skillization（Skillsの過剰使用） ​

症状 ​

外部APIの呼び出しやリアルタイムデータ取得をSkillで説明しようとする。

問題のあるアプローチ ​

❌ Skill: "DeepLを使った翻訳の仕方"（API呼び出し手順を詳述）
❌ Skill: "RFC検索の方法"（検索APIの使い方を説明）
❌ Skill: "GitHubリポジトリ操作手順"

なぜ問題か ​

  • Skillが肥大化・複雑化
  • 外部システムの更新に追従困難
  • 認証情報の管理が曖昧に
  • エージェントが実行できない（参照のみ）

正しいアプローチ ​

✅ 外部API連携 → MCP として実装
✅ MCPの使い方・ガイドライン → Skill で補完

判断基準: 「動的な実行が必要か、静的な知識か？」

3. 曖昧なSkill定義 ​

症状 ​

Skillの内容が抽象的すぎて、エージェントが具体的なアクションを取れない。

問題のあるアプローチ ​

markdown
❌ # コードレビュー Skill

コードレビューは大切です。
良いコードを書きましょう。
バグがないか確認してください。

なぜ問題か ​

  • エージェントが判断基準を持てない
  • 実行結果が毎回異なる
  • 品質の担保ができない

正しいアプローチ ​

markdown
✅ # コードレビュー Skill

## チェック項目

1. ESLintエラーがゼロであること
2. SOLID原則に違反していないこと
3. テストカバレッジが80%以上であること

## 判断基準

| 条件              | アクション       |
| ----------------- | ---------------- |
| ESLintエラーあり  | 修正必須         |
| カバレッジ80%未満 | テスト追加を要求 |

対策: 数値基準、具体的な条件、明確なアクションを定義

4. MCPツール依存の過度な結合 ​

症状 ​

Skillが特定MCPの内部実装に強く依存している。

問題のあるアプローチ ​

markdown
❌ # 翻訳 Skill

deepl MCPのバージョン1.2.3の translate-text を使用。
パラメータ split_sentences は "nonewlines" を指定。
内部的にキャッシュが効くので2回目は速い。

なぜ問題か ​

  • MCPのバージョンアップで壊れる
  • 内部実装への依存は保守困難
  • 他のMCPに置き換えられない

正しいアプローチ ​

markdown
✅ # 翻訳 Skill

## 使用MCP

| MCP                          | 用途         |
| ---------------------------- | ------------ |
| deepl（または同等の翻訳MCP） | テキスト翻訳 |

## ワークフロー

1. 翻訳を実行（フォーマリティ: フォーマル）
2. 品質スコアを確認
3. 基準未満なら再翻訳

対策: MCPのインターフェースレベルで記述、実装詳細に依存しない

5. 単一責任の原則違反 ​

症状 ​

1つのSkillに複数の異なる責務を詰め込む。

問題のあるアプローチ ​

markdown
❌ # 開発 Skill

## コードレビュー

...

## デプロイ手順

...

## 障害対応

...

## 新人オンボーディング

...

なぜ問題か ​

  • 更新時の影響範囲が大きい
  • 必要な部分だけ参照できない
  • コンテキスト消費が無駄に増える

正しいアプローチ ​

✅ skills/
    ├── code-review/SKILL.md
    ├── deployment/SKILL.md
    ├── incident-response/SKILL.md
    └── onboarding/SKILL.md

対策: 1 Skill = 1 責務

6. 更新されないSkill ​

症状 ​

作成後に放置され、実際の運用と乖離したSkillが残り続ける。

問題のあるアプローチ ​

❌ 半年前に作成したSkillをそのまま使用
❌ チームの規約は変わったがSkillは更新していない
❌ 誰がオーナーか不明

なぜ問題か ​

  • エージェントが古い情報で動作
  • 誤った判断につながる
  • 信頼性の低下

正しいアプローチ ​

markdown
✅ ---
name: code-review
description: コードレビューガイドライン
owner: @frontend-team
last_reviewed: 2025-01-15

対策:

  • オーナーを明記
  • 定期的なレビューサイクルを設定
  • 最終確認日を記録

アンチパターン早見表 ​

ここまで紹介したアンチパターンを一覧表にまとめる。

パターン症状対策
over-MCPization内部知識をMCP化Skillに移行
over-Skillization外部APIをSkillで説明MCPに移行
曖昧なSkill抽象的すぎる数値・条件を明確化
過度な結合MCP内部実装に依存インターフェースレベルで記述
単一責任違反複数責務を1 SkillにSkillを分割
更新されない運用と乖離オーナー・レビューサイクル設定

関連ドキュメント ​

アンチパターンの理解を深めるための関連ドキュメントを以下に示す。

Released under the MIT License.

Copyright © 2025-2026 shuji-bonji