devops-practices

DevOps プラクティス - MCP サーバー

mcp-name: io.github.ai-4-devops/devops-practices

目的：PoC に取り組む DevOps エンジニアが AI の支援（Claude Code）を活用するための生産性フレームワークです。

種類：Claude Code 用の Model Context Protocol（MCP）サーバー

バージョン：1.4.0

ステータス：🎉 MCP レジストリで正式公開済み（公開日：2026年2月18日）

公開バージョン：

• 📦 PyPI：v1.4.0 → Git タグ v1.4.0（34ca572）
• 🌐 MCP レジストリ：v1.4.0 → Git タグ v1.4.0（34ca572）
• 🚀 最新の開発版：main ブランチ（未公開の機能が含まれる場合があります）

---

対象者：PoC の開発に **Claude Code（VS Code プラグイン）**を使用する DevOps エンジニアです。 できること： 構造（TRACKER、ISSUES、ドキュメント、SoP）を提供するため、ドキュメント作成の負担を気にせず、構築に集中できます。 対象外の内容： DevOps のチュートリアルではなく、AI 支援による開発のための生産性フレームワークです。

---

この MCP サーバーを使う理由

CLAUDE.md の肥大化問題を解決します

複数のプロジェクトにまたがる膨大な CLAUDE.md ファイル（1000 行以上）の管理に困っていませんか？この MCP は、複数の PoC に取り組むエンジニア向けに再利用可能な DevOps の手順を一元管理し、プロジェクトやフォルダー間で同じ指示を繰り返す必要をなくします。

問題点：

• ❌ 大きな CLAUDE.md ファイルがコンテキストウィンドウを圧迫します
• ❌ すべてのプロジェクトで同じプラクティスが重複しています
• ❌ PoC ごとに TRACKER.md、ISSUES.md、ドキュメント、SoP を作り直しています
• ❌ プロジェクト間で標準に一貫性がありません
• ❌ 実際の作業ではなく指示にコンテキストを消費しています

解決策：

• ✅ 事前構築済みの構成 - TRACKER、ISSUES、ドキュメント、SoP 用のテンプレート
• ✅ 作業に集中 - 「これをどう文書化すればよいか」ではなく、作業に集中できます
• ✅ 一貫性 - すべての PoC で同じ標準を適用できます
• ✅ チームの連携 - 同じパターンを使うことで、セッション、システム、チームメンバー間のシームレスな協業と簡単な引き継ぎが可能になります
• ✅ すばやく開始 - テンプレートをコピーして作業を開始できます
• ✅ コンテキストを節約 - 肥大化した CLAUDE.md ファイルが不要になります

利用できるもの（知識ではなく構成）：

• 📋 TRACKER.md テンプレート - 追跡方法を設計するのではなく、すぐに追跡を開始できます
• 🐛 ISSUES.md システム - Jira をセットアップするのではなく、すぐに問題を記録できます
• 📚 ドキュメント標準 - 構成を議論するのではなく、すぐにドキュメントを作成できます
• 📖 ランブックのテンプレート - SoP の形式を作るのではなく、すぐに運用手順を文書化できます
• 🔄 セッションの継続性 - 引き継ぎプロトコルを設計するのではなく、すぐに引き継ぎを開始できます

2026 年 2 月時点で MCP Registry で「devops」を検索した場合、該当する結果はこれだけです。他の MCP が次の分野に注力する一方で、

• 🔧 開発ツール（コード生成、テスト、デバッグ）
• 📊 データ分析（データベース、API、分析）
• 🎨 コンテンツ作成（執筆、デザイン、メディア）

この MCP が提供するもの：

• 🏗️ 構成の構造 - 環境ごとの設定の整理方法、完了済みの環境設定から新しい環境設定を生成する方法、SoP の作成と検証方法
• 📚 ドキュメントのパターン - すぐにコピーできる TRACKER、ISSUES、ドキュメント、ランブックのテンプレート
• 🔄 運用テンプレート - セッションの引き継ぎ、ランブックの形式、ドキュメント標準
• 🎯 構造化されたガイダンス - すばやく見つけられるよう GG-SS で整理されたプラクティス

