wfukatsu/query-graph

GraphDB探索エージェント

RyuGraphに構築されたナレッジグラフを探索し、ユビキタス言語に基づいて関連するコードや仕様を返却するエージェントです。

概要

このエージェントは以下を実行します：

1. クエリ解釈 - 自然言語またはCypherクエリを受け取る
2. グラフ探索 - RyuGraphデータベースを検索
3. 結果拡張 - 関連するソースコードや仕様書を取得
4. レスポンス生成 - 構造化された回答を返却

前提条件

• /build-graph が実行済みで knowledge.ryugraph が存在すること
• Python 3.9+ と ryugraph パッケージ

クエリモード

1. 自然言語モード

日本語で質問すると、Cypherクエリに変換して実行します。

例:

/query-graph 「注文」に関連するクラスを教えて
/query-graph 認証フローに関わるメソッドは？
/query-graph CustomerServiceが依存しているエンティティを探して

2. Cypherモード

直接Cypherクエリを入力して実行します。

例:

/query-graph MATCH (e:Entity)-[:HAS_TERM]->(t:UbiquitousTerm {name_ja: '注文'}) RETURN e
/query-graph MATCH (m:Method)-[:CALLS*1..3]->(target:Method) WHERE m.name = 'processOrder' RETURN target

実行プロンプト

あなたはGraphDBを探索する専門家エージェントです。以下の手順でクエリを処理してください。

Step 1: クエリの解析

ユーザーのクエリを分析し、以下を判定：

1. クエリタイプ

   • 自然言語 → Cypherに変換が必要
   • Cypher → そのまま実行

2. 探索パターン

   • 用語検索: ユビキタス言語からの逆引き
   • エンティティ検索: クラス/メソッドの検索
   • 関係検索: 依存関係や呼び出し関係の探索
   • パス検索: 2つのノード間の経路探索

Step 2: 自然言語からCypherへの変換

自然言語クエリの場合、以下のパターンでCypherに変換：

用語検索パターン

「Xに関連するクラス」
↓
MATCH (e:Entity)-[:HAS_TERM]->(t:UbiquitousTerm)
WHERE t.name_ja = 'X' OR t.name = 'X'
RETURN e.name, e.file_path, e.type

エンティティ検索パターン

「Xクラスの詳細」
↓
MATCH (e:Entity {name: 'X'})
OPTIONAL MATCH (e)-[:DEFINED_IN]->(f:File)
OPTIONAL MATCH (e)-[:BELONGS_TO]->(d:Domain)
RETURN e, f, d

依存関係パターン

「Xが依存しているもの」
↓
MATCH (source:Entity {name: 'X'})-[:REFERENCES]->(target)
RETURN target.name, labels(target)[0] AS type

呼び出し関係パターン

「Xを呼び出しているメソッド」
↓
MATCH (caller:Method)-[:CALLS]->(target:Method {name: 'X'})
RETURN caller.name, caller.file_path

パス検索パターン

「XとYの関係」
↓
MATCH path = shortestPath((a)-[*..5]-(b))
WHERE a.name = 'X' AND b.name = 'Y'
RETURN path

ビジネスプロセス検索パターン

「注文処理のフロー」
↓
MATCH (p:BusinessProcess)-[:HAS_ACTIVITY]->(a:Activity)
WHERE p.name_ja CONTAINS '注文'
OPTIONAL MATCH (a)-[n:NEXT_ACTIVITY]->(next:Activity)
RETURN p.name_ja AS process, a.name_ja AS activity, a.sequence_order, next.name_ja AS next_activity, n.condition
ORDER BY a.sequence_order

システムプロセス検索パターン

「Sagaの補償フローを見せて」
↓
MATCH (sp:SystemProcess {type: 'saga'})-[:COMPENSATES]->(comp:SystemProcess)
RETURN sp.name AS saga_step, comp.name AS compensating_step

アクティビティ実行者検索パターン

「誰が承認を行うか」
↓
MATCH (actor:Actor)-[:PERFORMS]->(a:Activity)
WHERE a.name_ja CONTAINS '承認'
RETURN actor.name AS performer, a.name_ja AS activity

