exploring-codebases

コードベースの探索

不慣れなリポジトリを対象とした探索的なコード分析です。ローカルコピーに対して、tree-sitting（構造分析）と featuring（意味分析）を実行します。

ワークフロー

順番に進める5つのステップです。ステップ0は省略しないでください。

0. セットアップ（セッションごとに1回）

uv venv /home/claude/.venv 2>/dev/null
uv pip install tree-sitter --python /home/claude/.venv/bin/python
export PYTHON=/home/claude/.venv/bin/python
export TREESIT=/mnt/skills/user/tree-sitting/scripts/treesit.py
export GATHER=/mnt/skills/user/featuring/scripts/gather.py

ステップ2の--statsで、コードが含まれていると分かっているリポジトリのSymbols: 0が報告された場合は、tree-sitterコアパッケージがインストールされていません。ここに戻ってインストールしてください（エンジンには独自の文法がバンドルされており、tree-sitter-language-packは使用しません）。 この場合、Treesitは終了コード0で終了し、エラーも出力しないため、シンボルが0であることが唯一の手がかりです。Errors:行はありません。この行は解析失敗時に表示されますが、パーサーが見つからない場合は解析に進みません。詳しくは、tree-sittingスキルの「セットアップ」セクションをご覧ください。

1. リポジトリを取得する（ファイル単位ではなくtarballで）

OWNER=...
REPO=...
REF=main                    # branch name, tag, or SHA. For a PR: pull/N/head
curl -sL -H "Authorization: Bearer $GH_TOKEN" \
  "https://api.github.com/repos/$OWNER/$REPO/tarball/$REF" -o /tmp/$REPO.tar.gz
mkdir -p /tmp/$REPO && tar -xzf /tmp/$REPO.tar.gz -C /tmp/$REPO --strip-components=1
ls /tmp/$REPO | head        # sanity check — did extraction land?

1回のHTTP呼び出しでリポジトリ全体を取得できます。最初にREADMEをcurlしたり、ファイルをcatしたり、contents/PATH経由で取得したりしないでください。これらはtarballに含まれています。Authorizationヘッダーが必要なのはプライベートリポジトリのみです。パブリックリポジトリでは不要です。

参照先の選択は重要です。 フィーチャーブランチ、PR、タグを調べる場合は、それに応じてREFを設定してください。質問が未マージのブランチに関するものなのに、デフォルトのmainを使うと、古いコードが何も通知されずに取得されます。

2. 構造スキャン

$PYTHON $TREESIT /tmp/$REPO --stats

出力を確認します。ファイル数、シンボル数、言語、ディレクトリごとのシンボル密度が示されます。これは方向付けのための成果物です。このステップの準備運動ではなく、成果物として扱ってください。

具体的な疑問がある場合にのみ掘り下げてください。 「このリポジトリは何か」を把握するだけなら、掘り下げは省略してステップ3に進んでください。featuringが興味深い箇所を明らかにします。ユーザーから特定のサブシステムについて質問された場合や、ステップ3の出力からソースを確認する必要のある疑問が生じた場合は、掘り下げてください。

掘り下げる場合は、クエリを1回の呼び出しにまとめてください。 Treesitの呼び出しごとに、スキャン全体のコストがかかります。同じコマンドに複数のクエリを追加すれば、スキャンを共有でき、クエリを追加しても時間は約0msしか増えません。同じパスに対してTreesitを2回目に呼び出そうとしている場合は、最初の呼び出しにまとめてください。

# GOOD — one scan, three answers
$PYTHON $TREESIT /tmp/$REPO --path=SUBDIR --detail=full \
  'find:*Handler*:function' 'source:main' 'refs:Config'

# BAD — three scans, three answers (3× the cost for the same information)
$PYTHON $TREESIT /tmp/$REPO --path=SUBDIR --detail=full
$PYTHON $TREESIT /tmp/$REPO 'find:*Handler*:function'
$PYTHON $TREESIT /tmp/$REPO 'refs:Config'

3. フィーチャーの統合

実行する前に、成果物に応じてモードを選んでください。

成果物	コマンド	サイズ
自分の理解のためのもの — レビュー、概要の把握、質問への回答	--orient	約115行
すべてのシンボルを引用する必要がある、作成済みの_FEATURES.md	full output	数千行

# Default. Complexity assessment, decomposition ranking, directory tree, entry points.
$PYTHON $GATHER /tmp/$REPO --skip tests,.github,node_modules --orient

# Only when you are about to WRITE the inventory into a file:
$PYTHON $GATHER /tmp/$REPO --skip tests,.github,node_modules --source-budget 8000

出力上部付近に「サブファイルの候補領域（シンボル密度順）」の一覧があります。掘り下げる対象を選ぶ際に使ってください。順位も示されています。

