Knowledge Graph スキル

概要

Knowledge Graph (KG) は、コードベース分析から得られた発見を保存する永続的な JSON ファイルで、冗長な探索を排除し、タスク検証を可能にします。

保存場所: docs/specs/[ID-feature]/knowledge-graph.json

主な利点:

• ✅ 既に分析されたコードベースの再探索を回避
• ✅ 実際のコードベース状態に対してタスクの依存関係を検証
• ✅ チームメンバー間で発見を共有
• ✅ キャッシュされたコンテキストを使用してタスク生成を加速

使用する場合

以下の場合にこのスキルを使用します:

1. spec-to-tasks がコードベース分析をキャッシュ/再利用する必要がある場合 - エージェントの発見を将来の再利用のために保存
2. task-implementation がタスク依存関係と契約を検証する必要がある場合 - 実装前に必要なコンポーネントが存在するかを確認
3. 任意のコマンドが既存のパターン/コンポーネント/API をクエリする必要がある場合 - キャッシュされたコードベースコンテキストを取得
4. 冗長なコードベース探索を減らす場合 - 既に探索されたコードの再分析を回避

トリガーフレーズ:

• "Load knowledge graph"
• "Query knowledge graph"
• "Update knowledge graph"
• "Validate against knowledge graph"
• "Check if component exists"
• "Find existing patterns"

手順

利用可能な操作

1. read-knowledge-graph - 仕様用 KG をロードおよび解析

• 入力: spec フォルダへのパス (例: docs/specs/001-feature/)
• 出力: メタデータ、パターン、コンポーネント、API を含む KG オブジェクト

2. query-knowledge-graph - 特定のセクション (コンポーネント、パターン、API) をクエリ

• 入力: spec フォルダ、クエリタイプ、オプションフィルター
• 出力: 条件に一致するフィルター済みの結果

3. update-knowledge-graph - 新しい発見で KG を更新

• 入力: spec フォルダ、更新内容 (部分的な KG)、ソース説明
• 出力: 新しい発見がマージされた KG

4. validate-against-knowledge-graph - KG に対してタスク依存関係を検証

• 入力: spec フォルダ、要件 (コンポーネント、API、パターン)
• 出力: エラー/警告を含む検証レポート

5. validate-contract - タスク間の provides/expects を検証

• 入力: spec フォルダ、expects (ファイル + シンボル)、完了した依存関係
• 出力: 満たされた/満たされていない期待のレポート

6. extract-provides - 実装されたファイルからシンボルを抽出

• 入力: ファイルパスの配列
• 出力: ファイル、シンボル、タイプを含む provides の配列

7. aggregate-knowledge-graphs - すべての spec からパターンをマージ

• 入力: プロジェクトルートパス
• 出力: 重複排除されたパターンを含むグローバル KG

詳細な使用例については references/query-examples.md を参照してください。

例

入力/出力の例

Knowledge Graph を読み込む:

Input: /knowledge-graph read docs/specs/001-hotel-search/
Output: {
  metadata: { spec_id: "001-hotel-search", version: "1.0" },
  patterns: { architectural: [...], conventions: [...] },
  components: { controllers: [...], services: [...]}
}

コンポーネントをクエリ:

Input: /knowledge-graph query docs/specs/001-hotel-search/ components {"category": "services"}
Output: [{ id: "comp-svc-001", name: "HotelSearchService", type: "service"}]

Knowledge Graph を更新:

Input: /knowledge-graph update docs/specs/001-hotel-search/ {
  patterns: { architectural: [{ name: "Repository Pattern"}] }
}
Output: "Added 1 pattern to knowledge graph"

依存関係を検証:

Input: /knowledge-graph validate docs/specs/001-hotel-search/ {
  components: ["comp-repo-001"]
}
Output: { valid: true, errors: [], warnings: [] }

包括的なワークフロー例については references/examples.md を参照してください。

KG スキーマリファレンス

例を含む完全な JSON スキーマについては references/schema.md を参照してください。

統合パターン

Developer Kit コマンドとの詳細な統合については references/integration-patterns.md を参照してください。

エラーハンドリング

包括的なエラーハンドリング戦略と復旧手順については references/error-handling.md を参照してください。

パフォーマンスに関する考慮事項

最適化戦略とパフォーマンス特性については references/performance.md を参照してください。

セキュリティ

セキュリティに関する考慮事項、脅威軽減、ベストプラクティスについては references/security.md を参照してください。

ベストプラクティス

KG をクエリする場合: コードベース分析、タスク生成、依存関係検証の前に

KG を更新する場合: エージェントの発見後、コンポーネント実装後、パターン発見後

KG の鮮度:

• < 7 日: 新鮮
• 7～30 日: 古い、ユーザーに警告

• 30 日: 非常に古い、再生成を提案

詳細なベストプラクティスについては references/performance.md および references/security.md を参照してください。

制約と警告

重要な制約

• ソースコード安全操作: ソースコードファイルを変更しません。knowledge-graph.json ファイルのみを作成/更新します。
• パス検証: docs/specs/[ID]/ パスからのみ KG ファイルを読み込み/書き込みます。
• 自動コード生成なし: 分析結果をキャッシュしますが、実装コードは生成しません。

制限事項

• 検証スコープ: KG にコンポーネントが存在するかをチェックしますが、KG が古い場合は実際のコードベースに存在するかを確認できません
• 鮮度への依存: KG の精度は最後に更新されたときからの経過時間に依存します
• 単一 Spec ファースト: 各 KG は主に単一の仕様に固有です
• ファイルサイズ: KG ファイルは複雑な仕様の場合、非常に大きくなる可能性があります (>1MB)

完全な制約と警告については references/error-handling.md および references/security.md を参照してください。

リファレンスファイル

• schema.md - 完全な JSON スキーマ
• query-examples.md - クエリパターン
• integration-patterns.md - コマンド統合
• error-handling.md - エラーハンドリングガイド
• performance.md - パフォーマンス最適化
• security.md - セキュリティに関する考慮事項
• examples.md - 実践的な例