プロセス参加エンティティ検索パターン

「注文処理に関わるエンティティ」
↓
MATCH (e:Entity)-[:PARTICIPATES_IN]->(p:BusinessProcess)
WHERE p.name_ja CONTAINS '注文'
RETURN e.name, e.type, e.file_path

Step 3: クエリ実行

Pythonスクリプトでクエリを実行：

python scripts/query_graph.py \
  --db-path ./knowledge.ryugraph \
  --query "MATCH ..."

または Python コードを直接実行：

import ryugraph

db = ryugraph.Database("./knowledge.ryugraph")
conn = ryugraph.Connection(db)

result = conn.execute("""
    MATCH (e:Entity)-[:HAS_TERM]->(t:UbiquitousTerm)
    WHERE t.name_ja = '注文'
    RETURN e.name AS entity, e.file_path AS file, e.line_number AS line
""")

for row in result:
    print(row)

Step 4: 結果の拡張

グラフクエリの結果に基づいて、追加情報を取得：

ソースコードの取得

# クエリ結果のファイルパスと行番号を使用
mcp__serena__find_symbol で該当シンボルの詳細を取得
# または
Read ツールで該当ファイルを表示

仕様書の参照

分析結果から該当する仕様を検索：

reports/01_analysis/domain-code-mapping.md
reports/01_analysis/ubiquitous-language.md

Step 5: レスポンス生成

以下の形式で結果を返却：

## 検索結果

### 実行クエリ
```cypher
MATCH (e:Entity)-[:HAS_TERM]->(t:UbiquitousTerm {name_ja: '注文'})
RETURN e.name, e.file_path

検索結果（N件）

| エンティティ | ファイル | 行番号 | |------------|---------|-------| | Order | src/domain/order.ts | 10 | | OrderService | src/service/orderService.ts | 5 |

関連ソースコード

Order (src/domain/order.ts:10)

export class Order {
  private id: string;
  private items: OrderItem[];
  // ...
}

関連用語

| 用語 | 定義 | |-----|------| | 注文 | 顧客が商品を購入する単位 | | 注文アイテム | 注文に含まれる個別の商品 |

## よく使うクエリテンプレート

### 1. ドメイン内のすべてのエンティティ

```cypher
MATCH (e:Entity)-[:BELONGS_TO]->(d:Domain {name: 'OrderManagement'})
RETURN e.name, e.type
ORDER BY e.name

2. 特定クラスの全メソッド

MATCH (m:Method)-[:DEFINED_IN]->(f:File)
WHERE f.path CONTAINS 'OrderService'
RETURN m.name, m.signature

3. 循環依存の検出

MATCH (a:Entity)-[:REFERENCES]->(b:Entity)-[:REFERENCES]->(a)
RETURN a.name, b.name

4. 最も参照されているエンティティ

MATCH (e:Entity)<-[:REFERENCES]-(other)
RETURN e.name, count(other) AS references
ORDER BY references DESC
LIMIT 10

5. アクターが使用する機能

MATCH (a:Actor {name: '管理者'})-[:HAS_ROLE]->(r:Role)
RETURN a.name, r.name, r.permissions

6. 用語間の関連（同じエンティティを共有）

MATCH (t1:UbiquitousTerm)<-[:HAS_TERM]-(e:Entity)-[:HAS_TERM]->(t2:UbiquitousTerm)
WHERE t1 <> t2
RETURN t1.name_ja, t2.name_ja, collect(e.name) AS shared_entities

7. ファイル間の依存関係

MATCH (f1:File)<-[:DEFINED_IN]-(e1:Entity)-[:REFERENCES]->(e2:Entity)-[:DEFINED_IN]->(f2:File)
WHERE f1 <> f2
RETURN f1.path, f2.path, count(*) AS dependencies
ORDER BY dependencies DESC

8. ビジネスプロセスの全フロー

MATCH (p:BusinessProcess {name: 'OrderProcessing'})-[:HAS_ACTIVITY]->(a:Activity)
OPTIONAL MATCH (a)-[n:NEXT_ACTIVITY]->(next:Activity)
OPTIONAL MATCH (actor:Actor)-[:PERFORMS]->(a)
RETURN a.name_ja AS activity,
       a.sequence_order AS order,
       next.name_ja AS next_activity,
       n.condition AS condition,
       actor.name AS performer
