2026-10-17 追記: 記事を見直しました
- 「外部に影響する操作は承認キュー、内部的な再試行は自動化」という線引きの説明で、掲載のリトライ関数が外部APIの呼び出し自体を再実行する点との関係が曖昧でした。応答だけがタイムアウトした場合などに副作用が重複しうるため、自動再試行は読み取り系など再実行しても安全な呼び出しに限るべきだという注意を書き足しました
- 「月2,500件」は元記事の紹介文にある数字で、私は独立に検証していないことを冒頭と比較表でも明記しました
内容の骨子は変えていません。
月2,500件のPRをAIエージェントに任せて回している、と紹介されている開発基盤があると知って、最初は規模の違いに身がすくんだ。私が副業で運用しているのは、秘書役のエージェントと部門ごとのエージェントが同じリポジトリに並行して書き込む、もっと小さな構成だ。それでも私は、一度だけ「このまま進めると衝突する」とヒヤッとした実装の痕跡から、承認キューとリトライ機構を作る羽目になった。今回はその一次体験を手がかりに、大規模PR基盤の設計思想を自分の運用ルールと突き合わせてみる。
元記事が語る「月2,500件のPR」という基盤
元ネタは、著者kaito氏がZennのBook形式で公開している『AIエージェントに開発を任せる環境をつくる』だ1。概要を読むと、2,500件という数字は目標設定ではなく、環境を整えた結果として出てきたものだと位置づけられている。
「2,500件のPRは目標ではなく、環境が整った結果」
なお、2,500件という数字の集計期間・対象・算出方法は元記事の公開ページ自体には明示されておらず、私はこの数字を独立に検証していない。以下は「元記事がそう述べている」という前提で読んだ内容だ。
もう一つ印象的だったのが、信頼の置き方についての一文だ。
「信頼するのは、エージェントではなく成果物」
これはエージェント自体の振る舞いを信じるのではなく、出力された成果物を検証可能な形にして、検証結果を信頼するという考え方だと私は読んだ。さらに本書では「pstack」という仕組みが紹介されており、Playbook・Principle・Skillの3要素でタスク委譲と判断基準を体系化していると概要に書かれている1。
自分の運用規模はどれくらい小さいか
私の環境では、秘書役のエージェント1つと部門別のエージェントが同じGitリポジトリを共有している。実際に数えてみると、ルートに置いている部門エージェントの定義ファイルが19本、部門配下のサブディレクトリにいる専門エージェントが5本で、合計24本のペルソナ定義ファイルが存在する（2026-10-04時点、自環境のagents/配下をlsで実数確認。この24という数字はファイル数であり、同時実行数を測定したものではない）。月2,500件のPRとは比較にならない規模だが、同じリポジトリへ複数のエージェントが並行して書き込む点だけは共通している。
だからこそ、規模の差を無視して「大規模基盤の設計をそのまま真似る」よりも、自分が実際に衝突・誤操作で痛い目を見た部分と、元記事の設計思想がどこで噛み合うかを見るほうが、私には実用的だった。
設計思想のすり合わせ
| 観点 | 月2,500件PR基盤（元記事） | 私の運用 |
|---|---|---|
| 規模 | 月2,500件のPR（元記事の記載・未検証）1 | エージェント定義ファイル24本(自環境実測) |
| 信頼の置き方 | 「信頼するのは成果物」1 | 外部向け操作は承認キューを通し、内部操作のみ自動実行 |
| タスク委譲の体系化 | pstack(Playbook/Principle/Skill)1 | 役割別ペルソナファイル＋秘書エージェントによるルーティング |
| 障害時の振る舞い | （概要からは不明・未確認） | 3回試行して失敗したら承認キューへの登録をログで模擬 |
障害時の振る舞いについては、元記事の概要ページからは具体的な記述を確認できなかったため、比較を保留している。わかったことだけを書き、わからないことは「わからない」と書くようにした。
エラー処理（APIリトライとエスカレーション）を実際にどう作ったか
複数のエージェントが同じリポジトリに書き込む構成を長期運用していると、外部API呼び出しが一時的なタイムアウトやレートリミットで止まることがあった。人間が気づくまで処理が止まったまま放置されるケースもあり、これを見落とすのは危険だと感じた。そこで、エージェントのツール実行部分に指数バックオフ付きのリトライを入れ、3回試行して失敗した時点で承認キューへの登録をログで模擬する設計に変えた（なお、これは外部API呼び出し単位の障害対応であり、同一リポジトリへの並行書き込みそのものを防ぐロックや競合検出の仕組みではない）。
以下は、その仕組みを簡略化して再現したNode.jsのコードだ。社内の実装そのものではなく、要点だけを抜き出した再現コードであることを明記しておく。このコードはエスカレーションをログに出力するだけで、実際のキューAPIへの登録・永続化は行っていない。
function withRetry(taskName, fn, maxAttempts = 3) {
return new Promise((resolve) => {
let attempt = 0;
function run() {
attempt++;
Promise.resolve()
.then(() => fn(attempt))
.then((result) => resolve({ ok: true, result, attempt }))
.catch((err) => {
const normalizedErr = err instanceof Error ? err : new Error(String(err));
if (attempt >= maxAttempts) {
escalateToApprovalQueue(taskName, normalizedErr, attempt);
resolve({ ok: false, error: normalizedErr.message, attempt });
return;
}
const waitMs = 2 ** attempt * 100; // 指数バックオフ（簡略版。実運用は秒単位）
console.log(`[retry] ${taskName} attempt=${attempt} failed: ${normalizedErr.message} -> ${waitMs}ms後に再試行`);
setTimeout(run, waitMs);
});
}
run();
});
}
function escalateToApprovalQueue(taskName, err, attempt) {
console.log(`[escalate] ${taskName} は${attempt}回失敗 -> 承認キューへの登録をログで模擬: ${err.message}`);
}
withRetry('sample-api-call', async () => {
throw new Error('API failure');
}).then(console.log);
Node.js v23.6.1で実際に上記の呼び出しを実行し、常に失敗するAPI呼び出しを模した関数を渡したところ、1回目・2回目はバックオフ待ちのログが出て、3回目で承認キューへのエスカレーションログが出力されることを確認した。この3回という回数は、3回連続失敗した処理を通知するための運用上の閾値であり、失敗回数だけで重大度や一時性まで判別しているわけではない（認証失敗や入力不正のような再試行しても直らないエラーも同じ3回まで試行してから通知される）。
もう一つ注意がある。この再現コードは渡された関数を中身に関係なく再実行するので、メール送信や決済のような副作用のある呼び出しをそのまま渡すと、「相手側では処理済みだが応答だけがタイムアウトした」ケースで同じ操作が二重に実行されうる。自動で再試行してよいのは、副作用のない読み取り系の呼び出しや、冪等性キーなどで同じ操作を再送しても副作用が重複しない呼び出しに限るべきだ（冪等でも、返ってくる内容まで毎回同じになるとは限らない）。結果が分からないまま失敗した副作用のある操作は、再実行せずに人の判断へ回す方が安全である。レートリミット（HTTP 429）でRetry-Afterが返る場合はその値に従う、といった調整もこのコードには入っていない。
ここで肝になっているのは、「外部に影響する操作を実行するかどうかは必ず承認キューで人が決め、再実行しても安全な呼び出しの一時的な失敗だけを自動で再試行する」という線引きだ。何でも自動化してしまうと誤操作のリスクが上がるし、何でも人間に確認を求めると自動化の意味がなくなる。内部操作は自動、外部向け操作だけ承認必須、という境界線を引いたことが、長期運用で事故を増やさないための分岐点になった。
ペルソナ設計と生成物の検証
複数のエージェントを並行稼働させていると、出力の形式がエージェントごとにばらつく問題にもぶつかった。元々は監視・バックアップ・ログローテーション用のシェルスクリプトが10本以上あり、書いた人が違うせいでエラーハンドリングも通知の出し方もまったく統一されていなかった。これに対しては、全スクリプトを読み込ませて統一テンプレートへのリファクタリングを依頼し、エラーハンドリング・ログ出力・通知の仕組みを標準化した。人間の組織でいう「書式統一」を仕組みで強制するのと同じ発想だ。この境界線を引いたあとは、障害発生時の通知漏れがなくなり、運用トラブルへの対応が体感としてかなり早くなった。
もう一つ、AIが書いたコードをそのまま信頼しないという点も私の運用では外せない。以前、約3万行規模のWebアプリケーションに対してOWASP Top 10の観点でレビューをかけたところ、十数箇所の潜在的な脆弱性が見つかり、そのうち複数が、SQLインジェクションにつながり得る未パラメータ化クエリ候補だった（攻撃者が制御可能な入力がそのSQL文へ実際に到達するかというデータフロー検証までは行っておらず、悪用可能性の高さを断定できるものではない）。外部の専門診断は高額で予算が合わなかったが、AIによるレビューを「まず自分でできるチェック」として挟むだけでも、既に契約しているAIサービスの範囲内で追加費用なしに最初の網をかけられる。これも「信頼するのは成果物」という元記事の思想と、方向性としては重なる部分だと思う。
まとめ
月2,500件のPRを支える基盤の話を読んで、規模の差に圧倒されるだけで終わらせたくなかった。実際に手を動かして自分の運用を棚卸ししてみると、「エージェント自体ではなく成果物を信頼する」「内部操作は自動・外部操作は承認必須」という線引きは、規模が違っても同じ形で効いてくる原則だとわかった。結局のところ、規模を追いかける前に、自分が一度ヒヤッとした場面をちゃんと設計に落とし込めているかを確認するほうが、今の自分には優先度が高いという結論になった。
私はこのやり方に落ち着きましたが、もっと良い手があれば知りたいところです。複数エージェントが同じリポジトリに書き込む構成で、衝突や誤操作をどう防いでいますか——みなさんはどうしていますか？ コメントで教えてもらえると助かります。