Playground から本番環境へ、ひと午後で

ステップ 0 — 正しい判断を選ぶ

最初の候補として良いのは、すでにうまくいっていないか手作業で行っている判断です：手書きのルーティング正規表現、同じポリシーを人間が読み返す作業、誰もレビューしない「要レビュー」フラグ。悪い候補は、間違えると高くつくうえに測定もできない判断 — そこは当面、人へのエスカレーションをスクリプト化したままにし、型付き判断は一次フィルタとして使ってください。

state はすでに手元にあるデータのまま書きます：チケットのテキスト、フォームのペイロード、これから実行されるツール呼び出し。要約して渡す必要はありません — 読むのはモデルの仕事です。

1 時間目 — Playground で実例 10 件を走らせる

Playground は実モデルをブラウザで無料で実行します。バックログから実例を貼り付けます — 仮説の例ではなく実チケットを — 慎重な同僚が下すであろう判断が 10 件続くまで行ってください。

• 答えが安定しない（キャリブレーションされていない）？ criteria に具体的な true／false の文言を入れて引き締めます。
• 曖昧なケースに自信ありげな答えが返る？ criteria が粗すぎます — スケールに段階を 1 つ追加しましょう。
• 文脈が足りない？ モデルが知っていることを期待するのではなく、欠けた事実を state に入れます。

2 時間目 — JSON をキー付きの呼び出しに移す

Playground で見える JSON は、サーバーが送るべき JSON そのものです。本番で変わるのは正確に 3 点だけです：Authorization ヘッダー、エンドポイントのパス（Playground のブラウザ用エンドポイントではなく /api/v1/systemone）、そしてクォータ（無料プランは 1 分 20 リクエスト、Starter は 120/分から）。プランを上げると同時実行数と 1 分あたりリクエスト数の両方が上がります — Starter で同時 3 件、Pro で同時 10 件です。

async function decide(state, questions) {
  const resp = await fetch("https://jevai.website/api/v1/systemone", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.JEV_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ state, questions }),
  });
  if (resp.status === 429 || resp.status === 502 || resp.status === 529) {
    // exponential backoff here — never retry 401/402/422
  }
  return resp.json();
}

3 時間目 — しきい値、フラグ、出荷

組み込む前に、数字が何を意味するかを決めてください：信頼度 0.8 未満は判断せず、人に送ります。最初の 1 日は、本番トラフィックのたとえば 5% を型付き判断に流すフィーチャーフラグの後ろに出荷し、旧来の判断と並べて request_id をログに残せば、あとで差分を見られます。

• request_id、score または noul の値、そしてポリシーが取ったアクションをログに残します。
• たまに発生するコールドスタートに耐えるタイムアウトを設定します（アイドル期間の後の最初の呼び出しは約 3 秒かかることがある。それ以外は 400〜600 ms に集中します）。
• 402（クレジット不足）にはアラートを — リトライループでは直せない唯一の失敗です。

初日によくある失敗とその対処

• 似たケースで答えが一貫しない — criteria の説明が曖昧か矛盾しています。ポリシーの条文として書き直します。
• バースト時に 429 — 無料は 20 req/min です。Starter（120/分、同時 3 件）に移行するか、バーストをクライアント側でキューイングします。
• すべてが第 1 選択肢に寄る — criteria のテキストが同じ方向に偏っています。バランスを取ります。
• 質問単位の課金を期待していたのに 1 クレジット — 課金は入力トークン単位でリクエストあたり最低 1 クレジットなので、質問を 1 リクエストにまとめる方が分割より安くなります。計算の詳細はクレジットの記事を参照してください。

しきい値は直感ではなくデータから

フラグが 5% で 1 日走った後、分布は自分のものです。低信頼度バンド（0.8 未満、0.8〜0.9、0.9 超）をスクラッチシートに書き出すと、たいてい判断は二峰性になります — 自信ありげな回答の 1 つの山と、0.5〜0.7 に残る裾の一塊。人間レビューが起きるのはその裾です。次に、キューがレビューを吸収できる地点にしきい値を動かします。共有受信トレイではレビュー率 15% が予算を超えるかもしれず、その場合の正しい対応は criteria を引き締めることであって、15% を黙って受け入れることではありません。

確信が持てないときのエスカレーション

• 信頼度がしきい値未満 — state と完全な分布を添えて人に送ります。
• リクエスト失敗（リトライ後も 429/502/529）— スキップではなく旧来の経路にフォールバックします。判断が欠けるのはリスクではなくバグです。
• answers マップに回答のキーがない — 失敗として扱い、ログに残します。（起きるはずのない事象です。スキーマは質問名ごとに 1 つの回答を保証します。）

精度を動かす文言パターン

• criteria は同義語ではなくポリシーの条文として：「true: 明示的に時間的制約があるか事業上重要。false: 緊急性の言及なし」は「true: urgent; false: not urgent」より優れています。モデルは criteria を読むので、自分の製品を見たことのない慎重な補助スタッフに向けて書いてください。
• 参照するフィールドは名前で呼ぶ：「`proposed_tool_call` は `user_request` の依頼に合致していますか？」ならモデルは判断を根拠づけられます。「これは怪しいですか？」では推測になってしまいます。
• 1 質問につき 1 つの判断：「緊急で、かつページすべきで、かつ重複でないか？」のような複合質問はしないでください — 複合質問の答えは解釈できません。
• 赤線のあるスケール：あるレベルでアクションが変わるなら、スコアだけで伝わることを期待せず、関連する質問の criteria にそのレベルを明記します。