作業中のエージェントに、次の指示をいつ渡すか — 待つ・割り込む・積むを実運用で測りました

積んだ指示が古くなる — 前提のずれ

キューの指示が実行されるのは、現在の作業が終わったあとです。当たり前のことですが、この「あと」に何が起きているかを、指示を書いた時点の私は知りません。

具体例を挙げます。「src/lib/queue.ts の retryCount を設定から読むようにしてください」と積みました。積んだ時点では、確かにそのファイルにその変数がありました。

三分後、キューが実行される頃には、進行中だった作業が queue.ts を分割し終えていました。retryCount は src/lib/queue/policy.ts に移っています。エージェントは律儀に queue.ts を探し、見つからず、新しく queue.ts を作って retryCount を書きました。二重定義の完成です。

エージェントは間違っていません。私が、三分前の世界を前提にした指示を、三分後の世界に届けたのです。

90 件の積んだ指示を後から調べると、実行時点で HEAD が積んだ時点から進んでいたものが 37 件（41%）ありました。そのうち実際に破綻したのが 20 件で、手戻り率 22% の中身はほぼこれでした。

つまり、キューイングの弱点は「エージェントの理解力」ではなく、指示に前提が書かれていないことです。人間同士なら「さっきのファイル」で通じます。三分後のエージェントには通じません。

積んだ時点の前提を、指示に貼り付ける

対策は拍子抜けするほど単純でした。積む前に、そのときのリポジトリの状態を指示本文に書き込んでおきます。

#!/usr/bin/env bash
# queue-note.sh — キューに積む指示に「積んだ時点の前提」を添える
# 使い方: ./queue-note.sh "retryCount を設定から読むようにしてください"
set -euo pipefail
 
INSTRUCTION="${1:?指示の本文を引数で渡してください}"
 
BRANCH="$(git rev-parse --abbrev-ref HEAD)"
HEAD_SHA="$(git rev-parse --short HEAD)"
DIRTY_COUNT="$(git status --porcelain | wc -l | tr -d ' ')"
STAMP="$(TZ=Asia/Tokyo date '+%Y-%m-%d %H:%M:%S')"
 
cat <<EOF
${INSTRUCTION}
 
--- 前提スタンプ（${STAMP} JST 時点で積みました）---
branch: ${BRANCH}
HEAD: ${HEAD_SHA}
未コミットの変更: ${DIRTY_COUNT} 件
 
実行を始める前に、現在の HEAD を ${HEAD_SHA} と照合してください。
進んでいる場合、この指示は古い前提で書かれています。
そのまま実行せず、次の形式で一度だけ確認してください:
「前提が変わっています（${HEAD_SHA} → 現在の SHA）。<変わった点の要約>。
 意図はおそらく <推測した意図> ですが、続行してよいですか」
---
EOF

出力をそのままキューに貼ります。二十行足らずのスクリプトですが、効き方が想像以上でした。

前提スタンプ導入後（7/14〜7/16・44 件）

前提がずれる頻度そのものは、ほとんど変わっていません。当然です。スクリプトは世界の変化を止めるわけではありません。

変わったのは、ずれたときにエージェントが黙って推測しなくなったことです。25% は確認を返してきました。その確認に一行答えるだけで済むなら、二重定義を後から見つけて直すよりずっと安い。

手戻り率 9% の残りは、確認すら思いつかない類のずれでした。たとえばファイルの中身は同じでも、意味づけが変わっていたようなケースです。ここはスタンプでは拾えません。

Send Now を使うべき三つの条件

キューが便利だと、何でも積みたくなります。ただ、積んではいけない指示があります。三日間で見えた条件は次の三つでした。

条件1: 進行中の作業を止めること自体が目的のとき

「その方針は違います、やめてください」を積むのは意味がありません。積んだ時点で、止めたかった作業は終わっています。ここは Send Now です。

条件2: 現在の作業が壊れていると分かったとき

