understand-explain

/understand-explain

特定のコードコンポーネントについて、詳細かつ徹底的に説明します。

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

ナレッジグラフの 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 を確認してください

手順

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 -- .
     

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

3. 対象ノードを見つけます — Grep を使って、ナレッジグラフからコンポーネントを検索します：「$ARGUMENTS」

   • ファイルパス（例：src/auth/login.ts）の場合は、"filePath" の一致を検索します。
   • 関数表記（例：src/auth/login.ts:verifyToken）の場合は、ファイルパスで絞り込み、"name" フィールドから関数名を検索します。
   • 正確なノードの id、type、summary、tags、complexity を記録します。

4. 関連するエッジをすべて見つけます — edges セクションで対象ノードの ID を Grep で検索します。

   • "source" の一致 → このノードが呼び出す／インポートする／依存するもの（出方向）
   • "target" の一致 → このノードを呼び出す／インポートする／依存するもの（入方向）
   • 接続先のノード ID とエッジの種類を記録します。

5. 接続先ノードを読み取ります — 手順 4 で見つかった各接続先ノード ID を nodes セクションで Grep し、それぞれの name、summary、type を取得します。これにより、コンポーネントの近傍を把握できます。

6. レイヤーを特定します — "layers" セクションで対象ノードの ID を Grep し、所属するアーキテクチャレイヤーとそのレイヤーの説明を確認します。

7. 実際のソースファイルを読み取ります — 詳細な分析のため、ノードの filePath にあるソースファイルを読み取ります。

8. コンポーネントを文脈に沿って説明します：

   • アーキテクチャにおける役割（どのレイヤーに属するか、なぜ存在するか）
   • 内部構造（contains エッジに基づく、含まれる関数やクラス）
   • 外部との接続（エッジに基づく、インポートするもの、呼び出すもの、依存するもの）
   • データフロー（ソースコードに基づく、入力 → 処理 → 出力）
   • 読者がそのプログラミング言語を知らない可能性を考慮し、わかりやすく説明します。
   • 理解するうえで注目すべきパターン、イディオム、複雑さを取り上げます。