Claude Code Plugins × Atlassian MCPで実現する開発ガイドライン準拠チェックの仕組み化と全社展開

はじめに

こんにちは、ZOZOMO部FBZブロックの杉田です。普段はFulfillment by ZOZOが提供するAPIシステムを開発・運用しています。昨年からは、社内における開発者向けAI支援ツール（Claude、Devin、MCPなど）の導入・教育・推進・管理を担う専門チームでも兼務で活動しています。

本記事では、開発ガイドライン準拠チェックをClaude Code Plugins × Atlassian MCPで全社展開した取り組みを紹介します。手作業の確認コストを下げつつ、最新ガイドラインに基づいたレビューを日常的に回せるようにした経緯と、実装・運用のポイントをまとめます。

背景・課題

開発ガイドラインについて

ZOZOでは、サービス開発における「良い実装」「具体的な実装方法」「実装の目安」を明確にするため、開発ガイドラインをConfluence上で整備・管理しています。開発のガードレールとして機能し、品質の均一化と属人化の防止を目的としています。

執筆時点で、開発ガイドラインは以下のプラットフォーム・領域ごとに整備されています。

API
Backend
DB
ML
Infra
Frontend
iOS
Android
Q&A
Batch
Go
Java
Flutter
共通

各項目にはRFC2119に基づく要請レベル（MUST、RECOMMENDED、MAYなど）が設定され、「必ず従うべき項目」と「推奨事項」が明確に区別されています。また、開発ガイドラインの内容は定期的に見直され、継続的に更新されます。

開発ガイドラインの詳細については以下の記事で解説されていますので、あわせてご参照ください。

techblog.zozo.com

開発ガイドラインにまつわる課題

開発ガイドラインは整備されているものの、実際の運用では次の課題がありました。

人手による確認工数：プラットフォーム・領域ごとに数十の項目以上のチェックが必要で、レビューの負担が大きい
継続的なチェック体制の不在：リリース前の目視確認が中心で、更新内容の追従が難しい
チーム間のばらつき：観点の揺れが生まれ、統一した品質基準でのチェックが難しい

こうした課題を解消するため、開発ガイドライン準拠チェックを自動化・標準化する仕組みづくりに取り組みました。

Claude Code Pluginsとは

Claude Code Pluginsは、Claude Codeの機能をチームや組織内部で再利用しやすい形にまとめる拡張機構です。公式ドキュメントに沿って、AgentsやSkillsなどをプラグイン単位で管理・共有できます。

プラグインに含められる代表的な要素は以下の通りです。

構成要素	説明
Skills¹	Claude Codeの機能を拡張する指示セット
Agents	特定タスクに特化したサブエージェント
Hooks	ツール実行前後に介入するフック処理

さらに、プラグインごとに.mcp.jsonを配置することで、MCPサーバーと連携できます。外部サービス（Confluenceなど）の情報をプラグイン内から参照できる点が大きな特徴です。

プラグインは .claude-plugin/plugin.json を起点として定義され、Skillsは /plugin-name:skill-name のような名前空間付きで提供できます。そのため、開発者が複数のプラグインを導入しても衝突が発生しづらく、チームや組織内での再利用に適した形となります。

Claude Code Pluginsを採用した理由

当初は、開発ガイドラインの内容をGitHubリポジトリに保存して参照する方式を検討していました。具体的には、Confluence上で管理されている開発ガイドラインをMarkdown化し、任意のGitHubリポジトリ配下で管理し参照する方式です。しかし最終的に、Claude Code Plugins × Atlassian MCPの構成に方針を変更しました。

理由は以下の4点です。

1. 情報の鮮度を常に保てる

MCPを経由してConfluenceを直接参照することで、実行時点で常に最新の開発ガイドラインを参照できます。

2. 二重管理によるメンテナンスコストを避けられる

GitHubリポジトリ配下で管理する場合、Confluenceとの同期が必要になります。MCPで直接参照する方式により、二重管理を回避できました。

3. マーケットプレイス機能による全社配布の容易さ

Claude Code Pluginsのマーケットプレイス機能により、各プロダクトチームへの配布が容易になりました。共通のレビュー基準をコマンド1つで導入できます。

