▣ アプリ開発/2026-06-20上級

複数環境でエージェント設定が静かにずれていく — 設定ドリフトの検知と是正

2台のMacと自動運用環境でエージェントの設定が少しずつ食い違い、片方だけ失敗する——その「設定ドリフト」を、ハッシュ照合と是正手順で見える化する設計を、個人開発の現場からまとめます。

Antigravity²⁴⁸ エージェント⁴⁰ 設定管理ドリフト検知運用設計¹⁶

✦ プレミアム記事

同じエージェントなのに、片方の環境でだけ失敗する。ログを見比べても入力は同じ、コードも同じ。原因は数週間前に片方のMacだけで変えた設定値が、もう片方に反映されていなかったことでした。私自身、個人開発でメインのMacとサブのMac、それに自動運用の環境をまたいで作業しているので、この「いつの間にか設定がずれている」状態には何度もはまってきました。

設定ドリフトは、一度に壊れるのではなく、少しずつ食い違っていく性質を持ちます。だからこそ気づきにくく、気づいたときには「どちらが正しいのか」さえ分からなくなっています。これを防ぐ出発点は、設定を目で確認するのをやめて、機械に照合させることです。

なぜドリフトは静かに進むのか

設定が食い違う典型は、緊急対応です。深夜に1台だけで設定を直して急場をしのぎ、後で全環境に展開するつもりが、そのまま忘れる。あるいはツールの更新で既定値がこっそり変わり、片方だけが新しい既定値を拾う。Antigravity のようにデスクトップ・CLI・SDK と複数の利用面を持つツールでは、面ごとに設定の置き場所が違うため、ずれが入り込む隙間も増えます。

厄介なのは、ドリフトの大半が無害なまま放置されることです。99%の試行では何も起きず、残り1%でだけ「片方のモデル設定が古くて出力形式が違う」といった形で表面化します。無害な期間が長いほど、原因を直近の変更だと思い込みにくくなり、本番運用での調査が遠回りになる落とし穴です。

何を「設定の正本」とするか

最初に決めるべきは、どこを正本（source of truth）にするかです。私はリポジトリに config/agent.toml のような形で設定を1か所に置き、各環境はそこから読み込む方針を推奨します。正本がリポジトリにあれば、差分は git の履歴として残り、「いつ・誰が・何を変えたか」が後から追えます。

ただし現実には、環境固有の値（ローカルのパスや実行ホスト名など）は正本に入れられません。そこで設定を二層に分けます。

層	例	照合対象か
共有設定	モデル名・タイムアウト・リトライ上限・ゲートの閾値	照合する（全環境で一致すべき）
環境固有設定	作業ディレクトリ・ホスト名・並列数	照合しない（環境ごとに違ってよい）

照合の対象を共有設定だけに絞ることが大切です。環境固有の値まで一致を求めると、毎回「差分あり」と言われて警告が形骸化します。

✦

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

この記事の続きを読む

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

この記事で得られること

✦設定ファイルを正規化してハッシュ化し、環境間の差分を1コマンドで検知する実装（25行）

✦ドリフトを『無害・要警告・即是正』の3段階に分け、何を自動修正し何を人が見るかの線引き

✦2台のMac+自動運用で設定の食い違いによる夜間失敗を減らした、週1の照合運用

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

✦

この記事を購入する

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

または

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

正規化してからハッシュで照合する

照合の核は単純で、共有設定を正規化してハッシュ化し、環境間で突き合わせるだけです。正規化を挟む理由は、キーの並び順やインデントの違いだけで別物と判定されるのを回避するためです。TOML や JSON を一度パースし、キーをソートして書き出してからハッシュを取ります。

import hashlib, json, tomllib
 
SHARED_KEYS = {"model", "timeout_s", "max_retries", "gate_thresholds"}
 
def shared_fingerprint(config_path: str) -> str:
    with open(config_path, "rb") as f:
        data = tomllib.load(f)
    # 共有キーだけ抜き出し、順序を正規化してからハッシュ化する
    shared = {k: data[k] for k in sorted(SHARED_KEYS) if k in data}
    canonical = json.dumps(shared, sort_keys=True, ensure_ascii=False)
    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()[:16]

各環境でこのフィンガープリントを出力し、正本のフィンガープリントと比べます。一致すれば共有設定は揃っています。食い違えば、どのキーがずれているかを次のように具体的に出します。ハッシュは「ずれているか」を高速に判定し、差分表示は「どこがずれているか」を示す、という役割分担です。

def diff_shared(a_path: str, b_path: str) -> list[str]:
    def load(p):
        with open(p, "rb") as f:
            d = tomllib.load(f)
        return {k: d.get(k) for k in SHARED_KEYS}
    a, b = load(a_path), load(b_path)
    return [f"{k}: {a[k]!r} != {b[k]!r}" for k in SHARED_KEYS if a[k] != b[k]]

ドリフトを3段階で扱う

検知できても、すべてを即座に直すべきとは限りません。私はドリフトを次の3段階に分けて扱っています。

無害なドリフト（照合対象外）

並列数やローカルパスのような環境固有の差は、そもそも照合対象から外しているので、ここには現れません。万一現れたら、それは共有設定の切り分けが間違っているサインなので、SHARED_KEYS を見直します。

要警告のドリフト（人が揃える）

タイムアウトやリトライ上限のように、ずれていても致命的ではないが、いずれ片方だけ挙動が変わる値です。検知したら警告を出し、次の作業のついでに揃えます。自動修正はせず、人が「どちらに揃えるか」を判断するのをお勧めします。

即是正のドリフト（自動で正本へ）

モデル名やゲートの閾値のように、ずれると出力品質や安全性に直結する値です。これは検知した時点でジョブを止め、正本に強制的に揃え直します。私の運用では、ゲートの閾値がずれていた環境を1台見つけたとき、品質チェックを素通りした記事が出かけていたことがあり、それ以来この階層だけは自動是正にしています。同じ轍を踏まないよう、ここだけは手動運用に頼らないことを強く推奨します。

CRITICAL = {"model", "gate_thresholds"}
 
def decide(diff_keys: set[str]) -> str:
    if diff_keys & CRITICAL:
        return "halt_and_fix"   # 即是正：ジョブを止めて正本へ
    if diff_keys:
        return "warn"           # 要警告：人が揃える
    return "ok"

週1の照合を運用に組み込む

検知の仕組みは、定期的に回してこそ意味を持ちます。私は週に1回、全環境のフィンガープリントを正本と突き合わせる照合を、日曜の静かな時間帯に走らせています。差分がなければ1行「一致」と出るだけなので、確認は数秒で終わります。

照合のタイミングをずらすコツとして、大きなツール更新の直後は臨時で1回多く回すようにしています。Antigravity のようにバージョンが活発に動くツールは、更新で既定値が変わることがあり、そのタイミングがドリフトの入りやすい瞬間だからです。App Store Connect の API キーのように、環境ごとに別管理する値はあえて照合対象から外し、共有すべき値だけに絞ることで、警告のノイズを抑えています。

設定のずれは、起きてから直すより、起きたことに気づける状態を先に作るほうがずっと楽です。正本を1か所に決め、共有設定だけをハッシュで照合し、影響の大きい値だけ自動是正する——この三段構えで、複数環境のエージェントは驚くほど静かになります。まずは手元の2環境で、共有キーのフィンガープリントを出して突き合わせるところから始めてみてください。同じ「片方だけ失敗する」謎に悩む方の助けになれば幸いです。