knowledge-graph

ナレッジグラフスキル

概要

ナレッジグラフ（KG）は、コードベースの分析で得られた知見を保存する永続的な JSON ファイルです。探索の重複をなくし、タスクの検証を可能にします。

場所：docs/specs/[ID-feature]/knowledge-graph.json

主なメリット：

• ✅ 分析済みのコードベースを再探索せずに済みます
• ✅ 実際のコードベースの状態に照らして、タスクの依存関係を検証できます
• ✅ チームメンバー間で知見を共有できます
• ✅ キャッシュされたコンテキストを使って、タスクの生成を高速化できます

使用するタイミング

次の場合にこのスキルを使用します。

1. spec-to-tasks でコードベースの分析をキャッシュ／再利用する必要がある場合 - エージェントが得た知見を、今後の再利用のために保存します
2. task-implementation でタスクの依存関係や契約を検証する必要がある場合 - 実装前に、必要なコンポーネントが存在するか確認します
3. 既存のパターン／コンポーネント／API を照会するコマンドが必要な場合 - キャッシュされたコードベースのコンテキストを取得します
4. コードベースの探索の重複を減らす場合 - すでに探索済みのコードを再分析しないようにします

トリガーフレーズ：

• 「ナレッジグラフを読み込む」
• 「ナレッジグラフを照会する」
• 「ナレッジグラフを更新する」
• 「ナレッジグラフに照らして検証する」
• 「コンポーネントが存在するか確認する」
• 「既存のパターンを見つける」

手順

利用可能な操作

1. read-knowledge-graph - 仕様の KG を読み込んで解析します

• 入力：仕様フォルダーのパス（例：docs/specs/001-feature/）
• 出力：メタデータ、パターン、コンポーネント、API を含む KG オブジェクト

2. query-knowledge-graph - 特定のセクション（コンポーネント、パターン、API）を照会します

• 入力：仕様フォルダー、照会の種類、任意のフィルター
• 出力：条件に一致するフィルター済みの結果

3. update-knowledge-graph - 新たな知見を KG に反映します

• 入力：仕様フォルダー、更新内容（部分的な KG）、情報源の説明
• 出力：新たな知見を統合した KG

4. validate-against-knowledge-graph - タスクの依存関係を KG に照らして検証します

• 入力：仕様フォルダー、要件（コンポーネント、API、パターン）
• 出力：エラー／警告を含む検証レポート

5. validate-contract - タスク間の provides／expects を検証します

• 入力：仕様フォルダー、expects（ファイルとシンボル）、完了済みの依存タスク
• 出力：満たされた／満たされていない期待のレポート

6. extract-provides - 実装済みファイルからシンボルを抽出します

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

7. aggregate-knowledge-graphs - すべての仕様のパターンを統合します

• 入力：プロジェクトのルートパス
• 出力：重複するパターンを統合したグローバル KG

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

例

入出力の例

ナレッジグラフの読み込み：

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"}]

ナレッジグラフの更新：

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 の正確性は、どれだけ最近更新されたかに左右されます。
• 単一仕様を優先：各 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 - 実践的な例