AIに変更対象ファイルだけ読ませる方法｜リポジトリ作業の文脈を絞る

AIへリポジトリ作業を頼むときは、最初に変更対象を列挙し、必要な依存関係だけを段階的に追加します。Contextを小さくすること自体が目的ではありません。今回の変更に必要な実装、型、呼び出し元、関連テスト、既存の設計ルールをそろえ、秘密情報や無関係なデータを不用意に渡さないことが目的です。読み取り範囲と書き込みを許可する範囲は分けて指定します。

対象を狭くしすぎると、共有型や呼び出し元を見落として壊れた変更になり、広く渡しすぎると、変更理由のないファイルや秘密情報まで処理対象に混ざります。Issueや作業依頼を「何を変えるか」「どこまで変えてよいか」「何を維持するか」に分け、実装中に新しい依存が必要になったときだけ範囲を広げます。

作業前にContext Contractを書く

まず変更要求を、目的、受入条件、触れてよい範囲、触れてはいけない範囲に分けます。ファイル名の一覧だけでは、似た名前のfixtureや生成物を編集してよいか分かりません。パスと役割を記し、読取専用ファイル、秘密情報、generated output、無関係なWIPを明示します。Issueの説明にない目的をAIが推測して追加しないよう、対象外も書いてください。

表は横にスクロールできます

Context区分	例	渡す理由	扱い
Change target	Component、API、設定ファイル	直接の変更対象	要件に沿って編集
Dependency	shared type、caller、schema	影響範囲を確認	読取、必要なら追加承認
Convention	adjacent implementation、命名規則	既存設計と整合	原則読取のみ
Test	関連test、fixture	期待挙動を確認	test範囲を明示
Out of scope	secret、生成物、無関係WIP	誤変更を防ぐ	読み込み・編集しない

ここでいう「対象」は初期仮説です。変更後に影響ファイルが増えるのは正常な場合がありますが、変更理由と関係を説明できるかを確認します。対象外のファイルを変更しないという要件と、必要な依存ファイルを一切読まないという指示は別です。読取許可と書込許可を分けると、必要な設計確認を行いながら変更境界を保てます。

依存関係を段階的に追加する

最初にIssueから直接の実装候補を選び、近接する呼び出し元、型、設定、関連テストを確認します。コンポーネントだけを直す作業でも、そのAPIを使うページ、共有データ構造、テストが影響することがあります。逆に、関連がないフォルダまで全て読み込む必要はありません。

実装で見つけた依存は、次の問いで追加します。「このファイルが変わると受入条件に影響するか」「変更の安全性を確認するために必要か」「読取だけで足りるか」です。答えが不明な場合は、まず呼び出し元やテストを読む範囲へ追加し、編集は別途判断します。共通Schema、権限境界、データ契約、複数機能の呼出しへ波及する変更は、初期の局所範囲を広げて影響を追います。

影響ファイルMap

表は横にスクロールできます

段階	調べるもの	追加する条件
1. 直接対象	要件に明記された実装	常に確認
2. 呼び出し元	route、親Component、API caller	入出力変更が波及するとき
3. 契約	shared type、schema、権限	データや権限の意味が関わるとき
4. 検証	test、fixture、validator	受入条件を再現するため
5. 周辺実装	類似機能、利用側	共通挙動や互換性確認が必要なとき

このMapは読む順序の例で、毎回五段階すべてのファイルを編集する指示ではありません。新しいファイルを追加する場合は、なぜ必要かを変更説明へ書き、不要になった候補ファイルは編集しないままにします。差分レビューでは、依頼された目的、受入条件、各変更ファイルの関係を一つずつ確認します。

Read / Write / No-Read境界

AIの依頼には三つの範囲を記載します。Readは設計理解のために読める資料、Writeは編集可能なファイル、No-Readは秘密情報や不要なデータです。環境やツールの機能によっては、読取範囲を技術的に制限できないことがあります。その場合は、認証情報や個人情報が置かれていない安全なContextを選び、プロンプトの一文だけで保護できると考えないでください。

表は横にスクロールできます

境界	指示例	確認方法
Read	実装、関連型、隣接テスト	読む理由を記載
Write	変更対象パスを列挙	最終diffを照合
No-Read	.env、credential、顧客データ	対象外として指定、可能なら環境で除外
No-Write	snapshot、無関係WIP、成果物	diffで変更がないことを確認

