mcpField
U
understand-onboard

understand-onboard

github.com/egonex-ai開発88.8k3.8k 回インストール3 日前に更新
リポジトリ

understand-onboard について

understand-onboardは、プロジェクトのナレッジグラフからオンボーディングガイドを作成するスキルです。新しく参加する開発者向けに、アーキテクチャ、主要ファイル、概念、ツアー、複雑な領域をまとめます。

主な機能

  1. 01グラフのメタデータからガイド作成
  2. 02アーキテクチャをレイヤー別に整理
  3. 03主要ファイルと概念の要約
  4. 04ツアーと複雑度の高い箇所を掲載
  5. 05Gitとの比較によるグラフの鮮度確認

活用シーン

  1. 01開発者のプロジェクト理解を支援
  2. 02主要ファイルとアーキテクチャ層の対応付け
  3. 03変更前に複雑な領域を把握

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/egonex-ai/understand-anything --skill understand-onboard

インストール後、Claude Code で/understand-onboardを入力して読み込まれたか確認します。

詳細

/understand-onboard

プロジェクトのナレッジグラフから、包括的なオンボーディングガイドを生成します。

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

ナレッジグラフ 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 の差分に使用する前にコミットとして解決し、その後 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. レイヤーを読み取ります。 "layers" を Grep して、レイヤーの配列全体を取得します。これらはアーキテクチャを定義し、ガイドの構成にも使用します。

  5. ツアーを読み取ります。 "tour" を Grep して、ガイド付きウォークスルーの手順を取得します。これらは推奨される学習経路を示します。

  6. ファイルレベルの構造ノードだけを読み取ります。 Grep を使い、ナレッジグラフ内でファイルレベルのタイプ（file、config、document、service、pipeline、table、schema、resource、endpoint）を持つノードを検索します。ガイドを大まかな内容に保つため、関数レベルとクラスレベルのノードは省きます。各ノードの name、filePath、summary、complexity を抽出します。

  7. 複雑さの高い箇所を特定します。 ファイルレベルのノードのうち、complexity の値が最も高いものを探します。これらは、新しい開発者が慎重に取り組むべき領域です。

  8. オンボーディングガイドを生成します。 次のセクションを含めます。

    • プロジェクト概要：名前、言語、フレームワーク、説明（プロジェクトのメタデータから）
    • アーキテクチャレイヤー：各レイヤーの名前、説明、主要なファイル（レイヤーとファイルノードから）
    • 主要な概念：重要なパターンと設計上の決定（ノードの概要とタグから）
    • ガイド付きツアー：手順に沿ったウォークスルー（tour セクションから）
    • ファイルマップ：各主要ファイルの役割（ファイルレベルのノードから。レイヤー別に整理）
    • 複雑さの高い箇所：慎重に取り組むべき領域（複雑さの値から）

  9. 見やすい Markdown 形式にします。

  10. ガイドをプロジェクト内の docs/UA_ONBOARDING.md に保存するか、ユーザーに確認します。

  11. チームで共有できるよう、ガイドをリポジトリにコミットすることをユーザーに提案します。

コメント

Markdown 対応