understand-domain

/understand-domain

コードベースからビジネスドメインの知識（ドメイン、ビジネスフロー、プロセスの手順）を抽出し、ダッシュボードにインタラクティブな横方向のフローグラフを生成します。

仕組み

• ナレッジグラフ（.ua/knowledge-graph.json、またはそのディレクトリが存在する場合は旧形式の .understand-anything/knowledge-graph.json）がすでにある場合は、そこからドメイン知識を導き出します（低コストで、ファイルのスキャンは不要です）。
• ナレッジグラフがない場合は、軽量なスキャン（ファイルツリー、エントリポイントの検出、ファイルのサンプリング）を行います。
• --full フラグを指定すると、ナレッジグラフが存在していても新たにスキャンします。

手順

フェーズ 0：PROJECT_ROOT の解決

PROJECT_ROOT を現在の作業ディレクトリに設定します。

Worktree からのリダイレクト。 PROJECT_ROOT が Git worktree（メインのチェックアウトではない）内にある場合は、出力先をメインリポジトリのルートに変更します。Claude Code が管理する worktree は一時的なものです。そこに書き込まれたデータディレクトリ（.ua/ または旧形式の .understand-anything/）はセッション終了時に削除され、ドメイングラフも失われます（issue #133）。git rev-parse --git-dir と git rev-parse --git-common-dir の結果を比較して worktree かどうかを判定します。通常のチェックアウトまたはサブモジュールでは同じパスになり、worktree では異なるパスになり、--git-common-dir の親ディレクトリがメインリポジトリのルートになります。

COMMON_DIR=$(git -C "$PROJECT_ROOT" rev-parse --git-common-dir 2>/dev/null)
GIT_DIR=$(git -C "$PROJECT_ROOT" rev-parse --git-dir 2>/dev/null)
if [ -n "$COMMON_DIR" ] && [ -n "$GIT_DIR" ]; then
  COMMON_ABS=$(cd "$PROJECT_ROOT" && cd "$COMMON_DIR" 2>/dev/null && pwd -P)
  GIT_ABS=$(cd "$PROJECT_ROOT" && cd "$GIT_DIR" 2>/dev/null && pwd -P)
  if [ -n "$COMMON_ABS" ] && [ "$COMMON_ABS" != "$GIT_ABS" ]; then
    MAIN_ROOT=$(dirname "$COMMON_ABS")
    if [ -d "$MAIN_ROOT" ] && [ "${UNDERSTAND_NO_WORKTREE_REDIRECT:-0}" != "1" ]; then
      echo "[understand-domain] Detected git worktree at $PROJECT_ROOT"
      echo "[understand-domain] Redirecting output to main repo root: $MAIN_ROOT"
      echo "[understand-domain] (Set UNDERSTAND_NO_WORKTREE_REDIRECT=1 to keep PROJECT_ROOT as the worktree.)"
      PROJECT_ROOT="$MAIN_ROOT"
    fi
  fi
fi

以降のフェーズで「現在のプロジェクト」または <project-root> を参照する場合は、裸の CWD ではなく $PROJECT_ROOT を使用します。

データディレクトリ $UA_DIR を解決します。 Understand-Anything のすべての成果物は、プロジェクトのデータディレクトリに保存されます。$PROJECT_ROOT が判明したこの時点で一度解決し、以降のフェーズではすべての読み取りと書き込みに $UA_DIR を再利用します。

UA_DIR="$PROJECT_ROOT/$([ -d "$PROJECT_ROOT/.understand-anything" ] && echo .understand-anything || echo .ua)"

これにより、すでに存在する旧形式の .understand-anything/ ディレクトリはそのまま保持されます（既存のプロジェクトは移行せずに引き続き動作します）。存在しない場合は、新しい .ua/ を使用します。各フェーズは新しいシェルで実行される場合があるため、$PROJECT_ROOT と同様に $UA_DIR も引き継ぎます。後続のコマンドブロックで必要になった場合は、上記の行を使って再解決してください。

重要： プラグインのルートが、スキルのパス文字列から単純に 2 階層上のディレクトリにあると想定しないでください。多くのインストール環境では、~/.agents/skills/understand-domain は実際のプラグインのチェックアウト先へのシンボリックリンクです。まず実行時に提供されるプラグインルート（Claude 用）を優先し、次に汎用シンボリックリンク、スキルのシンボリックリンク解決、一般的なクローンベースのインストールパスの順に確認してください。

プラグインのルートは次のように解決します。

SKILL_REAL=$(realpath ~/.agents/skills/understand-domain 2>/dev/null || readlink -f ~/.agents/skills/understand-domain 2>/dev/null || echo "")
SELF_RELATIVE=$([ -n "$SKILL_REAL" ] && cd "$SKILL_REAL/../.." 2>/dev/null && pwd || echo "")
COPILOT_SKILL_REAL=$(realpath ~/.copilot/skills/understand-domain 2>/dev/null || readlink -f ~/.copilot/skills/understand-domain 2>/dev/null || echo "")
COPILOT_SELF_RELATIVE=$([ -n "$COPILOT_SKILL_REAL" ] && cd "$COPILOT_SKILL_REAL/../.." 2>/dev/null && pwd || echo "")

