参照C

スキル関係グラフ — 構造と運用

スキルが数十を超えると「どのスキルが何を前提とするか」は組織の記憶の外へ消えていく。この文書は、第10章 §2で紹介したスキル関係グラフの具体的構造 — データ原典、スキーマ、関係語彙、生成パイプライン、検証と運用ワークフロー — を一つの章としてまとめる。

出典: ai-workspace-standards ADR-0060 Skill Relationship Graph as Generated Projection (Amendments 1–8) · ADR-0061 Decision Record Standard · scripts/generate-skill-graph.ts v1.7.1

この文書で扱うこと
  • グラフがなぜ1次ストアではなく「常に再生成されるプロジェクション」なのか
  • 関係を導出する5つのデータ原典とその優先順位
  • ノード/エッジのスキーマと10個の型付き関係語彙
  • 明示的・実験的・プロジェクションの3層モデルと90日ルール
  • 生成・検証・同期パイプラインと関係追加の実務手順

概要 — なぜグラフか

スキル・エージェント・ADRの間の関係(「このスキルはあのスキルを先に実行すべき」「このエージェントはあのスキルを使う」)を自由テキストで書いておくと、三つのことが必ず起こる。第一に、原典が変わっても文章はそのまま残り 古くなる。第二に、関係がファイルのあちこちに散らばり 検索できなくなる。第三に、人がリストを手入れしない限り 検証もされない。

スキル関係グラフはこれを「直接書かず、導出する」ことで解決した。関係の原典はすでに存在する構造化データ(SKILL.mdフロントマター、エージェントファイル、variantマニフェスト)であり、グラフはそのプロジェクションである。グラフファイルはいつ消してもよい — ジェネレーターを再実行すれば、まったく同じ方法で再び生まれる。ADR-0060がこの原則を Generated Projection という名で固定したのはこのためだ。

データ原典と優先順位

ジェネレーターは次の原典を優先順に走査する。前の原典ほど意図が明示的で、後ほど暗黙的導出である。

  1. SKILL.mdフロントマター — prerequisites(必須前提スキル)と型付き relates_to(関係語彙+対象+任意メモ)。最も明示的な原典。
  2. エージェントファイルの required_skills — エージェント→スキルの used_by 関係を作る。
  3. variant.json の skill_manifest — variantがどのスキルをどのエージェント・フェーズに紐づけるかのマニフェスト。phase 関係の原典。
  4. ドキュメント本文のバッククォート参照 — ドキュメントがスキル名を正確なバッククォート名で言及すると references エッジになる(誤検出を防ぐため完全一致のみ)。
  5. docs/skill-graph.overrides.json — 上記の原典では導出できない関係を追加、または自動導出された関係を抑止するエスケープハッチ。スコープ別オーバーライドも対応。

フロントマター由来のエッジには provenance: {file, field, index?} が付く。「この関係はなぜ存在するのか」を辿ると、必ず原典ファイルの特定フィールドに戻れる。

ノードとエッジのスキーマ

グラフのコミット成果物は二つ — 機械用の docs/skill-graph.json と人が読む関係表 docs/skill-graph.md。JSONの最上位構造は {version, nodes[], edges[]} だ。

{
  "version": "1.7",
  "nodes": [
    { "id": "handbook", "type": "skill", "layer": "common" },
    { "id": "handbook-reviewer", "type": "agent", "layer": "common" },
    { "id": "ADR-0060", "type": "adr", "layer": "L0" }
  ],
  "edges": [
    {
      "from": "handbook",
      "to": "research",
      "type": "requires",
      "provenance": {
        "file": "skills/handbook/SKILL.md",
        "field": "prerequisites",
        "index": 0
      }
    },
    {
      "from": "handbook-reviewer",
      "to": "handbook",
      "type": "used_by"
    }
  ]
}

ノードは id・type・layer を持つ。型は skill、agent、adr、decision、procedure、output_type などで、レイヤーは L0(ワークスペースルート)、common(共通テンプレート)、variant:<name>、L3(個別プロジェクト)だ。

エッジ型の詳細

Amendment 1–8にわたって育った関係語彙の全体。方向と対称性、原典を併せて整理する。すべてのエッジは 助言的(advisory) — ルーティングと計画に情報を与えるが、実行を強制的に妨げない。

エッジ意味方向/対称原典
requiresBはAの必須前提スキルであるA→B(非対称)フロントマター prerequisites
relates_to一般的な関連(レガシー)A→Bフロントマター relates_to
composes_with同じエージェント内で共に使われる組合せ関係対称(symmetric: true の単一エッジ)Amendment 8 — 一つのエージェントの required_skills 共同宣言から導出
follows順序のみを示す。依存を含意しないA→Bフロントマター
enablesAの産出物がCを可能にするA→Cフロントマター
used_byエージェントがスキルを使用するagent→skillエージェント required_skills
phaseスキルがワークフローフェーズに割り当てられるskill→phasevariant.json skill_manifest
supersedesドキュメントの継承(旧→新)old→newドキュメントメタ
referencesドキュメント間の引用A→Bバッククォート参照
cites_skill意思決定記録がスキルを引用decision→skill意思決定記録本文
最もよくある間違いは requires の方向の混同だ。A requires B は「Aを使うにはBが先」という意味であり、「AがBを生み出す」ではない。方向が曖昧なら provenance フィールドで原典フロントマターを確認せよ。

