◈ Agents & Manager/2026-06-13上級

スケジュール実行のエージェントが二重に走る — 重複と再実行に耐える冪等設計

前回の実行が終わらないうちに次回がトリガーされ、スケジュール実行のエージェントが同じ作業を二重に行うことがあります。重なり防止のロックと、途中失敗からの再実行に耐える冪等化を、実運用で踏んだ二重投稿の事例とともに設計します。

agents⁶⁷ idempotency³ scheduled-execution³ locking reliability³

✦ プレミアム記事

同じ記事が2本、ほぼ同じ時刻に公開されているのを見つけたことがあります。

個人開発で複数のサイトを自動運用しているため、コンテンツ生成やレポート集計をスケジュール実行のエージェントに任せています。あるとき生成が普段より重く、1回分の実行が想定の枠を超えて長引きました。終わらないうちに次回のトリガーが来て、2本目のエージェントが起動し、同じトピックでもう1本作って push してしまったのです。

スケジュール実行は「決まった時刻に1回走る」と思いがちですが、実際には「前回が終わっていなくても時刻が来れば走る」ことがあります。私自身、この思い込みのまま組んでいて二重投稿に至りました。重なりと再実行に耐えるエージェントの冪等設計を、運用で踏んだ事故をたどりながら順に組み立てていきます。

二重実行はなぜ起きるのか

原因は大きく2つに分かれます。切り分けないと対策がずれます。

ひとつ目はオーバーラップ（重なり）です。前回の実行が長引き、終わる前に次回のトリガー時刻が来ると、2つの実行が並走します。生成系のエージェントは入力データやモデルの応答時間によって所要時間が大きく振れるため、普段は5分で終わる処理が、たまに20分かかることがあります。固定間隔のスケジュールは、この揺らぎを吸収してくれません。

ふたつ目はリトライによる再実行です。多くの自動実行環境は、失敗したタスクを自動でやり直します。問題は「どこまで進んでから失敗したか」です。記事ファイルを書き終えて push する直前にネットワークで落ちた場合、ファイルは残っているのに「失敗」と判定され、再実行で同じ作業をもう一度やると、成果物が二重になります。

この2つは性質が違います。オーバーラップは「同時に2つ走る」問題で、ロックで防ぎます。リトライは「時間をおいて2回走る」問題で、成果物の冪等化で吸収します。両方が必要です。

オーバーラップは flock で防ぐ

重なりを防ぐ最も確実な方法は、実行の入り口で排他ロックを取ることです。Linux の flock は、ファイルディスクリプタに対するアドバイザリーロックを提供し、ロックが取れなければ即座に諦める、という挙動を簡単に書けます。

#!/usr/bin/env bash
# run_agent_guarded.sh
# 同じタスクの実行が既に走っていたら、今回はスキップする
set -euo pipefail
 
LOCK="/tmp/agent-content-antigravity.lock"
 
exec 9>"$LOCK"
if ! flock -n 9; then
  echo "⏭ 前回の実行がまだ走っています。今回はスキップします（$(date '+%F %T')）"
  exit 0
fi
 
# ここから先は単一実行が保証される
echo "▶ 実行開始 $(date '+%F %T')"
 
# --- 実際のエージェント作業 ---
generate_and_push_article
 
echo "■ 実行終了 $(date '+%F %T')"
# 9 番ディスクリプタはプロセス終了時に自動で閉じ、ロックも解放される

flock -n の -n（non-blocking）が肝です。ロックが取れなければ待たずに終了コードを返すので、重なったときは黙って次回に譲ります。待ち行列を作らないことで、実行が雪だるま式に積み上がるのを防げます。ロックファイルは /tmp のようにプロセス間で共有される場所に置き、ディスクリプタはプロセス終了で自動解放されるため、明示的な解放処理は不要です。

これでオーバーラップは止まります。しかしリトライによる二重化は、ロックだけでは防げません。時間をおいて走る2回は、どちらもロックを取れてしまうからです。

✦

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

この記事の続きを読む

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

この記事で得られること

✦スケジュール実行が二重に走る2つの原因（前回実行の長期化による重なり・失敗後の自動リトライ）を切り分けて理解できる