PLUGIN_ROOT=""
for candidate in \
  "${CLAUDE_PLUGIN_ROOT}" \
  "$HOME/.understand-anything-plugin" \
  "$SELF_RELATIVE" \
  "$COPILOT_SELF_RELATIVE" \
  "$HOME/.codex/understand-anything/understand-anything-plugin" \
  "$HOME/.opencode/understand-anything/understand-anything-plugin" \
  "$HOME/.pi/understand-anything/understand-anything-plugin" \
  "$HOME/understand-anything/understand-anything-plugin"; do
  if [ -n "$candidate" ] && [ -f "$candidate/package.json" ] && [ -f "$candidate/pnpm-workspace.yaml" ]; then
    PLUGIN_ROOT="$candidate"
    break
  fi
done

if [ -z "$PLUGIN_ROOT" ]; then
  echo "Error: Cannot find the understand-anything plugin root."
  echo "Checked:"
  echo "  - ${CLAUDE_PLUGIN_ROOT:-<unset CLAUDE_PLUGIN_ROOT>}"
  echo "  - $HOME/.understand-anything-plugin"
  echo "  - ${SELF_RELATIVE:-<unresolved path derived from ~/.agents/skills/understand-domain>}"
  echo "  - ${COPILOT_SELF_RELATIVE:-<unresolved path derived from ~/.copilot/skills/understand-domain>}"
  echo "  - $HOME/.codex/understand-anything/understand-anything-plugin"
  echo "  - $HOME/.opencode/understand-anything/understand-anything-plugin"
  echo "  - $HOME/.pi/understand-anything/understand-anything-plugin"
  echo "  - $HOME/understand-anything/understand-anything-plugin"
  echo "Make sure the plugin is installed correctly."
  exit 1
fi

以降のフェーズでは、エージェント定義を参照する際に $PLUGIN_ROOT を使用します。

フェーズ 1：既存のグラフを検出する

1. $UA_DIR/knowledge-graph.json が存在するか確認します
2. 存在し、かつ --full が渡されていない場合は、そこから派生させる前に最新状態かどうかを確認します。
   • グラフのメタデータから project.gitCommitHash を GRAPH_COMMIT_RAW として読み取ります。$PROJECT_ROOT に移動し、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. この事前確認の後、フェーズ 3（グラフから派生）に進みます。
4. それ以外の場合は、フェーズ 2（軽量スキャン）に進みます。--full が使用された場合は、既存のグラフを使わず新たにスキャンするため、この事前確認をスキップします。

フェーズ 2：軽量スキャン（パス 1）

前処理スクリプトはドメイングラフを生成するのではなく、生データ（ファイルツリー、エントリーポイント、エクスポート／インポート）を生成します。これにより、ドメインアナライザーエージェントは、コードベースを調べるために何十回もツールを呼び出すのではなく、実際のドメイン分析に集中できます。いわばカンニングペーパーです。低コストの Python による前処理で、コストの高い LLM に整理された小さな入力を渡すことで、より低コストでより良い結果が得られます。

1. このスキルに同梱されている前処理スクリプトを実行し、フェーズ 0 の $PROJECT_ROOT を渡します。

   python ./extract-domain-context.py "$PROJECT_ROOT"
   

   これにより、次の内容を含む $UA_DIR/intermediate/domain-context.json が出力されます。
   • ファイルツリー（.gitignore を尊重）
   • 検出されたエントリーポイント（HTTP ルート、CLI コマンド、イベントハンドラー、cron ジョブ、エクスポートされたハンドラー）
   • ファイルシグネチャ（ファイルごとのエクスポート、インポート）
   • 各エントリーポイントのコードスニペット（シグネチャ＋先頭の数行）
   • プロジェクトのメタデータ（package.json、README など）
2. 生成された domain-context.json を読み込み、フェーズ 4 のコンテキストとして使用します。
3. フェーズ 4 に進みます。

フェーズ 3：既存のグラフから派生（パス 2）

1. $UA_DIR/knowledge-graph.json を読み込みます。
2. グラフデータを構造化されたコンテキストとして整形します。
   • すべてのノードと、それぞれのタイプ、名前、概要、タグ
   • すべてのエッジとそのタイプ（特に calls、imports、contains）
   • すべてのレイヤーとその説明
   • 利用可能な場合はツアーのステップ
3. これがドメインアナライザーのコンテキストとなります。ファイルを読み込む必要はありません。
4. フェーズ 4 に進みます。

フェーズ 4：ドメイン分析

1. $PLUGIN_ROOT/agents/domain-analyzer.md からドメインアナライザーエージェントのプロンプトを読み込みます。
2. ドメインアナライザーのプロンプトと、フェーズ 2 または 3 のコンテキストを渡してサブエージェントを起動します。
3. エージェントは出力を $UA_DIR/intermediate/domain-analysis.json に書き込みます。

フェーズ 5：検証と保存

1. ドメイン分析の出力を読み込みます。
2. 標準のグラフ検証パイプラインを使用して検証します（スキーマは domain／flow／step タイプに対応しています）。
3. 検証に失敗した場合は、警告を記録しつつ、有効なデータを保存します（エラー許容）。
4. $UA_DIR/domain-graph.json に保存します。
5. $UA_DIR/intermediate/domain-analysis.json と $UA_DIR/intermediate/domain-context.json を削除します。

フェーズ 6：ダッシュボードを起動する

1. /understand-dashboard を自動的に実行して、ドメイングラフを可視化します
2. ダッシュボードは domain-graph.json を検出し、デフォルトでドメインビューを表示します