出力が明らかに脱線している、無限ループに入っている。待つほど無駄が増えます。私の場合、三日間で Send Now を使ったのは 11 回、そのうち 7 回がこの型でした。

条件3: 指示の内容が、現在の作業の成否に依存しないとき

「終わったら CHANGELOG も更新して」は積んで安全です。逆に「さっき直したところをテストして」は、さっき直したところが変わるので危ない。

三番目が一番の落とし穴でした。私は当初、この型を安全側に分類していて、痛い目を見ました。安全そうに見えるのに、指示の中の「さっき」「その」「先ほどの」という指示語が、すべて前提スタンプなしでは解決できません。

積む前に、自分の指示文から指示語を探して、固有名に書き換える。これだけで積める指示かどうかが分かります。書き換えられないなら、それは待つべき指示です。

段階配布で、手元のバージョンが揃わないとき

v2.3.0 は段階的に配布されます。手元に届くまで数日かかることがあり、この記事を書いている時点でも、環境によって v2.2.1 のままのものがありました。

キューイングの有無で手順が変わるため、自動処理の中で分岐させています。

#!/usr/bin/env bash
# antigravity-version-probe.sh — 手元のバージョンを取り、機能の有無で分岐する
set -euo pipefail
 
# CLI 経由でバージョン文字列を取得（取れない環境では空になる）
RAW="$(antigravity --version 2>/dev/null || true)"
VER="$(printf '%s' "$RAW" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)"
 
if [ -z "$VER" ]; then
  echo "version-unknown: キューイング非対応として扱います" >&2
  echo "QUEUE_SUPPORTED=0"
  exit 0
fi
 
# 2.3.0 以上かどうかを sort -V で判定（バージョン比較を自前で書かない）
LOWEST="$(printf '2.3.0\n%s\n' "$VER" | sort -V | head -1)"
if [ "$LOWEST" = "2.3.0" ]; then
  echo "QUEUE_SUPPORTED=1  (detected ${VER})"
else
  echo "QUEUE_SUPPORTED=0  (detected ${VER} — Send Now / 逐次送信で運用)"
fi

sort -V に判定を任せているのは、2.10.0 と 2.9.0 の比較を文字列でやって間違えた経験があるからです。バージョン比較は自前で書かないほうが安全でした。

判定できないときは「非対応」に倒しています。キューが無い環境でキューを前提にすると指示が消えます。逆に、対応環境で逐次送信に倒しても、遅くなるだけで壊れません。倒すなら安全な側へ。自動処理に組み込む場合は、この向きで倒すことをお勧めします。

二分をどう使うか、という問いに戻る

三日間の暫定値ですが、いまの私の運用はこうなりました。

思いついたら、まず指示語を固有名に書き換えてみる。書き換えられれば queue-note.sh を通して積む。書き換えられなければ、それは現在の作業と絡んでいる指示なので、待つ。止めたいときだけ Send Now。私はこの三分岐を推奨します。判断に迷う余地が残らないからです。

この分岐を通すようになってから、冒頭の「二分」の落ち着かなさが減りました。待つか割り込むかの二択だった頃は、待つことが我慢でした。いまは、待つことにも積むことにも理由があります。

App Store 向けのアプリを一人で回していると、手戻りの一回が翌日の予定を押し出します。だから、手戻り率 22% を 9% にする二十行のスクリプトは、私にとって速度の話ではなく、明日の話でした。

次に試すなら、ここからだと思います。まず一週間、自分が作業中に何回割り込んでいるか数えてみてください。その回数がゼロに近ければ、キューイングは不要です。十回を超えるようなら、queue-note.sh を手元に置いて、積んだ指示に前提を添えるところから始める価値があります。

私自身まだ測りはじめたばかりで、90 件と 44 件では結論と呼ぶには足りません。一か月後に同じ物差しで測り直して、この数字がどう動いたかをまたご報告できればと思っております。お読みいただきありがとうございました。