AIにリポジトリ全体を理解させる方法｜複数ファイルの文脈を渡す

AIに複数fileの文脈を渡すには、対象repositoryと作業対象のapp/packageを確定し、README・入口・設定・schema・project rulesから地図を作ります。その後、今回の変更に関係するfileだけを読み、説明と変更後のdiff・testで理解を確かめます。repositoryを開いただけで全fileや依存関係を完全に理解したとみなすのは危険です。

最初に作業場所を固定する

「repository全体を理解して」と頼む前に、開いたrootを確認します。monorepoなら対象app、package、service、実行scriptを明記します。rootがずれると、AIが別のpackage設定を読み、存在しないtestを提案したり、似た名前のcomponentを修正したりします。

最初に確認する項目

・対象repositoryとbranch。

・monorepo内の対象app/packageと起動方法。

・READMEと開発手順。

・package.jsonやbuild設定などの入口。

・route、API、data model、schema。

・AGENTS.mdやCursor Rulesなど、作業範囲にかかる指示。

・関連testと、変更前に通る状態。

全部のfileを一度に開くのではなく、入口を見つけて依存を追う地図です。READMEに書かれたコマンドが古い場合もあるため、実際のpackage設定と照らします。

AIに渡すRepository Mapの依頼例

「このrepositoryの[app/package]が対象です。README、entrypoint、package設定、routing、data schema、関連rulesを確認してください。まず起動から主要画面・API・保存先までのdata flowを説明し、今回の変更に関係するfileを列挙してください。まだ編集しないでください。確認できなかった範囲、推測、矛盾する記述を別に示してください。」

返答は網羅感ではなく検証可能性で見ます。重要な説明にfile pathや設定名があり、実際のentrypointやtestと一致するか確認します。「ログイン後にAPIへ送る」なら、画面handler、API route、認証middleware、保存処理の順にたどれるかを見ます。

作業単位で文脈を渡す

Repository Mapの後、今回のJobに必要なfileへ絞ります。変更を頼むときは目的、変更しない領域、入力・出力、受け入れ条件、関連testを一緒に渡します。

例：「顧客一覧に次回日付を表示します。対象はapps/webの一覧componentとqueryです。API contractとDB schemaは変更しません。未設定なら『未設定』と表示します。権限がない利用者へdataを返さないこと。該当testを更新し、diffを説明してください。」

taskごとに必要な文脈は変わります。過去の会話説明をrepositoryの現状と混同せず、入口や設定を作業時点で確かめます。作業対象外のserviceまで変更していないかもdiffで見ます。

IndexingとRulesは補助

Cursorのcodebase indexingは関連コードの検索を助けますが、全fileを読んだ証拠ではありません。対象外に設定されたfileは検索されないことがあり、ignore設定やindex更新状況で見える範囲が変わります。秘密情報や巨大fileを不用意にindexへ追加しないでください。必要なfileが対象外なら、理由と安全性を確かめたうえで限定的に参照します。

Rulesは繰り返し使う制約や開発手順を伝えるものです。rulesがあることだけで内容が適用されたと判断せず、今回関係するrulesを読み、AIの説明に反映されているか確認します。矛盾する指示があれば、正本や対象範囲を示し、勝手に片方を選ばないようにします。

関連fileをたどる方法

画面表示の変更ならroute、component、data取得、型、関連testを確認します。保存処理ならform、API、validation、権限、database access、error handlingを見ます。設定変更なら、設定を読む場所とbuild/runtime両方の影響を調べます。fileを列挙するだけではなく、「このfileはresponse型」「このtestは閲覧権限を検証」のように役割を一言添えます。

検索に出ないfileがあるときは、ignore設定、generated directory、別workspace root、未保存fileを確認します。無差別に全repositoryを読ませる前に、正確なpathやsymbolで検索します。似た名称の旧実装が残っている場合は、build設定がどちらを使うか確かめます。

依存関係の説明を検証する

AIの説明は次の問いで点検します。

・実際のentrypointから説明をたどれるか。