他との違い：

• 生成ではなく、規範を提示 - 生成コードではなく、実証済みのプラクティスを提供します
• インフラを第一に - 開発者ではなく、運用チーム向けに構築されています
• 再利用可能なパターン - すべてのプロジェクトで使えるテンプレートと標準を提供します
• AI ネイティブな設計 - Claude が状況に応じてコンテキストを検索し、適用できるように整理されています
• R&D に最適化 - 概念実証の開発と実験を加速します

最適な対象： Claude Code（VS Code プラグイン）を使って PoC の構築や AI 支援による R&D を行う DevOps エンジニア。

---

動作の仕組み

サーバーの管理は不要です：

• ✅ 自動起動：Claude Code／Desktop の起動時に立ち上がります
• ✅ バックグラウンド実行：作業中は静かに動作します
• ✅ 必要に応じて利用：Claude が必要に応じてプラクティスを照会します
• ✅ 自動停止：Claude を閉じると停止します
• ✅ 代替手段：MCP が利用できない場合は、GitHub／ローカルからプラクティスにアクセスできます（トラブルシューティングを参照）

構成オプション：

MCP サーバーは、グローバル（すべてのプロジェクト）またはプロジェクトごとに構成できます。

オプション 1：グローバル構成（~/.claude.json）

{
  "mcpServers": {
    "devops-practices": {
      "command": "python3",
      "args": ["-u", "~/.mcp-servers/devops-practices/mcp-server.py"],
      "env": {"PYTHONUNBUFFERED": "1"}
    }
  }
}

オプション 2：プロジェクトレベルの構成（プロジェクトルートの .mcp.json）

{
  "mcpServers": {
    "devops-practices": {
      "command": "python3",
      "args": ["-u", "~/.mcp-servers/devops-practices/mcp-server.py"],
      "env": {"PYTHONUNBUFFERED": "1"}
    }
  }
}

セットアップ手順：

1. MCP サーバーをインストールします（以下のインストールのセクションを参照）
2. ~/.claude.json（グローバル）または .mcp.json（プロジェクトごと）に構成を追加します
3. Claude Code／Desktop を再起動します
4. MCP サーバーが自動的に実行されます。手動での起動は不要です

注：-u フラグと PYTHONUNBUFFERED により、デバッグ用のログがリアルタイムで記録されます。

---

提供内容

この MCP サーバーは、インフラストラクチャプロジェクトに共通する DevOps のプラクティスを共有します。

利用可能なプラクティス（11）

見つけやすくするため、GG-SS プレフィックスのパターン（グループ-順序）で整理されています。

命名パターン： GG-SS-practice-name

• GG = グループ ID（01-04）- 機能カテゴリ
• SS = 順序 ID（01-03）- グループ内の順序
• 例：03-02-air-gapped-workflow = グループ 03、順序 02

グループ一覧：

• 01 = ワークフローとプロセス（効果的な作業方法）
• 02 = バージョン管理とプロジェクト管理（git、課題）
• 03 = インフラストラクチャと設定（K8s、デプロイ、設定）
• 04 = ドキュメント標準（ドキュメント、README、運用手順書）

---

グループ 01：ワークフローとプロセス

1. 01-01-session-continuity - 状態の追跡、引き継ぎプロトコル、CURRENT-STATE.md
2. 01-02-task-tracking - TRACKER.md、CURRENT-STATE.md、PENDING-CHANGES.md
3. 01-03-efficiency-guidelines - スクリプト化とコピー＆ペーストの使い分け、コマンドの一括実行

グループ 02：バージョン管理とプロジェクト管理

4. 02-01-git-practices - git mv の使用、コミット規約、バックアップ手順、GitLab Flow
5. 02-02-issue-tracking 🆕 - リポジトリ内の Jira のような課題追跡システム（上級）

グループ 03：インフラストラクチャと設定

