mcpField
A
adr-index

adr-index

github.com/ruvnet開発80.0k737 回インストール今日更新
リポジトリ

adr-index について

adr-indexは、リポジトリ内のADR文書とその関係を保存するスキルです。ADR管理の初期導入やグラフデータとファイルの同期に使え、Ruflo monorepoで使われる2種類の形式を解析し、ドライランとセマンティック検索にも対応します。

主な機能

  1. 01ADRファイルのスキャン
  2. 022種類のADR形式を解析
  3. 03ADRと関係エッジの保存
  4. 04エッジを重複させずに更新
  5. 05ステータスと未解決参照の集計
  6. 06ドライランとJSON出力

活用シーン

  1. 01別プロジェクトからADRをインポート
  2. 02AgentDBグラフとファイルの不整合を修正
  3. 03既存コードベースでADR管理を開始
  4. 04インポート済みADRをテーマで検索

MCP 対応

adr-patterns名前空間でのセマンティック検索にMCP memory_searchを使います。インポートスクリプトがADRレコードと関係を永続化します。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/ruvnet/ruflo --skill adr-index

インストール後、Claude Code で/adr-indexを入力して読み込まれたか確認します。

詳細

ADR インデックス

*/docs/adr/ または */docs/adrs/ にあるすべての ADR を adr-patterns 名前空間に、すべての関連（supersedes / amends / related / depends-on）を adr-edges に保存します。Ruflo モノレポにある両方の ADR 形式に対応しています。

  • v3 形式：# ADR-097: Title の見出しと **Status**: Proposed の行
  • プラグイン形式：YAML フロントマター（id: ADR-NNNN、status: Proposed）

実装には、ADR ごとに多数の MCP ツール呼び出しを行うのではなく、scripts/import.mjs（Bash 呼び出し 1 回）を使用します。動作は実質的に同じで、はるかに高速であり、両形式に対応し、課題番号の誤検出を防ぎます。

使用するタイミング

  • 別のプロジェクトから ADR をインポートした後
  • AgentDB グラフがディスク上の ADR ファイルと同期していない場合
  • 既存のコードベースで ADR の追跡を開始する場合

手順

  1. インポーターを実行します：

    node plugins/ruflo-adr/scripts/import.mjs

    任意の環境変数：

    • IMPORT_FORMAT=json — Markdown の代わりに JSON を出力します
    • IMPORT_DRY_RUN=1 — 解析と要約を行い、保存はスキップします
    • ADR_ROOT=/path — 別のルートをスキャンします（デフォルト：cwd）

  2. 要約を確認します — ADR の合計数、保存件数、ステータス別の内訳、エッジ数、参照先が存在しない参照、ステータスの不一致。

  3. グラフの整合性を検証します（任意ですが推奨）。同じディレクトリにある adr-verify スキルを使用します。このスキルは scripts/verify.mjs を実行し、循環がある場合は 1 を終了コードとして返します。

  4. 意味検索を行います。データが格納された名前空間を対象に mcp__plugin_ruflo-core_ruflo__memory_search を使用します。

    memory_search --query "federation budget" --namespace adr-patterns

保存形式

adr-patterns 名前空間、キー <ADR-id>::<basename>、値（テキスト）：

<title> — <first paragraph of Context>

file: <relative path>
status: <Proposed|Accepted|Superseded|...>
date: <ISO date>
tags: <comma-separated>

adr-edges 名前空間、決定的なキー <relation>:<FROM>__<TO>、値：

{ "from": "ADR-097", "to": "ADR-086", "relation": "related", "capturedAt": "<ISO>" }

ADR レコードと関連エッジの両方は、明示的な upsert セマンティクスで保存されます。adr-index を再実行すると、変更されたメタデータがその場で更新され、変更のない意味的エッジが重複して作成されることはありません。

誤検出の防止

ADR 本文内の #1697 / commit abc123 / PR 1234 への参照は、正規表現で抽出する前に削除されるため、ADR-1697 などと誤認されません。scripts/import.mjs の extractAdrRefs() を参照してください。

このスキルでできないこと

adr-index は追加または upsert のみを行います。ADR ファイルが削除された場合（または残存するファイルから関連行が削除された場合）でも、書き込まれた行は残り続けます。孤立した行には参照先のない参照がなく、循環も形成されないため、adr-verify でも検出できません。削除を反映するには、同じディレクトリにある adr-reindex スキルを使用してください（issue #2666）。

相互参照

  • adr-create — このスキルが処理する ADR ファイルを作成します
  • adr-review — コンプライアンスチェックのために adr-patterns を対象に実行します
  • adr-verify（同じディレクトリにあるスキル）— グラフ整合性のゲート処理として scripts/verify.mjs を実行します
  • adr-reindex（同じディレクトリにあるスキル）— 削除された ADR ファイルを照合するため、データを削除して再構築します（このスキルは追加のみ可能で、削除はできません）

コメント

Markdown 対応