◈ Agents & Manager/2026-08-07上級

変更したファイルからテストを選ばせたら、9 割が「該当なし」でした — import グラフで届く範囲を 3 リポジトリで測る

変更起点でテストを選ぶ仕組みを自己検証ループに入れたところ、大半の変更で対象が 0 本になりました。到達範囲を 3 リポジトリで実測し、選択契約を組み直すまでの記録です。

✦ プレミアム記事

自己検証ループの実行時間を削るつもりでした。

エージェントが変更を出したあと、毎回テスト一式を走らせるのは待ち時間が長く、失敗しても原因の切り分けに時間がかかります。個人開発では、その待ち時間はそのまま自分の一日から差し引かれます。変更したファイルから逆にたどって、関係するテストだけを走らせればよいはずでした。

仕組みを入れて最初の数十件を流したところ、返ってきたのは「対象テスト 0 本」ばかりでした。

計測全体が 0.4 秒で終わったので、まずファイルを読めていないバグを疑いました。逆依存の辺数を数えると 3,177 本。グラフは確かに出来ていました。0 本という答えのほうが正しかったのです。

その日に測り直した内容を残しておきます。

何を測ったか

対象は公開リポジトリ 3 本です。ディレクトリ構成の癖が異なるものを選びました。

リポジトリ	解析対象ファイル	相対 import の辺	グラフ構築時間
vite	1,540	1,409	303 ms
hono	388	914	240 ms
nest	1,727	3,177	339 ms

測るのは 1 つだけです。ソースファイルを 1 本変更したとき、import の逆方向をたどって到達できるテストファイルが、テスト全体の何割になるか。

エージェントに「この変更に関係するテストを選べ」と任せるとき、内部で起きているのはこの計算です。割合が小さいほど実行は速く、しかし取りこぼしの危険は増えます。

グラフを組む

相対 import だけを解決します。@nestjs/common のようなワークスペース参照やパスエイリアスは意図的に外しました。エージェントが数百ミリ秒で組める範囲に限定したかったからです。

import os, re, subprocess
from collections import defaultdict, deque
 
EXTS = [".ts", ".tsx", ".mts", ".js", ".mjs", ".jsx"]
 
# import 文と副作用 import の両方を拾う
IMP = re.compile(
    r'''(?:^|\n)\s*(?:import|export)\b[^;\n]*?from\s*['"]([^'"]+)['"]'''
    r'''|(?:^|\n)\s*import\s*['"]([^'"]+)['"]'''
)
# re-export だけで構成された index.ts を「バレル」として印を付ける
REEXP = re.compile(r'''(?:^|\n)\s*export\s+(?:\*|\{)[^;]*?from\s*['"]''')
 
 
def resolve(base_dir, spec, fileset):
    """相対指定を実ファイルへ解決する。解決できなければ None。"""
    if not spec.startswith("."):
        return None
    raw = os.path.normpath(os.path.join(base_dir, spec))
    cands = [raw] + [raw + e for e in EXTS]
    cands += [os.path.join(raw, "index" + e) for e in EXTS]
    # ESM の相対指定は .js と書いて .ts を指すことがある
    if raw.endswith(".js"):
        cands += [raw[:-3] + e for e in (".ts", ".tsx", ".mts")]
    for c in cands:
        if c in fileset:
            return c
    return None
 
 
def build(repo):
    out = subprocess.run(["git", "-C", repo, "ls-files"],
                         capture_output=True, text=True).stdout
    paths = [p for p in out.split("\n")
             if p.strip() and os.path.splitext(p)[1] in EXTS]
    fileset = set(paths)
    fwd, barrel = defaultdict(set), set()
 
    for p in paths:
        try:
            src = open(os.path.join(repo, p), encoding="utf-8",
                       errors="ignore").read()
        except OSError:
            continue  # サブモジュール等で実体が無い場合は飛ばす
        if os.path.basename(p).startswith("index.") and len(REEXP.findall(src)) >= 3:
            barrel.add(p)
        d = os.path.dirname(p)
        for m in IMP.finditer(src):
            t = resolve(d, m.group(1) or m.group(2), fileset)
            if t and t != p:
                fwd[p].add(t)
 
    rev = defaultdict(set)
    for a, bs in fwd.items():
        for b in bs:
            rev[b].add(a)
    return paths, rev, barrel