・同じ機能の旧版や別packageを混同していないか。

・dataの読み込みと更新がどのfileを通るか。

・認証・権限・validationが画面以外にもあるか。

・build時とruntimeで参照するconfigが異なるか。

・generated fileを直接編集しようとしていないか。

・testがどの挙動を保証し、何を見ていないか。

「理解した」という一言で判断せず、taskに必要な経路だけ追います。説明できない範囲があれば、実装前に追加fileを読ませます。

変更前のContext Card

小さなメモを作ると、会話を跨いでも誤った前提を引き継ぎにくくなります。

・今回の目的と変更しない範囲。

・対象branch、package、作業開始点。

・関連file pathと役割。

・変更前に実行したtestと結果。

・未確認の仮定、既知の失敗、次に見るfile。

・必要な外部情報のSource of Truth。

ここでは「全体把握済み」と書かず、実際に読んだ範囲を明記します。更新時は過去の説明をそのまま使わず、branchとworking treeを読み直します。

変更後のReview

実装後にdiffで、依頼外のfile、APIやdata contractの変更、generated artifactへの直接編集がないか確認します。関連testを実行し、testの対象外は未検証として残します。buildが成功したことも、すべての依存関係が正しく理解された証明ではありません。画面なら実際のroute、保存なら実際のresponseまで確認します。

よくある失敗の切り分け

対象fileが見つからない場合は、開いたrootとpackageを確認し、似たrouteや旧実装を検索します。AIが違うscriptを提示したら、package設定とREADMEの差を見ます。索引が古そうなら、該当pathの直接読み込みや正確なsymbol検索に切り替えます。

変更範囲が広がった場合は、当初のJobとdiffを照らし、不要なfileを対象から外します。型エラーが出たとき、型を緩める前にdataの正本とAPI responseの意味を確認します。testが失敗したときは、変更の影響か既存失敗かを区別し、変更前状態や関連testを調べます。

Context Handoff

別の会話や担当者に引き継ぐときは、repository説明を長文で再掲するより、再確認できる場所を残します。目的、変更しない範囲、branch/package、関連file、実行済みtest、未確認事項、次に見るfileを短くまとめます。受け取る側はその記録を現行working treeと照合してから作業を開始します。

AIものさしの判断

repository全体の理解は一度で完了せず、作業目的に必要な範囲を確かめるものです。rootと入口を確認し、rulesやschemaを読み、関係fileをたどり、diffとtestで仮説を検証します。indexingは探索を助けますが理解を保証しません。何が分かり、何が未確認かを説明できた段階で、その範囲内の変更を依頼してください。

小さな変更と複数file変更の依頼を分ける

見出しの文言修正なら、対象画面と望む表示、該当testを示して直接依頼できます。認証方式や複数serviceを跨ぐ変更なら、最初に計画を求め、参照するfileと影響範囲を確認してから実装へ進みます。どちらも、AIが必要とする説明と、実装前に人が確定すべき条件は別です。複雑なtaskでは、計画に含まれていないdatabase migration、権限、rollbackの扱いを明示します。

検証用の短い依頼例

「変更前に、対象package、関連route、data取得元、権限判定、関連testを列挙してください。次に、一覧表示のdataがAPIから画面まで届く順序を説明し、どのfileを変更するか提案してください。根拠を見つけられない説明は未確認と記してください。提案を確認した後でのみ編集します。」

この依頼でも調査結果が正しいとは限りません。pathが実在するか、testがそのrouteを通るか、別のpackageに同名処理がないかをこちらで照合します。AIの説明と実コードが食い違うなら、コードを優先して要件メモを修正します。

作業を始めない判断

対象rootが不明、repositoryが想定branchと違う、または権限・dataの正本が分からない場合は、推測で修正を始めません。質問または読み直しで解消できるなら、必要なfileを追加で確認します。正本同士が矛盾する、data lossの可能性があるなど、判断が将来の動作を大きく変える場合は、コードを書かずに矛盾点と選択肢を提示します。