生成済みファイルは、sourceとgenerated outputの関係を確認してから扱います。生成物を手で直すと、次のbuildで失われたり、sourceと不整合になったりします。生成スクリプトが作るファイルが変更対象に見えたら、先に正規のsource・生成手順・検証方法を確認します。顧客情報や秘密値がログ、テストfixture、Promptへ複製されないことも差分で確認してください。

Promptの例

「作業目的は［変更目的］です。受入条件は［確認可能な条件］です。最初にWrite対象として［許可パス］を使い、［Read許可パス］は設計確認に限ってください。［No-Readの秘密情報・個人データ］を開かず、［No-Writeのgenerated outputや無関係WIP］を変更しないでください。依存ファイルを追加する必要がある場合は、そのパスと変更理由を示してから必要な範囲だけ扱ってください。変更後は対象ファイル一覧、各変更理由、関連テスト、対象外ファイルに差分がないことを確認してください。受入条件や既存Contractに矛盾がある場合は、仮定で広げず該当点を示してください。」

Promptのファイル名だけではアクセス権限が制限されない点に注意します。可能なら作業環境の権限設定や安全なbranch/worktreeを使い、重要な情報を最初からContextに含めません。出力された変更が範囲内か、実際のGit差分で照合します。ツール固有のファイル参照構文やFolder指定を使う場合は、そのツールの現行公式資料に従い、同じパス指定が何を含むか理解してから利用します。

架空例：フォームの必須項目を追加する

申請フォームの「利用目的」を必須にする作業を考えます。初期のWrite候補はフォームComponentと、その入力を受け取るValidationです。関連型やAPI callerはRead対象にして既存の契約を確認します。テストは空文字、空白だけ、既存入力の受入れ、API送信を含む関連テストを選びます。これはContext選択を説明する架空例で、実際のRepositoryや変更結果ではありません。

Validationが複数ページで共有されていると分かった場合は、影響routeの利用箇所を追加で読み、変更が共通契約に波及するか確認します。共通Schema自体の意味を変更する必要があるなら、単にWrite対象を増やすのではなく、関係者が承認した仕様か確認します。既存データのmigrationや一括更新まで必要だと判明した場合は、影響範囲が別の判断へ広がるため、局所修正として進めません。

失敗時の切り分け

表は横にスクロールできます

症状	主な原因	対応
テストが落ちるが対象外を見ていない	依存Contextが不足	caller・契約・関連testを追加
大量のファイルが変更される	境界や生成手順が不明	diffを分類し正規sourceへ戻る
実装後に別routeが壊れる	共有利用者の確認不足	影響routeと共通型を調べる
Secretが出力に混ざる	Contextへ秘密を渡した	利用を止め、出力・履歴の取扱いを確認
生成物だけ手修正された	source of truth不明	生成scriptと元データを確認
依頼外の設計変更が増える	目的が拡張された	受入条件へ戻し、不要変更を外す

差分レビューでは、変更されたファイルだけでなく、依頼された機能の境界も見ます。対象ファイル数が少ないから安全とは限らず、共通設定一つの変更が全routeへ波及することもあります。逆に関連testや型が追加されても、必要性が明確で受入条件を検証するなら適切です。最終的に残す差分は、目的と検証方法を説明できるものに絞ります。

実装後のContext閉鎖

作業が終わったら、使ったRead範囲とWrite範囲を短く記録し、予想外に追加した依存を説明します。受入条件ごとに、どのテストや手動確認が根拠か対応付けます。未解決の影響範囲が残る場合は、「確認済み」と混同せず、対象routeやデータ境界を明示します。作業用の一時資料やログへ秘密・個人情報が複製されていないかを確認し、既存の保管ルールに従います。

次にすること

次のRepository作業では、依頼文へ目的・受入条件・Read・Write・No-Read・No-Writeを記入します。初期対象から実装を読み、必要になったcaller・型・testを理由付きで追加してください。実装後はGit差分を受入条件に照らし、対象外のファイルや秘密情報が混ざっていないか確認します。

AIものさしの判断

Contextは「少ないほど良い」のではなく、変更を安全に判断できる範囲で過不足がない状態がよいです。小さな局所修正では近接実装と関連テストから始め、共通Contractや複数利用者へ影響する変更では必要な依存を含めます。読み取り権限、書き込み権限、秘密情報の除外を分け、差分ごとに変更理由を説明できるようにしてください。