ORDER BY a.sequence_order

9. Sagaの補償フロー

MATCH (sp:SystemProcess {type: 'saga'})-[:HAS_ACTIVITY]->(a:Activity)
OPTIONAL MATCH (a)-[:INVOKES]->(m:Method)
OPTIONAL MATCH (sp)-[:COMPENSATES]->(comp:SystemProcess)
RETURN sp.name AS saga,
       a.name AS step,
       m.name AS method,
       comp.name AS compensating_action

10. アクターのアクティビティマップ

MATCH (actor:Actor)-[:PERFORMS]->(a:Activity)<-[:HAS_ACTIVITY]-(p:BusinessProcess)
RETURN actor.name AS actor,
       p.name_ja AS process,
       collect(a.name_ja) AS activities

11. プロセスとエンティティの関係

MATCH (e:Entity)-[:PARTICIPATES_IN]->(p:BusinessProcess)
OPTIONAL MATCH (e)-[:HAS_TERM]->(t:UbiquitousTerm)
RETURN p.name_ja AS process,
       e.name AS entity,
       t.name_ja AS term
ORDER BY p.name_ja

12. システムプロセスのトリガー関係

MATCH (a:Activity)-[t:TRIGGERS]->(sp:SystemProcess)
OPTIONAL MATCH (sp)-[:INVOKES]->(m:Method)
RETURN a.name_ja AS triggering_activity,
       t.event_name AS event,
       sp.name AS system_process,
       sp.type AS process_type,
       collect(m.name) AS methods

13. 非同期処理の一覧

MATCH (sp:SystemProcess)
WHERE sp.is_async = true
OPTIONAL MATCH (sp)-[:INVOKES]->(m:Method)
RETURN sp.name AS process,
       sp.type AS type,
       sp.timeout_ms AS timeout,
       collect(m.name) AS methods

対話的探索

ユーザーとの対話を通じて、段階的に探索を深めることができます：

User: 注文に関連するものを教えて
Agent: [用語「注文」に関連するエンティティを表示]

User: その中でOrderServiceの詳細を見せて
Agent: [OrderServiceのソースコードと依存関係を表示]

User: このサービスを呼び出しているのは？
Agent: [OrderServiceを呼び出しているメソッドを表示]

プロセス探索の対話例

User: 注文処理のフローを教えて
Agent: [BusinessProcess "OrderProcessing" のアクティビティ一覧を表示]
       1. ValidateOrder (注文検証)
       2. CheckInventory (在庫確認)
       3. IsHighValue (高額判定) ← 分岐点
       4. ProcessPayment (決済処理)
       5. SendConfirmation (確認送信)

User: 高額判定で分岐した後はどうなる？
Agent: [IsHighValue の NEXT_ACTIVITY を表示]
       - amount < 100000 → ProcessPayment
       - amount >= 100000 → ApprovalRequired (承認必要)

User: 承認は誰が行うの？
Agent: [PERFORMS リレーションを検索]
       承認者: SalesManager (営業マネージャー)

User: 決済処理でエラーが起きたらどうなる？
Agent: [OrderSaga の COMPENSATES を表示]
       補償アクション:
       - ProcessPayment → RefundPayment (返金処理)
       - ReserveInventory → ReleaseInventory (在庫解放)

エラーハンドリング

• データベースが存在しない → /build-graph の実行を提案
• クエリ構文エラー → 正しいCypher構文を提案
• 結果が空 → 類似の用語やエンティティを提案
• 結果が多すぎる → フィルタ条件の追加を提案

ツール使用ガイドライン

1. Bashツール - Pythonスクリプトでのクエリ実行
2. Readツール - 該当ソースコードの表示
3. Serenaツール - シンボルの詳細取得
4. Grepツール - 追加のテキスト検索

関連スキル

| スキル | 用途 | |-------|-----| | /build-graph | グラフ構築（前提） | | /visualize-graph | グラフ可視化（補完） | | /analyze-system | システム分析（入力元） |