目的・処理特性が違うものは汎用機構に相乗りさせず、専用経路に分ける
設計判断
API設計
キュー設計
原則
一つの汎用ツール・キュー・タスク定義に、目的や処理特性の違うものを押し込まない。最適化するのは「経路ごとに最適な設定・挙動を選べること」、避けるのは「汎用機構へ相乗りさせ、片方に最適な前提(デフォルト上限・本文ペイロード・soft フィルタ・同一 worker 枠)が他方を黙って壊すこと」。
判断基準
- ある目的の候補集合を渡す経路に、汎用検索/一覧をそのまま流用しない。流用すると、デフォルト件数上限(全件欲しい経路で黙って頭打ち)、本文込みの重いペイロード、プロンプト遵守頼みの soft フィルタ(安全上守りたい条件が漏れる)を一緒に背負う。全件・軽い索引・hard なフィルタが要るなら目的専用経路にする。
- ヒット時の正しい挙動が逆方向の判定(一方は抑止、他方は促進など)を一本の検索に相乗りさせない。状態や種別で対象空間を分け、無差別検索で機能が静かに停止するのを防ぐ。
- 処理サイズ・所要時間が桁違いのジョブを同じキュー・同じ worker プールへ流さない。小規模ジョブ用の専用レーンと予約済み枠を持ち、長時間ジョブが枠を占有して短時間ジョブを待たせる構造を作らない。公平性機構は受信順の調整であって、worker 枠の占有問題そのものは解かない。
- 共有基盤で特定ジョブだけ仕様を変えたいときは、共有定義を触らず専用定義を横に足して起動経路で振り分ける。変更範囲が狭いうちは無理な共通化(過度な抽象)を避ける。
落とし穴
汎用機構へ相乗りさせても、上限・ペイロード・soft フィルタは消えるのではなく汎用側に隠れて残るだけ。分けないと後から条件追加で他用途を壊す。
検証
目的専用経路が、件数上限なしで全件返すか、不要な本文を載せていないか、呼び出し側からフィルタを外しても除外を維持するかを確認する。サイズ混在では、長時間ジョブで枠を埋めた状態で短時間ジョブの開始が許容時間内に収まるかを見る。
根拠(synthesize 元)
- 545 候補集合を渡す経路に汎用検索/一覧ツールを流用しない
- 542 非同期バルクジョブは処理サイズ別レーンと予約済み実行枠で短時間ジョブの待ちを防ぐ
- 234 同一バッチ基盤で特定ジョブだけスペックを変える際の設計方針(専用定義を横に足す)