複数PCのAIエージェントに「ルールの変更」を確実に届ける — 届いたつもりを潰す4つの実測

複数のPC（または複数アカウント）で同じAIコーディングエージェントを使っていると、片方で決めた運用ルールが もう片方に届かず、同じ調査を何度もやり直す。よくある構成は「共有リポジトリの ONBOARDING.md を セッション開始フックが取ってきてローカルへ展開する」。これは pull だけが自動で、push が手動なので穴が空く。

この指示書は、その輪を閉じるまでに実際に踏んだ4つの罠と、それぞれの潰し方を書く。 どれも「成功ログが出ているのに古いまま」という形で現れるので、ログを根拠にすると必ず騙される。

前提の構成

• 共有リポジトリ（例: <org>/<rules-repo>）に ONBOARDING.md を置く
• 各PCの SessionStart フックが同期スクリプトを起動し、ONBOARDING.md を取得してローカルへ展開する
• エージェントは毎セッションその内容を読む

罠1: 書き出し(push)が自動化されていない

pull だけ自動にすると「決めた側が書かない」ので永久に届かない。機体ローカルで決めたことは、 共有ファイルの表に書いて PR を出すまでを1タスクにする。ルール本文に次の表を埋め込む。

<!-- MACHINE-STATE-START 各PCは自分の行だけを更新して push する -->

| 機体 / アカウント | 設定値 | 理由 | 最終更新 |
|---|---|---|---|
| <PC名> / <アカウント> | `<値>` | <なぜその値なのか> | <YYYY-MM-DD> |

<!-- MACHINE-STATE-END -->

「理由」を必須にするのが要点。値だけ書くと、次のセッションが「ルールと違う」と判断して勝手に戻す。 また伝播しないものを同じ場所に明記する（エージェントの永続メモリ、機体ローカルの設定ファイル、 会話そのもの）。これが書いていないと「メモリに書いたから伝わるはず」と誤解する。

罠2: 取得の間引きが長すぎ、しかも黙っている

同期スクリプトはたいてい「前回から N 時間以内なら取得しない」を持つ。N が20時間だと、 書いた結論が他PCに届くまで最大20時間かかる。さらに悪いのは黙って return する実装で、 その後に走る別の同期（サブディレクトリのコピー等）のログだけが出るため成功したように見える。

// 悪い: 黙って返る
if (!force && since < 20 * 60 * 60 * 1000) return;

// 良い: 分単位にし、スキップした事実を必ず出す
const minIntervalMin = Number(process.env.RULES_MIN_INTERVAL_MIN ?? 15);
if (!force && since < minIntervalMin * 60 * 1000) {
  console.log(`[sync] 取得をスキップ (前回 ${Math.round(since / 60000)} 分前 / 間引き ${minIntervalMin} 分 / --force で強制)`);
  return;
}

本文が 100KB 程度なら、セッション開始ごとに取り直しても実質コストはない。

罠3: CDN が古い版を返す（最も見つけにくい）

GitHub の raw 配信は、マージ直後に古い版を返すことがある。 実測（同一時刻・同一URL）:

取得方法	返ってきたサイズ	ヘッダ
Node の fetch（undici）	古い版	x-cache: HIT
curl	新しい版	—

Cache-Control: no-cache を送っても、クエリ文字列でキャッシュキーを変えても、Node 側は HIT のままだった （エッジが違うため curl だけ当たった）。ここから2つの教訓が出る。

1. 検証は配布経路そのもので行う。 curl で新しい版が見えても、実際に配布するのが Node なら その Node で確かめない限り「届いた」とは言えない。
2. 取得元を CDN でないものに変える。 ホスティングの Contents API は同時刻に新しい版を返した。

// API を先に試し、失敗（レート制限・障害）時だけ raw へ落とす
const attempts = [
  { label: 'api', url: `https://api.github.com/repos/<org>/<repo>/contents/ONBOARDING.md?ref=main`,
    headers: { Accept: 'application/vnd.github.raw', 'User-Agent': '<your-sync-tool>' } },
  { label: 'raw', url: rawUrl, headers: { 'Cache-Control': 'no-cache' } },
];
for (const a of attempts) {
  try {
    const r = await fetch(a.url, { cache: 'no-store', headers: a.headers, signal: AbortSignal.timeout(15000) });
    if (!r.ok) throw new Error(`HTTP ${r.status}`);
    const bytes = Buffer.from(await r.arrayBuffer());
    if (bytes.length) return { bytes, source: a.label };
  } catch (e) { /* 次の候補へ。最後まで失敗したらログに全部出す */ }
}

未認証の Contents API は 60 req/時/IP。15分間引きなら1台あたり4回/時なので収まる。 どちらから取れたかを必ずログに出す（updated (hash xxxxxxxx / from api)）。出さないと、 フォールバックが常用されていることに気付けない。

さらに悪い相互作用として、古い版のハッシュを「取得済み」として保存する実装だと、 次の取得まで「最新のつもり」で止まる。ハッシュ保存は取得元とセットで記録する。

罠4: git push --dry-run は保護ブランチを教えてくれない

エージェントに「main へ直接 push できるか」を確かめさせると --dry-run を使いがちだが、 dry-run は保護ブランチのフックを通らないので「通る」と表示される。実際に push すると ! [remote rejected] ... (protected branch hook declined) で落ちる。

保護されている前提で、エージェント側はブランチ push と PR 作成までを自動化し、 マージは人が押す設計にする（共有リポジトリの既定ブランチへのマージは、エージェントの安全機構が 拒否することがある。これは正しい関門なので迂回しない）。CLI の認証が無くても、 資格情報ヘルパーに入っているトークンで API から PR は作れる。

git push origin HEAD:refs/heads/auto/<日付>-<内容>
TOK=$(printf 'protocol=https\nhost=<host>\n\n' | git credential fill | sed -n 's/^password=//p')
curl -X POST -H "Authorization: Bearer $TOK" -H "Accept: application/vnd.github+json" \
  -d '{"title":"...","head":"auto/<...>","base":"main","body":"..."}' \
  https://api.github.com/repos/<org>/<repo>/pulls

必須チェックが終わるまで mergeable_state は blocked なので、API で clean を確認してから 人に手順を出す。灰色のボタンを押させると手戻りになる。

受け入れ条件（これが言えるまで「直った」と言わない）

1. 共有ファイルを変更 → マージした
2. 配布経路（同期スクリプト）を実行して、ローカルのファイルサイズ／文字列が新しい版に変わった
3. 取得元がログに出ている
4. 間引きに当たったときは、その理由がログに出ている

1 と 2 の間が今回いちばん壊れていた。1 だけを見て「配布した」と報告しない。