errors="ignore" を入れているのは、実体のないパスが git ls-files に混ざるためです。ここで例外を上げると解析が途中で止まり、辺の少ないグラフを正しいものとして扱ってしまいます。最初の実行で 0 本ばかり返ってきたとき、私が真っ先に疑ったのがこの経路でした。

✦

ここまでお読みいただきありがとうございます。

この記事の続きを読む

この先には、実装コードやベンチマーク結果など、実務でお役に立てる内容をご用意しています。このサイトは広告を掲載しておらず、サーバーや開発にかかる費用はメンバーの皆様のご支援で成り立っています。もしお役に立てていましたら、ご支援いただけますと大変ありがたいです。

この記事で得られること

✦vite・hono・nest で測ると、1 ファイルの変更から到達するテストは中央値 0.0〜0.7% に対し p90 は 0.3〜50.4%。平均値で設計判断を下すと外れます

✦vite ではソース 1,148 本のうち 89.6% が import グラフ上どのテストにも到達しません。怖いのは選びすぎではなく、静かに 0 本を返す取りこぼしでした

✦index.ts の再エクスポートを経路から外すと nest の到達率は平均 4.0%→1.4%、p90 14.5%→2.5%。バレルが選択範囲を約 3 倍に広げていました

Stripe による安全な決済 · いつでもキャンセル可能

✦

この記事を購入する

この先の内容をすべてお読みいただけます。一度のご購入で、いつでも何度でもアクセスできます。このサイトは広告を掲載しておらず、皆さまのご支援がサーバー費用などの運営を支えています。

または

メンバーシップなら全記事が読み放題 →

到達したテストを数える

逆方向に幅優先で広げ、テストファイルに当たったら記録します。skip は後でバレルを外すために使います。

def is_test(p):
    return (".spec." in p) or (".test." in p) or ("__tests__/" in p) or ("/e2e/" in p)
 
 
def closure_tests(start, rev, tests, skip=frozenset()):
    """start を変更したとき、import 経路で到達するテストの集合。"""
    seen, hit = {start}, set()
    q = deque([start])
    while q:
        cur = q.popleft()
        for importer in rev.get(cur, ()):
            if importer in seen or importer in skip:
                continue
            seen.add(importer)
            if importer in tests:
                hit.add(importer)
            q.append(importer)
    return hit

到達率は len(closure_tests(...)) / len(tests) です。ソースファイル全件について回し、分布を見ます。

平均値が役に立たない分布でした

リポジトリ	ソース	テスト	中央値	平均	p90	到達 0 本の割合
vite	1,148	392	0.0%	1.3%	0.3%	89.6%
hono	251	137	0.7%	10.0%	50.4%	27.9%
nest	1,320	407	0.2%	4.0%	14.5%	26.5%

hono の中央値は 0.7%、平均は 10.0%、p90 は 50.4%。同じ分布を 3 通りに要約すると、判断がまるで変わります。

中央値だけを見れば「テスト選択はほぼ常に効く」と読めます。平均だけを見れば「1 割で済むなら十分」と読めます。p90 を見て初めて、10 回に 1 回は半分の suite が走ると分かります。

到達率が高い側には具体的な顔があります。

リポジトリ	到達率が最大のファイル	到達率
hono	src/utils/types.ts	76.6%
hono	src/router.ts	68.6%
nest	packages/common/constants.ts	17.0%
vite	packages/vite/src/node/constants.ts	15.3%

型定義と定数ファイル。変更頻度が高く、変更の中身は小さいことが多い場所です。ここに触れた瞬間だけ、選択実行の利点が消えます。

エージェントの時間見積もりを「平均 10%」で組んでいると、この 1 割で予定が崩れます。私は見積もりを平均から p90 に置き換えました。

怖かったのは選びすぎではありませんでした

vite の「到達 0 本」が 89.6%。ソース 1,148 本のうち 1,029 本が、import グラフの上ではどのテストからも参照されていません。

理由は追えば分かります。vite のテストの多くは playground を立ち上げて挙動を確かめる形式で、ソースを相対 import していません。静的な import グラフからは、両者が無関係に見えます。

ここが計測していていちばん背筋が寒くなった箇所でした。

選びすぎは遅くなるだけです。選ばなさすぎは、緑のまま壊れたものを通します。しかも出力は「対象テスト 0 本」という、成功と区別のつかない静かな形で返ってきます。エージェントの自己検証に組み込むと、検証したつもりの空回りがそのまま「検証済み」として記録されます。