6. 03-01-configuration-management ⭐ - 設定の整理、プレースホルダー、環境の分離
7. 03-02-air-gapped-workflow - ノートパソコン、CloudShell、踏み台サーバー、EKS をまたいだ作業
8. 03-03-standard-workflow - 一般的な運用パターンとワークフロー

グループ 04：ドキュメント標準

9. 04-01-documentation-standards - HOW/WHAT/WHY の構成、命名規則
10. 04-02-readme-maintenance ⭐ - ディレクトリのドキュメント標準とベストプラクティス
11. 04-03-runbook-documentation ⭐ - 必須のセッションログ標準と要件

利用可能なテンプレート（7）

1. TRACKER.md - タスク追跡テンプレート（マイルストーン）
2. CURRENT-STATE.md - セッション引き継ぎテンプレート
3. CLAUDE.md - 簡易版プロジェクト指示テンプレート
4. RUNBOOK.md ⭐ - 必須セクションをすべて含むセッションログテンプレート
5. ISSUE.md 🆕 - 個別の課題テンプレート（上級）
6. ISSUES.md 🆕 - 統計ダッシュボード付き課題インデックステンプレート（上級）
7. issues/README.md 🆕 - 課題システムの使用方法（上級）

---

アーキテクチャ

devops-practices-mcp/
├── README.md                    # This file
├── mcp-server.py                # MCP server implementation
├── requirements.txt             # Python dependencies
├── .github/workflows/ci.yml     # GitHub Actions pipeline
├── health-check.sh              # Health validation script
├── practices/                   # Shared practice documents (11 files, GG-SS organized)
│   ├── 01-01-session-continuity.md
│   ├── 01-02-task-tracking.md
│   ├── 01-03-efficiency-guidelines.md
│   ├── 02-01-git-practices.md
│   ├── 02-02-issue-tracking.md  # 🆕 Advanced: In-repo issue tracking
│   ├── 03-01-configuration-management.md
│   ├── 03-02-air-gapped-workflow.md
│   ├── 03-03-standard-workflow.md
│   ├── 04-01-documentation-standards.md
│   ├── 04-02-readme-maintenance.md
│   └── 04-03-runbook-documentation.md
├── templates/                   # File templates (7 files)
│   ├── TRACKER-template.md
│   ├── CURRENT-STATE-template.md
│   ├── CLAUDE-template.md
│   ├── RUNBOOK-template.md
│   ├── ISSUE-TEMPLATE.md        # 🆕 Individual issue template
│   ├── ISSUES.md                # 🆕 Issue index with dashboard
│   └── issues-README.md         # 🆕 Issue system guide
├── tools/                       # Automation tools 🆕
│   └── issue-manager.sh         # CLI for managing issues
└── config/                      # MCP configuration
    └── mcp-config.json          # Server configuration

---

MCP ツール

MCP サーバーは、Claude がプラクティスやテンプレートを検索するための 5 つのツールを提供します。

ツール	説明	例
list_practices	利用可能なすべてのプラクティスを一覧表示します	10 件のプラクティスの一覧を返します
get_practice	名前を指定してプラクティスの内容を取得します	get_practice("01-02-task-tracking")
list_templates	利用可能なすべてのテンプレートを一覧表示します	4 件のテンプレートの一覧を返します
get_template	名前を指定してテンプレートの内容を取得します	get_template("TRACKER-template")
render_template	変数を置換してテンプレートをレンダリングします	render_template("TRACKER-template", {"PROJECT_NAME": "my-project"})

テンプレート変数の置換

テンプレートでは、${VARIABLE} プレースホルダーがサポートされており、自動的に置換されます。

自動提供される変数：

• ${DATE} - 現在の日付（YYYY-MM-DD 形式）
• ${TIMESTAMP} - UTC タイムスタンプ（YYYYMMDDTHHMMz 形式）
• ${USER} - 現在のシステムユーザー
• ${YEAR} - 現在の年

カスタム変数： レンダリング時に任意の追加変数を渡せます。

render_template("RUNBOOK-template", {
    "SESSION_NUMBER": "1",
    "TITLE": "Kafka Deployment",
    "CLUSTER_NAME": "example-eks-uat",
    "OBJECTIVE_DESCRIPTION": "Deploy Kafka cluster to UAT"
})