4. プラグインの自動更新による最新化の容易さ

Claude Code Pluginsはマーケットプレイスとインストール済みプラグインを起動時に自動更新する機能を備えています。また、/plugin marketplace update marketplace-nameコマンドで手動更新も可能です。これにより、プラグインの改善や機能追加を迅速に開発者に展開できます。

実施内容

開発ガイドラインの参照

Confluenceに格納されている開発ガイドラインを参照するため、Atlassian MCPを活用しました。Atlassian MCPはリモートMCPとして提供されています。ローカルにMCPサーバーを起動せずとも、Atlassianがホストするサーバーに直接接続してConfluenceやJiraのデータにアクセスできます。

プラグイン側で.mcp.jsonを以下のように設定し、読み取り専用モードでConfluenceにアクセスします。

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.atlassian.com/v1/mcp"
      ],
      "env": {
        "READ_ONLY_MODE": "true"
      }
    }
  }
}

ポイントは以下の通りです。

リモートMCP: mcp-remoteを使用してAtlassian MCPサーバーに接続
READ_ONLY_MODE: 書き込み操作を無効化し、安全にConfluenceを参照できる
認証: 初回接続時にブラウザでOAuth 2.1ベースの認証が行われ、以降は自動的に認証情報が管理される

プラグインの作成

本セクションで紹介するプラグイン構成は、説明用に簡略化したサンプルです。Claude Code Pluginsの最新の機能や仕様については公式ドキュメントをご参照ください。

開発ガイドラインレビュー用プラグインは、以下のようなディレクトリ構成で作成しました。

plugins/guideline-review/
├── .claude-plugin/
│   └── plugin.json             # プラグイン設定
├── .mcp.json                   # MCP Atlassian統合設定
├── commands/
│   └── guideline-review.md     # ガイドラインレビューコマンド定義
└── README.md                   # プラグイン詳細ドキュメント

plugin.json

プラグイン本体の設定ファイルです。プラグインの名前や説明、利用するコマンドを定義します。

{
  "name": "guideline-review",
  "version": "1.0.0",
  "description": "開発ガイドラインの準拠状況をレビューするプラグイン",
  "commands": ["commands/guideline-review.md"]
}

guideline-review.md

コマンドの振る舞いをMarkdown形式で定義します。ファイル先頭のフロントマターには、/helpで表示されるコマンドの説明（description）や使用可能なツール（allowed-tools）などのメタ情報を記述します。

記述可能なメタ情報の詳細は以下をご参照ください。

code.claude.com

フロントマター以降の本文部分がプロンプトとして実行されます。

---
description: 開発ガイドラインの準拠状況をレビューする
allowed-tools:
  - mcp__atlassian__*
  - Task
---

# 開発ガイドラインレビュー

現在のプロジェクトが開発ガイドラインに準拠しているかをチェックします。

## 手順

1. Atlassian MCPを使用して、Confluenceから開発ガイドラインを取得
2. 関連するプラットフォーム・領域の開発ガイドラインに対して、サブエージェントで並列してチェックを実行
3. 各項目について「適合」「非適合」「確認不可」を判定
4. 非適合の場合は具体的な指摘箇所と改善案を記載

このコマンド定義のポイントは以下の通りです。

allowed-tools: 使用可能なMCPツールを制限（Atlassianへのアクセスとサブエージェント起動のみ許可）
サブエージェントによる並列チェック: 開発ガイドラインは種類も多く、各開発ガイドラインの項目も数十に及ぶため、コンテキストウィンドウの消費を抑える観点からもサブエージェントを活用
構造化された出力: 適合・非適合の判定と詳細を明確に記載

プラグインの登録

作成したプラグインを全社で利用できるようにするため、マーケットプレイスとして登録します。リポジトリのルートに.claude-plugin/marketplace.jsonを配置します。

{
  "name": "xxxxx-marketplace",
  "plugins": [
    {
      "name": "guideline-review",
      "description": "開発ガイドラインの準拠状況をレビューします",
      "version": "1.0.0",
      "source": "./plugins/guideline-review"
    }
  ]
}

