code-understand

Code Understand — オンデマンドのアーキテクチャ重点マップ

まだよく知らないコードベースで作業しようとしています。grep であちこちを探したり、ファイルを無作為に読んだりする代わりに、ローカルの抽出ツールに重点マップを依頼してください。これは、アーキテクチャを支えるシンボルを重要度順に並べ、それぞれに file:line の引用と根拠の種類を付けたものです。マップが示す箇所だけを読んでください。これはマップであり、引用されたコードそのものを読む代わりにはなりません。

どんなときに使うか

• まだ詳しく知らないモジュールを編集する前に、構造を変える前に何が呼び出していて、何を呼び出しているかを確認します。
• wiki ではなくコードベースについて、「X はどのように動くのか」「Y を変更するとどのような影響があるか」「この関数をほかに使っている箇所はどこか」とユーザーから尋ねられたときに使います。
• 大規模なリファクタリングを行う前に、ツリー全体を読む代わりに、重要度順に並んだ基盤となるファイルのリストを確認したいときに使います。
• すでに差分や変更対象ファイルの一覧があり、変更を終える前に影響範囲を把握したいときに使います。

対象外：wiki 向けにプロジェクトの機能を要約する場合（これは wiki-update の Step 3b で、より大きな同期フローの一部として同じコマンドを呼び出します）。このスキルを直接使うのは、自分の目の前の作業に重点マップが必要な場合に限ります。知識を保存する目的では使わないでください。

実行方法

obsidian-wiki code-understand --project <dir> [--backend auto|builtin|codegraph] \
    [--changed <file>...] [--since <sha>] [--max-symbols N] [--pretty]

• --project — デフォルトは現在のディレクトリです。
• --changed／--since を指定しない場合 — 追跡対象のすべてのファイルをシードにします（プロジェクト全体をスキャン）。
• --changed <file>（複数回指定可能）— 関連するとすでに分かっているファイルを指定してシードにします（例：これから作成する差分に含まれるファイル）。
• --since <sha> — git の参照以降に変更されたファイルすべてをシードにします（例：--since HEAD~5 またはベースブランチ）。
• --backend — auto（デフォルト）は、インストール済みなら CodeGraph を使用し、そうでなければ組み込みの抽出ツールにフォールバックします。依存関係のない方法を使うには builtin を強制し、拡張バックエンドを必須にするには codegraph を指定します（インストールされていない場合は、黙って性能を落とすのではなく、明示的にエラーになります）。
• --max-symbols — 重点マップのサイズ上限です（デフォルトは 50）。手早く全体像をつかむ場合は小さく設定し、十分に調べる場合は大きくしてください。

注意： コマンドが利用できない、またはエラーになる場合は、実行を見送り、通常の調査方法（grep／読み込み）に切り替えてください。これは作業を加速するものであり、依存するものではありません。これを理由に作業を止めないでください。

出力の読み方

1. 根拠の種類が重要です。 backend: codegraph の場合、重点マップの項目は構造上の事実（実際の呼び出しグラフのエッジ）なので、そのまま引用できます。backend: builtin の場合、defines／imports／changed-file の項目は事実ですが、rg-reference の項目はテキストの一致を示すだけです。実際の関連性として扱う前に、ファイルを開いて確認してください。
2. まず、引用されている箇所だけを開いてください。 重点マップが示すのは、どこを読むべきかです。ソース本文は含まれていません。アーキテクチャについて見解を持つ前に、該当する file:line の箇所を読んでください。
3. 自分の出力でも引用してください。 ユーザーにアーキテクチャを説明したり、PR の説明やコミットメッセージに記載したりする場合は、重点マップまたは開いたソースにある (file:lines) の引用を残してください。根拠を示さずに構造を断定しないでください。
4. これはキャッシュであり、成果物ではありません。 生の JSON や .codegraph/ を wiki の保管場所、PR の説明、コミット対象のドキュメントに書き込まないでください。これはプロジェクトのリポジトリ内にある使い捨てのサイドカー（git で無視されます）です。古い出力を永続的なものとして扱うのではなく、次回は新たに実行してください。

CodeGraph がインストールされていない場合

auto／builtin はセットアップなしで引き続き使えます（正規表現 AST 抽出ツールと rg を使用します）。ファイルをまたぐ拡張された呼び出しグラフの根拠が必要で、ユーザーが何かのインストールを許可している場合は、次を実行してください。

npm install -g @colbymchenry/codegraph

または、CODE_UNDERSTANDING_CODEGRAPH_BIN に既存のバイナリを指定してください。ユーザーの許可なくインストールしないでください。まず確認してから、コマンドを再実行してください。

どのバックエンドを明示的に要求するか決める前に、obsidian-wiki doctor --project <dir> を実行して、利用可能な機能を示す code-understanding.* の行（builtin、rg、codegraph、codegraph-index、codegraph-fresh、codegraph-gitignore）を確認してください。