事前の私の予想は逆でした。ハブになるファイルを触ったときに suite 全体が走ってしまう、つまり削減が効かないことを心配していたのです。実際に危険だったのは、何も走らないほうでした。

バレルが経路を広げていました

もう 1 つ、予想と違ったのが index.ts の扱いです。

再エクスポートだけで構成された index.ts を経路から外して測り直すと、こうなりました。

リポジトリ	バレル数	平均（含む→除く）	p90（含む→除く）	到達 0 本（含む→除く）
vite	3	1.3% → 1.1%	0.3% → 0.0%	89.6% → 90.9%
hono	5	10.0% → 9.7%	50.4% → 50.4%	27.9% → 31.5%
nest	52	4.0% → 1.4%	14.5% → 2.5%	26.5% → 36.9%

nest だけ挙動が違います。p90 が 14.5% から 2.5% へ落ちました。到達範囲のかなりの部分が、コードの実質的な依存ではなく index.ts の再エクスポートを経由して生まれていたことになります。

バレルは人間の import 文を短く保つための仕組みです。それがそのまま、静的解析から見た「影響範囲」を膨らませます。52 本のバレルが 1,320 本のソースの見え方を変えていました。

ただし外せば正しくなるわけではありません。到達 0 本の割合は 26.5% から 36.9% へ増えます。バレル経由でしか繋がっていない本物の依存を、同時に切り落としているからです。

私自身はバレルを外さず、残す側を選びました。過剰に選ぶコストは待ち時間ですが、切り落としたコストは見逃しだからです。代わりに、バレル経由でのみ到達したテストには理由を付けて記録するようにしました。あとで「なぜこのテストが選ばれたか」を人が読めるようにするためです。

「該当なし」を結論にしない

測った結果を踏まえて、選択の出力を 3 状態にしました。0 本は結果ではなく、判断を上へ渡す合図として扱います。

FULL_SUITE_THRESHOLD = 0.35   # これを超えるなら選択の意味が薄い
 
 
def select_tests(changed, rev, tests, barrel=frozenset()):
    """変更ファイル群に対する実行計画を返す。0 本は結論にしない。"""
    hit, via_barrel = set(), set()
    for p in changed:
        direct = closure_tests(p, rev, tests, skip=barrel)
        whole = closure_tests(p, rev, tests)
        hit |= whole
        via_barrel |= (whole - direct)   # バレル経由でのみ届いたもの
 
    if not hit:
        # グラフ上どのテストにも届かない。e2e 側にしか無い可能性がある
        return {"mode": "escalate",
                "reason": "no_reachable_test",
                "run": "full",
                "changed": sorted(changed)}
 
    ratio = len(hit) / len(tests)
    if ratio > FULL_SUITE_THRESHOLD:
        return {"mode": "full",
                "reason": f"reach_ratio={ratio:.2f}",
                "run": sorted(tests)}
 
    return {"mode": "selected",
            "reason": f"reach_ratio={ratio:.2f}",
            "run": sorted(hit),
            "via_barrel_only": sorted(via_barrel)}

escalate を独立させたのが要点です。「選択の結果 0 本だった」と「そもそも静的解析では判断できない」は、実行時間が同じ 0 秒でも意味が正反対です。前者を後者と同じ扱いにしていたのが、最初に見た 9 割でした。

閾値 0.35 は hono の p90（50.4%）と nest の p90（14.5%）の間に置いています。半分の suite を選ぶくらいなら全部走らせたほうが、結果の解釈も再現も簡単になるためです。数字自体は自分のリポジトリで分布を測ってから決めていただくのが確実です。

この測り方で分からないこと

正直に書いておきます。上の数字は静的な相対 import だけを根拠にしています。

拾えないもの	起きること
ワークスペース参照・パスエイリアス	モノレポで依存が途切れ、到達 0 本が過大に出る
動的 `import()`・遅延読み込み	実行時にだけ現れる依存を見落とす
DI コンテナ・デコレータ経由の解決	nest のような構成で実際の結合が見えない
フィクスチャ・スナップショット・設定ファイル	コード以外の変更が影響ゼロと判定される
e2e / playground 形式のテスト	vite で 89.6% が到達 0 本になった主因