このリポジトリを公開し、利用者側でextraKnownMarketplacesに追加します。 .claude/settings.jsonに以下を追加します。

{
  "extraKnownMarketplaces": {
    "guideline-review": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

プラグインの利用方法

設定が完了したら、以下のコマンドでプラグインをインストールして利用できます。

# マーケットプレイスの追加
/plugin marketplace add your-org/claude-code-plugins-name

# プラグインのインストール
/plugin install guideline-review-plugin

# 開発ガイドラインレビューの実行（プラグイン名:コマンド名の形式）
/guideline-review-plugin:guideline-review

チーム展開時の設定

チーム全体でプラグインを利用する場合、プロジェクトの.claude/settings.jsonに許可設定を追加します。

{
  "plugins": {
    "allowed": ["guideline-review-plugin"]
  }
}

プラグインの実行結果

コマンドを実行すると、以下のような流れで処理が行われます。

適合状況のサマリー

確認すべき開発ガイドラインが分かった後は、対象の開発ガイドラインに対するチェックが行われ、結果が以下のようなサマリー形式で出力されます。

状態	件数	項目番号
✅ 適合	46	1-4, 10-12, 18, 20-23, 26-47, 49-54, 58
⚠️ 非適合	5	7, 8, 19, 24, 25
❓ 確認不可/対象外	7	9, 13-17, 48, 55-57

このサマリーはAPIガイドラインに対する適合状況の例です。適合・非適合・確認不可の判定が一覧化されています。

詳細レポート

サマリーに続き、各ガイドライン項目の詳細なチェック結果が出力されます。以下、JSON命名規約に関するレポートの抜粋です。

#	項目	必須度	状態	詳細・根拠
18	プロパティ名はASCIIスネークケース	MUST	✅ 適合	order_key, member_id等全て準拠
19	enumの値はUPPER_SNAKE_CASE形式	MUST	⚠️ 非適合	new_arrival, soldout等が小文字
20	Booleanのプロパティにnullを使わない	MUST	✅ 適合	boolean型にnullable設定なし
21	Booleanのプロパティ名は命名規約に従う	RECOMMENDED	✅ 適合	is_main, can_return等準拠
24	日時プロパティ名に_atサフィックス	MUST	⚠️ 非適合	order_date等_date使用
25	日付プロパティ名に_onサフィックス	MUST	⚠️ 非適合	日付専用プロパティも_date使用
26	日時型・日付型の値はISO 8601に準拠	MUST	✅ 適合	format: date-timeで指定

各項目に対して具体的なコード箇所や根拠が示されます。また、非適合項目については項目別の具体的な修正案も提示されるため、それを参考に修正計画を立てることができます。

今後の展望

本取り組みを通じて、開発ガイドライン準拠チェックの自動化の基盤ができました。今後は以下の拡張を検討しています。

プラグインの拡充: 開発ガイドラインのレビュー以外にも、コードレビュー支援やテスト生成などのプラグインを追加し、開発フロー全体をカバーする
Skills/Agentsの活用: 任意のタイミングでのチェックだけでなく、開発中も常に開発ガイドラインに準拠した実装が担保される仕組みを展開していく

まとめ

本記事では、開発ガイドライン準拠チェックをClaude Code Plugins × Atlassian MCPで全社展開した取り組みを紹介しました。Claude Code Pluginsは、組織固有のワークフローをパッケージ化して容易に配布・メンテナンスできる仕組みです。今回ご紹介した開発ガイドラインレビュー以外にも、さまざまな用途に応用できる可能性があります。また、Claude Codeは継続的にアップデートされているため、最新バージョンに追従することで新機能や改善の恩恵を最大限に受けることができます。AI駆動の開発プロセス標準化に取り組む方の参考になれば幸いです。

ZOZOでは、一緒にサービスを作り上げてくれる方を募集中です。ご興味のある方は、以下のリンクからぜひご応募ください。

corp.zozo.com

Claude Code v2.1.3でCommandsとSkillsが統合されました。本記事の執筆時点ではリリース前だったため、一部サンプルコードはCommands形式で記載していますが、挙動に変わりはありません。↩

ZOZO TECH BLOG

TECH BLOG