✦flock によるオーバーラップ防止と、作業キーで成果物の重複を弾く冪等ガードを、bash でそのまま導入できる

✦「少なくとも1回」実行を前提に、二重実行が起きても成果物が1つに収束する設計の組み立て方が分かる

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

✦

この記事を購入する

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

または

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

リトライは作業キーの冪等化で吸収する

冪等（idempotent）とは、同じ操作を何回行っても結果が変わらない性質です。スケジュール実行は「少なくとも1回（at-least-once）」走ることはあっても「ちょうど1回（exactly-once）」は保証されない、と前提を置きます。そのうえで、2回走っても成果物が1つに収束するように設計します。

要は、生成しようとしている成果物に一意な「作業キー」を与え、push の直前に「そのキーの成果物がもう存在しないか」を確認することです。コンテンツ生成なら、トピックから決まる slug が作業キーになります。

# 冪等ガード: この slug の記事が ja/en に既にあるなら、作業をやめる
SLUG="antigravity-scheduled-agent-idempotency-overlap-guard-design"
JA="content/articles/ja"
EN="content/articles/en"
 
if find "$JA" "$EN" -name "${SLUG}.mdx" | grep -q .; then
  echo "⏭ slug=$SLUG は既に存在します。生成をスキップします。"
  exit 0
fi
 
# ここに来たら、この slug はまだ無い → 生成して良い
write_article "$SLUG"

ポイントは、確認を「実行の最初」ではなく「push の判断と同じ場所」で行うことです。最初に確認しても、生成に時間がかかる間にもう1つの実行が同じ slug を作るかもしれません。push 直前に最終チェックを置くことで、競合の窓を最小にできます。

さらに堅くするなら、ローカルだけでなくリモートの最新状態に対して確認します。スケジュール実行の前段で git pull --rebase を済ませてから slug 存在を検査すれば、別マシンの別実行が先に同じ slug を公開していた場合も弾けます。

push 自体の冪等性も確保する

成果物の重複を弾けても、push の競合が残ります。複数の実行が同じ origin/main に push しようとすると、後発は non-fast-forward で弾かれます。これは失敗として扱い、自動でリベースして1回だけやり直す設計にします。

push_with_rebase_once() {
  if git push origin main; then
    echo "✅ push 成功"
    return 0
  fi
  echo "↺ 競合を検知。pull --rebase して1回だけ再試行します。"
  git pull --rebase origin main || { echo "❌ rebase 失敗。手動確認が必要です。"; return 1; }
  # リベース後、冪等ガードを再評価（先に同じ slug が公開されていたら自分の分は捨てる）
  git push origin main
}

無限リトライにしないのがコツです。1回リベースして再 push しても通らないなら、それは単純な競合ではなく別の異常（権限・保護ブランチ・大きな乖離）の可能性が高いので、機械の再試行を打ち切ってログに残します。

設計の優先順位

3つの仕掛けは、入れる順番に意味があります。まず flock で同時実行を止め、次に作業キーで成果物の重複を弾き、最後に push をリベース付き1回再試行で冪等にします。この順で重ねると、二重実行が起きても成果物は1つに収束します。

本番運用へ入れる前に、私自身が確認している導入手順を3つにまとめておきます。

まず flock だけを入れ、1週間ほど「スキップが何回起きたか」のログを観測します。スキップが1日に何度も出るなら、実行間隔が処理時間に対して短すぎる兆候です。
次に冪等ガードを push の直前に置き、リモートに対して git pull --rebase を済ませてから slug 存在を検査します。これで別マシンの実行との競合まで弾けます。
最後に push をリベース付き1回再試行にし、それでも通らなければ機械の再試行を打ち切ってログに残します。

アプリ開発で AdMob のレポート集計や App Store 向けの定期処理をエージェントに任せている経験では、この3点を入れてから二重投稿はゼロになり、無音の再実行による手戻りも体感で月に数件から1件未満へ減りました。スケジュール実行は「ちょうど1回」を捨てて「2回走っても壊れない」を前提に置き換えるのが出発点だと考えています。冒頭の二重投稿は、flock ひとつ入れるだけでも防げたものでした。まずはロックから始めてみてください。