codebase-domain-map

コードベースのドメインマップ

概要

リポジトリ内で再生成できる、「何がどこにあるか」を示すスナップショットです。.claude/project-snapshot/ 以下の2つの小さなファイルを一度読むだけで、ドメイン／フォルダー単位で全体を把握できます。毎回 find／grep でモジュールマップを調べ直す必要はありません。まずこれを読み、調べる場所を絞り込んでから、通常の検索ツールを使って絞り込んだ範囲内で実際の行レベルの答えを探します。

これは、作業するすべてのリポジトリに適用されます。.claude/project-snapshot/ がすでにあるリポジトリだけに限らず、各プロジェクト独自の CLAUDE.md／ルールに「プロジェクトスナップショット」についてどのように書かれているかにも左右されません。 プロジェクト独自のルールで、同じ名前の生成済みスナップショットを読むよう指示されている場合もあります。そのプロジェクト固有の指示は、この汎用的で持ち運び可能な手法の一例であり、全体ではありません。このスキルは、それとは別に常時適用されるものです。そのようなルールがないリポジトリを含め、あらゆるリポジトリで適用されます。現在のリポジトリにスナップショットがない場合は、（セットアップの手順に従って）生成するのが正しい対応です。プロジェクト固有のルールで使うよう指示されていないからといって、この手法を省略してはいけません。

要注意事項 — 省略しないでください

考え	実際のところ
「このプロジェクトには別のリポジトリ用の『プロジェクトスナップショット』に関するルールがあるから、ここでは関係ない」	そのルールとこのスキルは別物です。このスキルは、対応するプロジェクトルールの有無にかかわらず、あらゆるリポジトリで使える汎用的な手法です。似た名前のプロジェクトルールがあるからといって、このスキルが適用されるか確認するのを忘れないでください
「ここには .claude/project-snapshot/ がないから、使えない」	ない場合は省略するのではなく生成します。そのためのスクリプトが同梱されています
「これは他人の／見慣れないリポジトリで、自分のものではない」	見慣れないリポジトリこそ、この手法が役立つ場面です。事前に把握している必要はありません
「今すぐ grep するほうが速い」	セットアップはスクリプトを1回実行するだけです。ファイルが数個を超えるリポジトリで、事前に把握せず grep するほうが時間がかかります。しかも、新しいエージェントがまず選びがちなやり方でもあります。このスキルは、その失敗を防ぐためのものです

絞り込める範囲と、絞り込めない範囲： ドメイン／アプリ／フォルダーの粒度に限られます。行やシンボル単位の結果は得られません。スナップショットでフォルダーが示された後も、実際の内容を調べるには、その中で grep／読み取りを行ってください。

使用するタイミング

• 「X がどこにあるか探す」「Y を所有するアプリはどれか」「Z のファイルを見つける」といったタスクでは、find／grep／Explore／調査サブエージェントを使う前に参照してください。
• 自分だけでなく、タスクを委任するすべてのエージェントが対象です： サブエージェントにコードベースの調査を委任するときは、まず自分でスナップショットを読み、絞り込んだドメイン／パスをそのままサブエージェントのプロンプトに渡してください（例：「auth ドメイン：バックエンド — apps/api/src/app/auth、フロントエンド — apps/web/src/pages/auth」）。スナップショットを使って事前に範囲を絞らず、「X のコードを探して」とだけ伝えるプロンプトでは、すでに無料で得られたドメインマップをサブエージェントに一から調べ直させることになります。
• ファイルパスが1つに特定できている場合や、ls の出力を直接読めるほど小さなリポジトリでは必要ありません。

ファイル

• .claude/project-snapshot/overview.md — プロジェクトごとのドメイン一覧とエントリーポイントを、人が読みやすい形式で記載します。
• .claude/project-snapshot/domains.tsv — scope\ttype\tname\tpath 形式のフラットなテーブルです。複数のプロジェクトを横断してキーワードを grep する際に最も速く使えます。

ファイル一覧全体は意図的に含めていません。すぐに古くなって差分がノイズになりやすく、ファイル単位の検索には glob、rg --files、または IDE のファイル検索を使えるためです。

セットアップ／更新

同梱のスクリプトを使って生成または更新します。Nx 形式（apps/+libs/）、Go／Rust 形式（cmd/、internal/、crates/）、フラットなリポジトリのいずれでも動作します。コンテナディレクトリの有無を自動検出し、存在しない場合はトップレベルのディレクトリにフォールバックします。

bash <skill-dir>/scripts/update-project-snapshot.sh          # repo root = git toplevel (or cwd)
bash <skill-dir>/scripts/update-project-snapshot.sh /path/to/repo   # explicit root

新しいアプリ／パッケージ／ドメインを追加したら、スクリプトを再実行してください。新しいドメインが欠けた古いスナップショットは、スナップショットがないよりも悪い状態です（気づかないまま誤検出が起き、検索結果が「探す場所が違う」ではなく「ここには何もない」になってしまいます）。チームでこの規約を共有する場合は生成したファイルをコミットし、そうでない場合はローカルに保管してください。

よくある間違い

間違い	対処法
スナップショットを確認せずにリポジトリ全体を grep する	まず overview.md／grep domains.tsv を確認します。ファイルは1つだけで、検索ではありません
絞り込んだパスを指定せず、「X を見つけて」と調査サブエージェントに指示する	自分でスナップショットを読み、特定したドメイン／パスをサブエージェントのプロンプトに渡します
スナップショットを行単位の検索として扱う	フォルダー単位のみです。実際の答えを見つけるには、絞り込んだフォルダー内でも引き続き grep／読み込みを行います
新しいアプリ／ドメインを追加した後、生成し直さない	スクリプトを再実行します。古いスナップショットは、単に古いだけでなく、誤検出を招きます