テンプレート内のすべての ${...} プレースホルダーが、指定した値に置き換えられます。

---

CI/CD パイプライン

このリポジトリには、変更を自動的に検証する GitHub Actions パイプライン（.github/workflows/ci.yml）が含まれています。

パイプラインのジョブ

すべてのマージリクエストと main/develop へのコミット時に実行されます：

1. health-check - 包括的なヘルスチェック用スクリプトを実行します
2. python-validation - Python の構文と依存関係を検証します
3. practice-validation - すべてのプラクティスファイルが存在することを確認します
4. template-validation - テンプレートに変数プレースホルダーが含まれていることを確認します
5. link-checker - ドキュメント内の相互参照をチェックします

メリット

• ✅ 破壊的変更がメインブランチに到達するのを防ぎます
• ✅ 不足しているファイルや構文エラーを自動的に検出します
• ✅ 一貫した品質基準を確保します
• ✅ 手動での検証は不要です

パイプラインのステータス

GitHub でパイプラインのステータスを確認します：

• 緑のチェックマーク ✅ - すべてのチェックに合格しました。マージしても安全です
• 赤い X ❌ - チェックに失敗しました。マージする前にエラーを確認してください

---

ドキュメント

クイックリファレンス

• PRACTICE-INDEX.md - どのプラクティスをいつ使うかをすばやく調べるガイド
  • タスクの種類別に整理（デプロイ、ドキュメント作成、トラブルシューティングなど）
  • 推奨プラクティスを含む一般的なシナリオ
  • プラクティスの依存関係と関連性

移行ガイド

• MIGRATION-GUIDE.md - 既存のプロジェクトに MCP を導入する
  • モノリシックな CLAUDE.md からの段階的な移行手順
  • Claude Desktop/Code の設定
  • テストと検証の手順
  • 必要に応じたロールバック計画

バージョン履歴

• CHANGELOG.md - 完全なバージョン履歴とアップグレードガイド
  • バージョン 1.0.0（2026-02-13）：10 個のプラクティス、4 個のテンプレート、ヘルスチェックツール
  • バージョン 0.1.0（2026-02-13）：初回リリース

ヘルスチェック

• health-check.sh - デプロイ前に MCP サーバーを検証します
  • 14 項目の包括的なチェック（ディレクトリ構造、ファイル、Python 環境、読み込みテスト）
  • 合格数と失敗数を色分けして表示
  • 終了コード：0（正常）、1（異常）

使い方：

cd devops-practices-mcp
bash health-check.sh

---

プロジェクトでの活用方法

プロジェクトの CLAUDE.md 構成

各プロジェクトには、簡潔な CLAUDE.md を用意します：

# Claude AI Assistant - [Project Name]

## MCP Service Integration
**Shared Practices**: `devops-practices` MCP server

Claude has access to shared DevOps practices via MCP:
- Air-gapped workflow
- Documentation standards
- Session continuity protocols
- Task tracking guidelines
- Git best practices
- Efficiency guidelines

⚠️ Fallback: If MCP unavailable, see Appendix or GitHub practices

## Project-Specific: [Project Details]
[Only project-specific instructions here]

## Appendix: Critical Practices (Fallback)
[Emergency practice summaries if MCP down - see CLAUDE-template.md]

メリット

• DRY：共通のプラクティスを一度だけ記述し、あらゆる場所で活用できます
• 一貫性：すべてのプロジェクトで同じ標準に従えます
• 保守性：一度更新すれば、すべてのプロジェクトに反映されます
• 見つけやすさ：必要なときに Claude がプラクティスを検索できます
• 堅牢性：MCP が利用できない場合は、GitHub／ローカル／付録にフォールバックします

テンプレート： フォールバック用の付録を含む完全な構成については、CLAUDE-template.md を参照してください

---

インストールと設定

🔧 手動インストール（最も安定 — 開発におすすめ）

最適な対象： 開発者、コントリビューター、またはすべてを自分で管理したい方

