Gemini にコードをまとめて渡せるようになった日から、同じフォルダを選ぶのをやめました

呼び出し側を機械で列挙する

手で追うと必ず漏れるので、依存グラフを作る小さなスクリプトを用意しました。実行してそのまま添付リストにできる程度の分量に抑えています。

# deps.py — 対象ファイルの「呼び出し側」と「依存先」を列挙する
# 使い方: python3 deps.py src/lib/content.ts
import os, re, sys
 
ROOT = "src"
EXTS = (".ts", ".tsx")
CANDIDATES = (".ts", ".tsx", "/index.ts", "/index.tsx")
 
files = [
    os.path.join(d, f).replace("\\", "/")
    for d, _, fs in os.walk(ROOT)
    for f in fs if f.endswith(EXTS)
]
 
def resolve(spec, frm):
    """import 文の指定を実ファイルへ解決する。'@/' は src/ 別名、'.' は相対パス。"""
    if spec.startswith("@/"):
        base = "src/" + spec[2:]
    elif spec.startswith("."):
        base = os.path.normpath(os.path.join(os.path.dirname(frm), spec)).replace("\\", "/")
    else:
        return None  # 外部パッケージは添付しない
    for ext in CANDIDATES:
        if base + ext in files:
            return base + ext
    return base if base in files else None
 
out = {f: set() for f in files}   # f が import しているファイル
inn = {f: set() for f in files}   # f を import しているファイル
for f in files:
    src = open(f, encoding="utf-8", errors="ignore").read()
    for spec in re.findall(r'from\s+["\']([^"\']+)["\']', src):
        r = resolve(spec, f)
        if r and r != f:
            out[f].add(r)
            inn[r].add(f)
 
target = sys.argv[1]
kb = lambda fs: round(sum(os.path.getsize(x) for x in fs) / 1024, 1)
callers, deps = sorted(inn[target]), sorted(out[target])
print(f"呼び出し側 {len(callers)} 件 / {kb(callers)} KB")
for f in callers:
    print("  <-", f)
print(f"依存先 {len(deps)} 件 / {kb(deps)} KB")
for f in deps:
    print("  ->", f)

src/lib/content.ts を渡すと、呼び出し側 19 件と依存先 0 件が並びます。依存先が 0 件なのは、このモジュールが Cloudflare の ASSETS バインディング経由で HTML を読むだけで、自前のモジュールに依存していないからです。つまり添付すべきは、下ではなく上でした。

外部パッケージを resolve の時点で切っている点は意図的です。node_modules の中身まで添付する余地はありませんし、モデルは公開ライブラリの型と挙動をおおむね知っています。添付枠は、自分のリポジトリにしか存在しない情報のために空けておきたいのです。

1 段で止めるか、2 段まで辿るか

呼び出し側を拾うと決めたあと、次に迷ったのは深さです。呼び出し側の呼び出し側まで辿るべきなのか、という問いです。

同じリポジトリで測った結果は、はっきりしていました。

1 段増やしただけで、添付量が全体のほぼ半分に達しました。ここまで来ると「必要なものを選んだ」とは言いにくく、実質的には全部渡しているのと変わりません。

そして 2 段目で増えた 14 ファイルは、私の場合ほとんどが UI コンポーネントでした。記事取得の契約が変わったときに直接壊れるのは 1 段目であり、2 段目は 1 段目が直れば連鎖的に収まります。いまは 1 段で止めて、足りないと感じたときだけ名前を指定して追加しております。

長いコンテキストに全部を放り込む選択肢もあります。私自身、以前は入るなら入れてしまえと考えていました。ただ、範囲を広げるほど「どこを見て答えたのか」が確かめにくくなります。範囲を絞ることは節約のためではなく、答え合わせを可能にするための手順なのだと、いまは考えています。

添付の順番と、最初に書く一文

選んだあとの渡し方にも、効き目の差がありました。私がいま踏んでいる手順を並べます。

1. 直したいファイルを 1 つ決め、deps.py を実行して呼び出し側の一覧を出します。
2. 呼び出し側のうち、変更の影響を受ける可能性がある行を含むものだけを残します。テストと型定義はこの段階では外します。
3. 直したいファイルを最初に添付し、そのあとに呼び出し側を並べます。順番は結果に影響しないはずですが、後から自分が読み返すときに追いやすくなります。
4. 最初の一文で、どれが変更対象でどれが呼び出し側かを明示します。「content.ts を変更します。残りは呼び出し側で、変更しません」という程度で十分です。
5. 質問には「壊れる箇所を、ファイル名と行の役割つきで挙げてください」と書きます。抽象的な改善案を求めると、抽象的な答えが返ってきます。

4 番を書き忘れると、呼び出し側にも修正案が付いてきます。悪い提案ではないのですが、私が知りたいのは影響範囲であって、書き直し案ではありません。役割を先に宣言しておくと、この取り違えはほぼ起きなくなりました。

うまくいかなかった二つのこと

ひとつは、生成物や自動生成ファイルを一緒に渡したことです。私のリポジトリには記事のメタデータをまとめた JSON があり、依存グラフ上は確かに呼び出し側です。ただ中身は機械が吐いた配列で、読ませても判断材料になりませんでした。いまは自動生成ファイルを添付対象から外し、代わりに「このファイルは生成物で、形はこうです」と一行で説明しています。同じ形の JSON を抱えている方には、添付ではなく一行の説明に置き換えることをお勧めします。

もうひとつは、設定ファイルを軽く見ていたことです。middleware.ts は呼び出し側が 0 件で、依存先が 2 件しかありません。数の上では小さいのですが、ここでの分岐がページの挙動を決めています。依存グラフの数字が小さいことと影響が小さいことは別なのだと、いまは感じています。API キーの扱いで同じ勘違いをした話は Gemini の API キーを差し替えても旧キーが勝つ理由 に書き残しております。

数えることの効用は、こうした思い込みが数字と食い違ったときに現れます。似た考え方は 9月で止まる標準 API キーを三層で棚卸しする や アシスタント前提の記述が自分のアプリに何箇所残っているか でも使っています。棚卸しは地味な作業ですが、個人開発では代わりにやってくれる人がいません。

いま使っている線引き

まとめて渡せるようになったことで楽になったのは、貼り付けの手間だけでした。増えたのは、選ぶという仕事です。そして選ぶ仕事の答えは、モデルではなくリポジトリの構造が持っているのかもしれません。

添付は、直したい場所からではなく、壊れる場所から選びます。 この順番だけは、急いでいる日でも守るようにしています。

まずは自分のリポジトリで、いちばん触る回数の多いファイルを 1 つ選び、deps.py を通してみていただければと思います。呼び出し側が同じフォルダに何件いたか——その数字が、これまでの添付の当たり外れをそのまま説明してくれるはずです。

最後までお読みくださり、ありがとうございました。