understand-chat

/understand-chat

プロジェクトのデータディレクトリにあるナレッジグラフ（.ua/knowledge-graph.json、またはそのディレクトリが存在する場合はレガシー版の.understand-anything/knowledge-graph.json）を使って、このコードベースに関する質問に回答します。

グラフ構造のリファレンス

ナレッジグラフのJSONは、次の構造になっています。

• project — {name, description, languages, frameworks, analyzedAt, gitCommitHash}
• nodes[] — 各ノードは{ id, type, name, filePath?, summary, tags[], complexity, languageNotes? }を持ちます
  • コードノードのタイプ：file、function、class、module、concept
  • 非コードノードのタイプ：config、document、service、table、endpoint、pipeline、schema、resource
  • ドメイン／ナレッジノードのタイプ：domain、flow、step、article、entity、topic、claim、source
  • IDにはノードタイプが接頭辞として使われます（例：file:path、function:path:name、config:path、article:path）
• edges[] — 各エッジは{ source, target, type, direction, weight }を持ちます
  • 主なタイプ：imports、contains、calls、depends_on、configures、documents、deploys、triggers、contains_flow、flow_step、related、cites
• layers[] — 各レイヤーは{ id, name, description, nodeIds[] }を持ちます
• tour[] — 各ツアー項目は{ order, title, description, nodeIds[] }を持ちます

効率的な読み取り方

1. ファイル全体を読む前に、Grepを使ってJSON内の関連項目を検索します
2. 必要なセクションだけを読み、グラフ全体をコンテキストに読み込まないでください
3. ノード名と要約は、内容を理解するうえで最も役立つフィールドです
4. エッジはコンポーネント間のつながりを示します。依存関係の連鎖をたどるには、importsとcallsを追ってください

Instructions

1. データディレクトリ $UA_DIR を解決します。 UA_DIR=$([ -d .understand-anything ] && echo .understand-anything || echo .ua) を実行します。すでに存在する場合は従来の .understand-anything/、それ以外の場合は新しい .ua/ です。現在のプロジェクトルートに $UA_DIR/knowledge-graph.json が存在することを確認してください。存在しない場合は、まず /understand を実行するようユーザーに伝えてください。

2. グラフから得たコンテキストを使う前に、グラフが最新か確認します：

   • グラフのメタデータから project.gitCommitHash を GRAPH_COMMIT_RAW として読み取ります。Git diff で使用する前にコミットとして解決し、git rev-parse HEAD と比較したうえで、プロジェクトルートからプロジェクトに関係するコミット済みの変更と作業ツリーの変更を確認します：

     GRAPH_COMMIT=$(git rev-parse --verify --end-of-options "${GRAPH_COMMIT_RAW}^{commit}" 2>/dev/null)
     git rev-parse HEAD
     git diff --name-only "$GRAPH_COMMIT" HEAD -- .
     git diff --cached --name-only -- .
     git diff --name-only -- .
     git ls-files --others --exclude-standard -- .
     

   • -- . のパス指定は必須です。モノレポ内の兄弟プロジェクトだけに変更がある場合、このグラフを古いと判断してはいけません。ハッシュが一致しなくても、プロジェクトの差分が空なら古くありません。
   • 選択したデータディレクトリ（.ua/ または従来の .understand-anything/）には生成されたグラフの成果物が含まれ、プロジェクトソースの変更ではないため、すべてのコマンド出力から除外します。
   • コミット済み差分、または作業ツリーを確認するいずれかのコマンドでプロジェクトのファイルが報告された場合は、回答する前に、グラフから得たコンテキストに変更が反映されていない可能性があることを警告します。次の実行を提案します：グラフを更新するには /understand を実行してください。
   • GRAPH_COMMIT_RAW が正常に解決できた場合に限り、コミット差分を確認します。グラフのコミットまたは Git メタデータが欠落している、無効である、または利用できない場合は、簡潔にベストエフォートで警告してから処理を続け、ブロックしないでください。

3. プロジェクトのメタデータのみを読み取ります — Grep または Read を行数制限付きで使い、コンテキストとしてファイル冒頭の "project" セクション（名前、説明、言語、フレームワーク）のみを抽出します。

4. 関連ノードを検索します — ナレッジグラフファイル内で、ユーザーのクエリキーワード "$ARGUMENTS" を Grep で検索します。

   • "name" フィールドを検索します：グラフファイル内で grep -i "query_keyword" を実行します。
   • 意味的に一致するものを "summary" フィールドで検索します。
   • トピックに一致するものを "tags" 配列で検索します。
   • 一致するすべてのノードの id 値を記録します。

5. 接続されたエッジを確認します — 一致した各ノード ID について、edges セクション内でその ID を Grep し、次を確認します：

   • そのノードがインポートまたは依存するもの（下流）
   • そのノードを呼び出す、またはインポートするもの（上流）
   • これにより、クエリの周囲にある1ホップの部分グラフが得られます。

6. レイヤーのコンテキストを読み取ります — "layers" を Grep し、一致したノードがどのアーキテクチャレイヤーに属するかを把握します。

7. 関連する部分グラフのみを使って、クエリに回答します：

   • グラフ内の具体的なファイル、関数、関係性を示します。
   • 関連するレイヤーと、その理由を説明します。
   • 簡潔かつ十分に説明し、概念を実際のコードの場所と結び付けます。
   • クエリに一致するノードがない場合は、その旨を伝え、グラフ内の関連する用語を提案します。