1. リポジトリをクローンする

# Clone to recommended location
git clone https://github.com/ai-4-devops/devops-practices.git ~/.mcp-servers/devops-practices
cd ~/.mcp-servers/devops-practices

2. 依存関係をインストールする

# Using uv (10-100x faster)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv pip install -r requirements.txt

# Or using traditional pip
pip install -r requirements.txt

3. MCP サーバーを設定する

~/.claude/config.json を編集します：

{
  "mcpServers": {
    "devops-practices": {
      "command": "python3",
      "args": ["-u", "~/.mcp-servers/devops-practices/mcp-server.py"],
      "env": {"PYTHONUNBUFFERED": "1"}
    }
  }
}

4. Claude Code/Desktop を再起動する

5. MCP 接続を確認する

Claude に「MCP サーバーから利用可能な DevOps プラクティスを一覧表示できますか？」と尋ねます。

💡 ヒント： Claude に MCP を確認するよう、あらためて伝える必要がある場合があります。プラクティス名が返されない場合は、次のように試してください：

• 「devops-practices MCP サーバーにアクセスできるか確認してください」
• 「利用可能な MCP ツールをすべて一覧表示してください」
• Claude Code をもう一度再起動する

---

🧪 実験的／テスト用（詳しい方向け）

⚠️ 注意： これらの方法は実験的で、まだ十分にテストされていません。確実に設定するには、上記の手動インストールを使用してください。

オプション 1：Claude Desktop の UI から MCP レジストリを利用（実験的）：

1. Claude Desktop を開きます
2. Settings → Developer → MCP Servers に移動します
3. 「devops-practices」を検索します
4. 「Install」をクリックします
5. Claude Code/Desktop を再起動します

オプション 2：uvx でインストール（✨ おすすめ — 仮想環境を自動管理）：

# Add MCP server using uvx (handles venv automatically)
claude mcp add devops-practices -- uvx devops-practices-mcp

# Restart Claude Code/Desktop to activate

おすすめの理由： uvx が仮想環境を自動的に管理するため、設定は不要です。

オプション 3：uv + venv でインストール（Python 開発者向け）：

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment
uv venv ~/.venvs/devops-practices-mcp

# Activate venv
source ~/.venvs/devops-practices-mcp/bin/activate

# Install MCP server
uv pip install devops-practices-mcp

# Add to Claude configuration (using venv's python)
claude mcp add devops-practices -- ~/.venvs/devops-practices-mcp/bin/python -m devops_practices_mcp

# Restart Claude Code/Desktop to activate

この方法を使う理由： 最新の uv ツールを使って、仮想環境を完全に管理できます。

オプション 4：ユーザーディレクトリにインストール（旧方式 — 仮想環境なし）：

# Install using pip (to ~/.local/)
pip install --user devops-practices-mcp

# Add to Claude configuration
claude mcp add devops-practices -- python3 -m devops_practices_mcp

# Restart Claude Code/Desktop to activate

オプション 5：システム全体にインストール（sudo が必要）：

# Install system-wide (requires root)
sudo pip install devops-practices-mcp

# Add to Claude configuration
claude mcp add devops-practices -- python3 -m devops_practices_mcp

# Restart Claude Code/Desktop to activate

オプション 6：手動設定（設定ファイルを直接編集）：

pip または uvx でインストールしてから、~/.claude/config.json を編集します：

{
  "mcpServers": {
    "devops-practices": {
      "command": "uvx",
      "args": ["devops-practices-mcp"],
      "env": {}
    }
  }
}

---

実際の活用例

1. 複数環境にわたる Kafka のデプロイ

シナリオ：dev → test → uat → prod に Kafka をデプロイします

MCP を使用しない場合：

• 各プロジェクトに 580 行の CLAUDE.md を複製します
• 各環境で同じ問題に繰り返し対処します（合計 12 時間）
• チーム間で標準化されたアプローチがありません

MCP を使用する場合：

• Claude が get_practice("configuration-management") を照会し、インストール手順書を取得します
• test 環境用に dev のランブックをコピーします（所要時間を 56% 削減）
• すべてのチームが同じ標準に自動的に従います