出力全体をheadにパイプしないでください。 出力を切り詰めようとしているなら、選ぶべきモードは--orientでした。読まない数千行を出力するためにコストをかけたことになります。あるレビューでは、全体の収集結果が5,697行に達し、120行目で切り詰められました。その中のすべての発見は、実際にはtreesitによる掘り下げと対象を絞った読み取りから得られていました。--orientなら、実際に使われる約115行が返されます。fullモードのシンボル一覧は、読むためではなく引用するためにあります。

4. 統合した出力をもとに考察する

2と3を統合し、機能、フィーチャー群、アーキテクチャ、エントリーポイント、異常点をまとめます。必要に応じて_FEATURES.mdを作成します。ここがLLMによるステップです。それ以前はすべて機械的な処理です。

これを他のスキルと使い分ける場面

状況	使用するもの
「これをクローンしたばかりですが、これは何ですか？」	exploring-codebases（このスキル）
「リトライのロジックはどこにありますか？」	searching-codebases
「class.*Error に一致するファイルをすべて見つけてください」	searching-codebases
「auth.py のシンボルを表示してください」	tree-sitting を直接使用
「CSRF／セッション／クエリセットのフィルタリングに最も関連するファイルはどれですか？」	bm25
「複数語の概念との関連度でドキュメントを順位付けしてください」	bm25
「このコードベースの機能をドキュメント化してください」	featuring を直接使用
「このコードベースについて教えてください」（人間が学習する場合）	orienting-codebases
「このリポジトリを入手したい」—取得のみで、分析は不要	accessing-github-repos, cloning-project

探索は発散型のスキルです。まだ何を探しているのかわからない場合に使います。検索は収束型のスキルです。探しているものがわかっている場合に使います。

orienting-codebases は、同じ tree-sitting と featuring のパイプラインを実行し、このスキルに最も近いカタログ内のスキルです。対象者が異なります。このスキルは作業を進められるよう Claude の理解を深め、もう一方はガイド付き演習と HTML アーティファクトを通じて ユーザー の理解を深めます。教える相手がいない場合は、このスキルが適切です。

このワークフローで bm25 を組み合わせる

手順 2～3 でリポジトリの大まかな構造を把握したら、grep や完全一致するシンボルの検索を超えて関連度順のコンテンツ検索を行いたい場合は、bm25 を組み合わせるのが自然です。複数語のクエリに対する語彙的な関連度でファイルを順位付けするため、「X で検索すると、このコードベースは実際のところ何についてのものなのか？」を調べるのに役立ちます。特に、tree-sitting に渡すシンボル名がまだわからない場合に有用です。

BM25=/mnt/skills/user/bm25/scripts/bm25.py

# Pass multiple queries — index builds once, all queries reuse it
python3 $BM25 /tmp/$REPO 'auth flow' 'session backend' 'middleware pipeline' \
  --exclude 'tests/*' --exclude '*/tests/*' --top-k 5

特に相性のよい使い方は次の 2 つです。

1. bm25 → tree-sitting。 bm25 で概念に関連する上位ファイルを見つけ、その後 tree-sitting source:Symbol:path/to/file.py で実際の実装を読みます。
2. --exclude 'tests/*' を指定して bm25 を使う。 テスト名にはドメイン用語が重複して含まれるため、テストディレクトリがキーワード検索の結果を占めがちです。最初から除外しておけば、実装ファイルにたどり着きやすくなります。

bm25 はコーパスに依存しません。探索対象にドキュメント、トランスクリプト、PDF が含まれる場合は、project ナレッジストアや uploads/ に対しても機能します。

サブエージェントへの委任

リポジトリが大規模（ファイルが 1000 個超、または複数の独立したサブシステムがある）で、かつこの環境でサブエージェントツール（Claude Code と CCotw の Agent／Task）が利用できる場合に限ります。Claude.ai のチャットとスキル単体での実行では利用できないため、手順 2～4 をそのまま実行し、これらの作業は省略してください。ツールがない場合、他の方法で複数のエージェントに処理を振り分けたように見せかけてはいけません。

いずれの場合も、手順 2～3 はそのまま実行します。振り分けるのは手順 4 の判断作業だけで、サブシステムごとに 1 つのエージェントを割り当てます。サブエージェントには何も引き継がれません。会話、このファイル、スキャン成果物がすでにディスク上にあるという情報も引き継がれません。最初のエージェントプロンプトを書く前に references/subagent-delegation.md を読んでください。すべてのプロンプトに含めるべき 4 つの項目と、それらが欠けていた場合に起きることが記載されています。

注意事項

• 大規模なリポジトリ（ファイルが 100 個超）：スキャン対象を絞るため、手順 2 で --skip tests,vendored,docs,... を使用します。
• モノレポ：各パッケージ／サービスを個別に探索します。サブシステムごとに _FEATURES.md ファイルを生成し、ルートインデックスからリンクします。
• 掘り下げのヒューリスティック（手順 2 で掘り下げが妥当な場合）：シンボル数とファイル数の比率が高いディレクトリ（ロジックが密集している）、エントリポイント名（main、cli、app、server、routes）、インポート数が多いファイル（統合ポイント）。