関係の3層モデル

同じグラフの中に三種類の関係が混在している。寿命と信頼度が異なるため、層を区別して扱う。

  • L-A 明示的(Explicit) — フロントマターの型付き relates_to。意図として恒久的で、グラフの1次原典。
  • L-B 実験的(Experimental) — オーバーライドファイルの関係。reason と since の記録が必須で、90日が経過すると陳腐化の警告が出る。「グラフにあるべきだがフロントマターに入れる前の観察中」の関係の待合室。
  • L-C プロジェクション(Projection) — 生成されたグラフそのもの。常に再生成され、決定論性検証で「同じ入力→同じ出力」が崩れていないことを確認。

実験的関係が安定したと判断されればフロントマターへ移してL-Aへ昇格する。逆にL-Aを無くすにはフロントマターから消せばよい — グラフファイルを直接編集する経路は存在しない。

生成パイプライン

グラフは四つの場所でパイプラインと噛み合う。

  • scripts/generate-skill-graph.ts — 原典を走査して skill-graph.json/.md を生成。グラフはスキーマv2で、ノードidはスコープ込み（例: skill:co-abap/abap-dev）。--scope <name> でテンプレート別スコープグラフを作る(共通+各variant、計15スコープ)。
  • scripts/verify-skill-graph.ts — コミット済みグラフが原典と一致するか(ドリフト)と不変式を検証。
  • dev-sync.ts ステップ4.65 — /sync のたびに全スコープのグラフを再生成しドリフト確認。「グラフを最新に保つ作業」がコミットフローに組み込まれている。
  • new-project.ts ステップ7.6 — 新規プロジェクトのスキャフォールディング時に、そのプロジェクトの docs/skill-graph.json を即座に生成。最初の /sync を待たせない。

スコープグラフは統合L0グラフの 範囲ビュー だ。variantテンプレートが自スコープのグラフを同梱するため、そこから生まれるプロジェクトは初日から自分に関係の深い関係地図を持って始まる。

宣言的 vs 推論的 構築戦略

関係をどこから引き出すかについて、二つの戦略がある。

  • 宣言的(Declarative) — フロントマターに関係を直接宣言する(Amendment 3)。意図が明確で検証が単純だが、スキル作成者の規律に依存する。
  • 推論的(Inferential) — 既存の構造化データから関係を導出する(Amendment 4、co-newbiz前例)。手順スキーマのフェーズ隣接性やルール述語を根拠とする。フロントマターを一つも追加せずにカバレッジを増やせる。

比較実験(scripts/experiments/infer-graph-from-phases.ts、読み取り専用)の結論は折半だ — 手順スキーマが豊富な領域では推論がよく機能するが、そうでないテンプレートでは宣言的戦略が優れる。そのため新しいデフォルト抽出モードは採用されず、両戦略は共存する。スキーマのある所は導出し、残りは宣言で埋める。

意思決定チェーンと検証

グラフがADR・意思決定記録まで取り込む理由は「関係」と「根拠」を一枚の地図に載せるためだ。ADR-0061の意思決定チェーン — Agent, Skill, Knowledge, Evidence, Rule, Decision — を scripts/validate-decisions.ts が fail-closed で検証する。

  • 意思決定記録の必須フロントマターと証拠台帳(evidence ledger)参照の存在
  • ルールID形式とスキル参照の解決可能性
  • 伝播結合ルール — L1に発行されたスキルが、L1に存在しない対象と関係を結ぶことを禁止。守らないと下位コピーごとに宙ぶらりんのエッジ(dangling edge)が生える。

グラフは supersedes・cites_skill エッジで「この決定がどのスキルの上に、どのドキュメントを継承して出たか」を示す。関係が根拠なしに増えるのを構造的に防ぐ装置だ。

実務ワークフロー — 関係を追加する

実際に関係を一つ追加するときの最小手順だ。

  1. 宣言 — 対象スキルの SKILL.md フロントマターに関係を書く: 
    relates_to:
  - { skill: research, type: requires }
  - { skill: pdf-export, type: enables, note: "produces layout spec" }
  2. 検証 — bun scripts/validate-skills.ts(関係形式検査)の後、bun scripts/generate-skill-graph.ts を実行。
  3. 確認 — bun scripts/verify-skill-graph.ts でドリフトなしを確認し、docs/skill-graph.md で当該スキルの関係表を目視確認。
  4. コミット — /sync がステップ4.65で全スコープ再生成・検証を行うため、コミット前にグラフファイルを直接触っていないかだけ確認すればよい。

まだ確信のない関係は、フロントマターではなくオーバーライドファイルに書く。reason と since を残しておけば、90日後にシステムが「まだ観察中か?」と尋ねてくる。

ロードマップ

ADR-0060の Phase 2+ ビジョンは以下のとおり。現時点ではすべて未実装だ。

  • ライフサイクル状態機械 — スキルの draft/active/retired 遷移をグラフノード状態として追跡
  • バージョン管理・マイグレーション — グラフスキーマ版間の移行ツール
  • グラフインテリジェンス — 関係を利用したルーティング提案、コンテキストバンドル自動構成
  • 監査証跡スナップショット — 時点別グラフスナップショットで関係変化の履歴照会

要点は、今の設計がこの拡張を妨げないことだ。グラフは1次ストアではなくプロジェクションなので、消費者を増やしたりノードに状態を足しても、原典とジェネレーターだけ変えればよい。