結果：5.25 時間対 12 時間（56% 高速化）

2. 標準化された Git ワークフロー

シナリオ：チームで一貫したブランチ戦略が必要です

MCP を使用しない場合：

• プロジェクトごとにブランチの運用方法が異なります
• 新しいチームメンバーがワークフローに戸惑います
• Git の運用方法が各所で異なる形式で文書化されています

MCP を使用する場合：

• Claude が get_practice("02-01-git-practices") を照会します
• 全員が同じ 200 行以上の GitLab Flow ドキュメントを利用できます
• Git 標準の単一の信頼できる情報源になります

結果：15 件すべてのプロジェクトで一貫したワークフローを実現

3. エアギャップ環境へのインフラストラクチャのデプロイ

シナリオ：インターネットに接続できないセキュアな環境にデプロイします

MCP を使用しない場合：

• セッションごとにワークフローを説明し直します
• 古いランブックからコマンドをコピー＆ペーストします
• ファイル転送手順に一貫性がありません

MCP を使用する場合：

• Claude が get_practice("air-gapped-workflow") を照会します
• Laptop → S3 → Bastion → Target の手順を順番に取得します
• 毎回一貫したプロセスで実行できます

結果：セキュリティインシデントゼロで、予測可能なデプロイを実現

4. プロジェクトドキュメントのセットアップ

シナリオ：新しいインフラストラクチャプロジェクトを開始します

MCP を使用しない場合：

• CLAUDE.md をゼロから作成します（2 時間）
• 古いプロジェクトからコピー＆ペーストします（一貫性がありません）
• 重要なプラクティスを見落とします

MCP を使用する場合：

User: "Create project structure for monitoring-stack project"
Claude: [Queries MCP for templates]
Claude: Creates TRACKER.md, CURRENT-STATE.md, RUNBOOK.md
        All following latest standards

結果：15 分対 2 時間（88% 高速化）

5. 複雑なプロジェクトの課題追跡

シナリオ：3 か月のプロジェクトで 50 件以上の作業項目を管理します

MCP を使用しない場合：

• 外部の Jira を使用します（アクセスの問題、オーバーヘッド）
• または、散在する Markdown ファイルで追跡します
• 一貫した形式がありません

MCP を使用する場合：

• Claude が get_template("ISSUES") を照会します
• ダッシュボード付きのリポジトリ内課題追跡を作成します
• CLI で管理するために tools/issue-manager.sh を使用します

結果：Git ベースの追跡を実現し、外部依存がありません

---

使用例

Claude の場合

プロジェクトで作業するときは、以下のようにします。

プラクティスを照会：

User: "What's the air-gapped workflow for file transfers?"
Claude: [Queries MCP: get_practice("air-gapped-workflow")]
Claude: [Receives markdown content]
Claude: "Here's the air-gapped workflow..."

テンプレートを取得（未加工）：

User: "Show me the TRACKER template"
Claude: [Queries MCP: get_template("TRACKER-template")]
Claude: [Receives template with ${VARIABLES}]
Claude: "Here's the template..."

テンプレートをレンダリング（変数を使用）：

User: "Create a TRACKER.md for my kafka-deployment project"
Claude: [Queries MCP: render_template("TRACKER-template", {
    "PROJECT_NAME": "kafka-deployment",
    "DATE": "2026-02-14",
    "PHASE_NAME": "UAT Deployment"
})]
Claude: [Receives rendered template with all variables substituted]
Claude: [Creates TRACKER.md with actual values]

プラクティスの更新

貢献者向け：

cd devops-practices-mcp
vim practices/documentation-standards.md
# Make changes
git add practices/documentation-standards.md
git commit -m "Update documentation standards: add new RUNBOOKS guidelines"
git push
# All projects using this MCP server now get updated standards

---

ブランチ戦略

このリポジトリでは、依存するプロジェクトの安定性を確保するため、セマンティックバージョニングを採用した GitLab Flow を使用しています。

ブランチ構成

