project-understanding

プロジェクトの理解

概要

Tree-sitter によるインデックス作成と PUI コマンドを通じて、リポジトリの情報を自動的に把握します。基本原則は、一度インデックスを作成したら、手作業で grep する代わりに、目的を絞ったパック（repomap／find／zoom／impact）を使うことです。

使用する場面

• 新しいコードベースに取り組むとき： 構造とエントリーポイントを素早く把握する
• リファクタリングやホットフィックスを計画するとき： 呼び出し元を見つけ、影響範囲を評価する
• コンテキストの予算を調整するとき： リポジトリの要約を LLM のトークン上限内に収める
• 時間に追われているとき： 間接的な依存関係の見落としを減らす
• 検証するとき： 変更がアーキテクチャ上の境界に違反していないことを確認する

使用しない場面

• 小規模なリポジトリ： インデックスを作成するより、手作業で読むほうが速い場合
• サポート対象外の言語： シンボルグラフに依存しないでください（skills/project-understanding/references/LANG_SUPPORT.md を参照）

言語サポート（最初にお読みください）

• シンボル／呼び出しグラフの完全なサポート： Python、JavaScript、TypeScript、Go、Rust
• C/C++： 主にファイル単位の結果が表示されます。zoom／graph では「Symbol not found」と表示される場合があります
• 参照先： skills/project-understanding/references/LANG_SUPPORT.md

コマンドのガードレール（例外なし）

• リポジトリは作業ディレクトリで選択します。 --repo フラグはありません。
• 対象リポジトリから必ず "$PUI" を呼び出してください。 対象リポジトリ内で ./scripts/pui.sh を実行しないでください。
• zoom の対象は位置引数です。 --target フラグや --file フラグはありません。
• zoom はファイルパスを受け付けません。 シンボル ID／名前、または file:line を使用してください。

基本的なワークフロー

1. ツールのパスを一度だけ設定します： PUI="/path/to/skills/project-understanding/scripts/pui.sh"（Windows では pui.ps1 を使用）。対象リポジトリから ./scripts/pui.sh を実行しないでください。
2. リポジトリのルートから実行します（--repo フラグなし）：
   • "$PUI" index（または、大きな変更の後は "$PUI" index build）
   • "$PUI" repomap --depth 2 --max-tokens auto
3. シンボルを見つけます：
   • "$PUI" find "SymbolName" でシンボル ID を取得します（一般的な名前を推測して指定しないでください）
   • "$PUI" zoom <symbol-id|name|file:line>（ファイルパスだけを指定すると失敗します）
   • "$PUI" graph --symbol <symbol-id|name> --depth 2
4. 影響を評価します：
   • "$PUI" impact --files path/to/file --include-tests
   • "$PUI" impact --git-diff HEAD~1..HEAD

例（Lean Boost）

project-understanding-skill リポジトリのルートから実行します：

PUI="$(pwd)/skills/project-understanding/scripts/pui.sh"
cd ./codebases/lean-boost

"$PUI" index
"$PUI" repomap --depth 3 --max-tokens 1200
"$PUI" find "services_manager"
"$PUI" graph --symbol 70 --depth 1 --format mermaid
"$PUI" impact --files src/uninstall/leftovers_scanner.cpp --max-tokens 800

インストール

このスキルはすぐに使用できます。初回実行時に、共有仮想環境が ~/.local/share/pui/venv（またはローカルのフォールバック先）に自動で構築されます。リポジトリのインデックスは、プロジェクトのルートにある .pui/ に保存されます。

クイックリファレンス

コマンド	用途	主なフラグ
index	インデックスの作成／更新	build、--force
repomap	ディレクトリと主要ファイル	--depth、--max-tokens
find	シンボル検索	--limit、--format
zoom	シンボルの詳細	--max-tokens
graph	呼び出し／依存関係グラフ	--symbol、--depth
impact	影響範囲の分析	--files、--git-diff、--include-tests
architecture	アーキテクチャの概要	--format
depgraph	モジュール依存関係グラフ	--scope、--format

使用上の注意：

• zoom の対象は位置引数です。--target フラグはありません。
• zoom はファイルパスを受け付けません。シンボル ID／名前、または file:line を使用してください。
• シンボル ID がわからない場合は、最初に find を使用してください。

影響分析の信頼度

スコア	意味	対応
0.9+	確実に一致	信頼して進める
0.7-0.9	一致の可能性が高い（インポート）	手動で確認する
<0.7	ヒューリスティック／動的	手がかりとして扱う

信頼度の指標が有効なのは、シンボル抽出に対応している言語に限られます。

よくある間違い

• スクリプトのパスが間違っている： リポジトリのルートから ./scripts/pui.sh を実行しても失敗します。絶対パスを使うか、PUI=... を指定してください。
• インデックス作成を省略する： コマンドが失敗したり、古いデータが表示されたりします。定期的に index を使い、完全に再構築する場合は index build を使ってください。
• ズーム対象が間違っている： zoom にはシンボル ID／名前、または file:line が必要です。--target フラグはありません。
• シンボルを推測する： 特に大規模なリポジトリでは、zoom／graph の前に find を実行してください。
• フラグを勝手に作る： --repo フラグはありません。対象のリポジトリに cd して設定してください。
• C/C++ のシンボルグラフがあると思い込む： まず skills/project-understanding/references/LANG_SUPPORT.md を確認してください。
• 予算を考慮しない： 大規模なリポマップでは 20k 以上のトークンを消費することがあります。--depth または --max-tokens を使ってください。

よくある正当化と実情

言い訳	実情
「インポートを grep すればいい」	grep では間接的な依存関係を見落とします。インデックス作成後は impact のほうが正確です。
「フォルダー名を見れば構造は明らかだ」	フォルダー名は依存関係グラフではありません。repomap と graph を使ってください。
「インデックス作成に時間がかかりすぎる」	インデックスは差分更新されます。手作業で追跡するほうが遅く、リスクも高くなります。
「このツールを使ったことがないから、使わずに済ませよう」	初回の実行コストは一度きりです。その後は find と impact で時間を節約できます。
「大きなファイルをそのまま読めばいい」	600 行を超えるファイルを読むと、トークンと集中力を消費します。zoom を使えば重要なロジックだけを確認できます。
「ツールはここの ./scripts にあるはずだ」	スクリプトはスキルディレクトリにあります。まず PUI を設定してください。
「ファイルパスを指定して zoom できる」	zoom にはシンボル ID／名前、または file:line が必要です。ファイルパスだけでは失敗します。

警告サイン — 停止してインデックスを作成

• 手作業での grep だけを根拠に、影響の概要を公開しようとしている。
• フォルダー名からアーキテクチャを推測している。
• 「Symbol not found」と表示されたのに、言語サポートや find を確認せずに作業を続けている。
• 対象のリポジトリ内で ./scripts/pui.sh を実行しようとしている。
• zoom にファイルパスを渡そうとしている。
• 2 ファイルを超えてインポートを手作業で追跡している。
• 大きなコードブロックでコンテキストウィンドウの上限に達している。

これらはいずれも、まず index を実行し、repomap／find／impact を使うか、言語サポートを確認する必要があることを示しています。