main            ← Production releases only (v1.0.0, v1.1.0, etc.)
  ↑
develop         ← Active development, integration branch
  ↑
feature/*       ← New practices, templates
release/*       ← Version preparation (v1.2.0)
hotfix/*        ← Critical production fixes

ブランチの種類

ブランチ	目的	作成元	マージ先
main	本番リリース（タグ付け済み）	-	-
develop	アクティブな開発	main	main（リリース経由）
feature/*	新機能	develop	develop
release/*	バージョン準備	develop	main + develop
hotfix/*	重大な修正	main	main + develop

GitLab Flow を採用する理由

• ✅ 安定性：main には常にテスト済みの本番環境対応コードが含まれます
• ✅ 安全性：変更は本番環境に反映する前に develop を経由します
• ✅ テスト：CI/CD によって、マージ前にすべての変更が検証されます
• ✅ バージョニング：明確なセマンティックバージョニングによるリリース（v1.0.0、v1.1.0 など）
• ✅ 追跡可能性：何がいつ変更されたかの完全な履歴を確認できます

クイックワークフロー

新しいプラクティス／テンプレートの追加：

git checkout develop
git checkout -b feature/add-security-practice
# Make changes, commit
git push origin feature/add-security-practice
# Create PR → develop

リリースの作成：

git checkout develop
git checkout -b release/v1.2.0
# Update CHANGELOG.md, version numbers
# Create PR → main
# Tag release: git tag v1.2.0
# Merge back to develop

緊急のホットフィックス：

git checkout main
git checkout -b hotfix/critical-bug
# Fix, commit, push
# Create PR → main (fast-track)
# Also merge to develop

詳細なドキュメント：CONTRIBUTING.md および git-practices.md を参照してください

---

ガバナンス

メンテナンス担当

• オーナー：Uttam Jaiswal Lead
• 貢献者：DevOps エンジニア
• レビュー手順：変更には PR が必要です

更新プロトコル

新しいプラクティス／テンプレートの場合：

1. develop から機能ブランチを作成します
2. プラクティスまたはテンプレートのファイルを更新します
3. ヘルスチェックを実行します：bash health-check.sh
4. ドキュメント（README.md、PRACTICE-INDEX.md）を更新します
5. 説明を添えて PR を作成します → develop
6. チームによるコードレビューを受けます
7. CI/CD の合格後、develop にマージします

リリースの場合：

1. develop からリリースブランチを作成します：release/v1.x.0
2. CHANGELOG.md とバージョン番号を更新します
3. PR を作成します → main
4. マージ後にリリースへタグを付けます：git tag v1.x.0
5. リリースを develop にマージします
6. チームに告知します（依存するすべてのプロジェクトに影響します）

重大な修正の場合：

1. main からホットフィックスブランチを作成します：hotfix/issue-name
2. 問題を修正し、十分にテストします
3. PR を作成します → main（優先的に承認）
4. ホットフィックスリリースにタグを付けます：git tag v1.x.1
5. 同期を維持するため、develop にマージします
6. 緊急の修正をチームに告知します

詳細なワークフローについては：CONTRIBUTING.md を参照してください

バージョン管理

• メジャーバージョン（2.0）：構造に対する破壊的変更
• マイナーバージョン（1.1）：新しいプラクティスの追加
• パッチバージョン（1.0.1）：明確化、修正

---

この MCP サーバーを使用するプロジェクト

プロジェクト	目的	場所
kafka-deployment	Apache Kafka のデプロイ	サンプルプロジェクト
observability-stack	可観測性スタック	サンプルプロジェクト
network-infra	ネットワークインフラストラクチャ	サンプルプロジェクト

---

開発

貢献ワークフロー、ブランチ戦略、コードレビュープロセスの詳細については、CONTRIBUTING.md を参照してください。

新しいプラクティスの追加

1. practices/ に Markdown ファイルを作成します
2. 例を含め、明確な構成にします
3. 必要に応じて mcp-server.py を更新します
4. Claude でテストします
5. この README を更新します（プラクティス数）
6. PRACTICE-INDEX.md を更新します（シナリオ一覧に追加）
7. CHANGELOG.md を更新します（追加内容を記録）
8. ヘルスチェックを実行します：bash health-check.sh

新しいテンプレートの追加

1. templates/ にテンプレートファイルを作成します
2. プレースホルダーを使用します：${PROJECT_NAME}、${DATE} など（MCP Tools セクションの自動提供変数を参照してください）
3. コードの変更は不要です。render_template がすべての ${...} の置換を自動的に処理します
4. テンプレートをテストします：render_template("your-template", {"VAR": "value"})
5. この README を更新します（テンプレート数）
6. CHANGELOG.md を更新します（追加内容を記録）
7. ヘルスチェックを実行します：bash health-check.sh

変更を加える場合

• リリース前： すべてのファイルを検証するため、ヘルスチェックを実行します
• 変更後： バージョンを更新して CHANGELOG.md を更新します
• 破壊的変更： 移行時の注意事項を記載して MIGRATION-GUIDE.md を更新します
• 新機能： 使用シナリオを記載して PRACTICE-INDEX.md を更新します

---

トラブルシューティング

Claude が MCP サーバーにアクセスできない

症状： Claude が質問してもプラクティスを返さない、または MCP が存在しないかのように振る舞う

解決策：

1. Claude に明示的に伝えます：「devops-practices MCP サーバーを確認し、利用可能なプラクティスを一覧表示してください」
2. MCP が読み込まれているか確認します：「どの MCP サーバーにアクセスできますか？」と尋ねます
3. 設定を確認します： ~/.claude/config.json に正しいパスが設定されていることを確認します（絶対パスである必要があります）
4. Claude Code を再起動します： MCP サーバーは起動時に読み込まれます
5. ログを確認します： ~/.cache/claude/mcp-devops-practices.log でエラーを確認します
6. MCP プロセスを確認します： ps aux | grep mcp-server.py を実行し、プロセスが稼働していることを確認します

💡 プロのヒント： Claude は MCP サーバーの確認を「忘れる」ことがあります。タスクに取りかかる前に MCP を確認するよう、明示的に伝えてください。

ログの場所： ~/.cache/claude/mcp-devops-practices.log

MCP サーバーが停止または利用不可

症状： MCP サーバーのプロセスがクラッシュした、応答しない、または起動できない

代替オプション：

オプション 1：GitHub のプラクティス（推奨）

Access practices directly from GitHub:
https://github.com/ai-4-devops/devops-practices/tree/main/practices

Ask Claude to read practices via GitHub URLs when MCP unavailable.

オプション 2：ローカルクローン

# Access practices from local clone
ls ~/.mcp-servers/devops-practices-mcp/practices/

# Read practice directly
cat ~/.mcp-servers/devops-practices-mcp/practices/03-02-air-gapped-workflow.md

オプション 3：CLAUDE.md の付録

Projects using the CLAUDE-template.md have a built-in appendix
with critical practice summaries for emergency fallback.

See: templates/CLAUDE-template.md (Appendix section)

予防策：

• プロジェクトレベルの設定には .mcp.json を使用します（より信頼性があります）
• セッション開始前のチェックリストに MCP のヘルスチェックを追加します
• ローカルクローンを最新の状態に保ちます：git pull origin main
• ログを監視します：tail -f ~/.cache/claude/mcp-devops-practices.log

関連項目： プロジェクト固有の代替設定については、MIGRATION-GUIDE.md を参照してください

プラクティスファイルが見つからない

1. ファイルが存在することを確認します：ls practices/
2. ファイル名が正確に一致していることを確認します（大文字と小文字を区別します）
3. MCP サーバーのログを確認します

テンプレートの置換に失敗する

1. プレースホルダーの構文を確認します：${VARIABLE}
2. テンプレートファイルのエンコーディングを確認します（UTF-8）
3. mcp-server.py のログを確認します

---

ライセンス

MIT License - 自由に使用および変更できます

---

メンテナンス担当者：Uttam Jaiswal 最終更新日：2026-02-20 バージョン：1.4.0