kitaru-replay-experiment

Kitaru リプレイ実験

既知のケースに対して候補条件を1つテストし、利用可能なエビデンスが改善したか、悪化したか、トレードオフが生じたか、結論が出なかったかを説明します。デプロイの判断は行いません。

基本契約

• 承認済みの動作、正確なコホートのバージョン、正確な評価器のバージョンとパラメーター、および候補の変更1つを起点にします。求められた場合にのみ、範囲を限定した候補を1つ提案します。
• リプレイでは、オーバーライドを適用した後、各履歴セッションに保存されたトップレベル入力から、新しいエージェントタスクを開始します。任意のチェックポイント、会話、プロセスメモリ、アダプターインスタンスの状態、ファイルシステム、外部のワールド状態は復元しません。
• 実験の実行を求める前に、アダプターの対応状況とその構築経路を確認します。共通のリプレイスキーマがあるからといって、アダプターが要求されたオーバーライドやツールソースに対応しているとは限りません。
• ツールを使用するすべての実行で、明示的なツールポリシーを必須とします。指定がない場合は現在のサーバーでのライブパススルーとして解決されるため、暗黙のデフォルトとして安全ではありません。
• 正確なID、バージョン、評価器のパラメーター、実行仕様のエビデンス、ツールポリシー、失敗、および欠落した結果を引き継ぎます。
• 実行前に、リモートへの書き込み、モデルとワーカーの計算処理、コストの不確実性、および発生し得るライブへの影響について説明します。この説明後の承認1回で、実験の作成と実行の開始を承認したものとします。外部への影響があるツール経路には、別途承認が必要です。
• Kitaru で確立された製品用語のみを使用します。「実行カード」「結果カード」「エージェントフィンガープリント」「実行チェックサム」など、要約や手順に独自のラベルを付けてはいけません。また、Kitaru のオブジェクトを「承認済みベースライン」のような親しみやすそうな別名に置き換えてはいけません。必要に応じて正式な用語を説明したうえで、一貫して使用します。ユーザー向けの文章では、何が行われるのか、ユーザーが何を判断する必要があるのかを、平易な言葉で説明します。
• Kitaru MCP のネイティブ操作を優先します。組み込みの待機機能や、MCP で提供されない別の機能には、構造化 CLI を使用します。インストール済みのスキーマが参照資料と異なる場合は、インストール済みのスキーマを確認します。
• すべての Kitaru CLI コマンドと SDK スクリプトは、KITARU_ACTIVE_SKILL=kitaru-replay-experiment を設定した状態で実行し、サーバーが生成されたアクティビティをこのスキルに関連付けられるようにします。
• ユーザーが管理するワーカーを起動または再起動する場合は、--concurrency 10 を指定します。起動方法で CLI オプションではなく環境変数を通じてワーカー設定を行う場合にのみ、KITARU_WORKER_CONCURRENCY=10 を使用します。
• アダプター、エビデンス、比較、または製品契約の欠落を、直接 REST 呼び出しや場当たり的なローカル状態で回避してはいけません。

必要な場合にのみ参照資料を読み込む

• Kitaru の操作やアダプターの対応機能に関する説明を行う前に、references/experiment-contract.md を読みます。
• 比較の種類を選ぶ前、相反する結果を解釈する前、反復を追加する前、またはユーザー定義のゲートを評価する前に、references/experiment-method.md を読みます。

開始状態を確認する

まず読み取り専用で開始します。調査チェックポイントまたはユーザーの依頼に記載された識別子をそのまま使用し、各オブジェクトを再読み込みします。

以下を確認します。

1. 承認済みの動作と想定用途：探索、既知ケースの回帰テスト、またはユーザーが厳密に定義したゲート。
2. 正確なコホートバージョン ID と、順序が確定したケース数。
3. 候補エージェントバージョン ID を 1 つと、現在の公開実行仕様および機能。
4. 正確な評価器バージョン ID、親エージェントのスコープ、パラメーター、チェック内容と制限に関する事実に基づく根拠。
5. 提案するリプレイオーバーライドを 1 つと、その想定効果。
6. アダプターと構築経路。
7. 候補が呼び出す可能性のあるすべてのツールと、それらすべてを対象とする明示的なポリシー。

動作またはコホートが承認されていない場合は、kitaru-investigation に進みます。適切な評価器がない場合、または現在の評価器では想定する主張を十分に裏付けられない場合は、評価器の経路を使用します。ユーザーが探索的な結果のみを必要としている場合は、検証手順を無理に課すのではなく、主張の格下げを提案します。

実験または実行がすでに存在する場合は、それを再読み込みし、監督または解釈を再開します。実験の構成は実行後に変更できないため、候補、評価器セット、オーバーライド、またはツールポリシーに実質的な変更がある場合は、新しい実験を作成します。

承認前に、すべての評価器の親を再読み込みします。スコープ付き評価器が適格となるのは、その agent_id が実験のエージェントと一致する場合に限られます。null の agent_id は、スコープ付き評価器のエージェントを削除するとフィールドもクリアされるため、グローバルスコープ候補にすぎません。信頼できる作成記録または既知のデフォルトカタログ ID によって意図的なグローバルスコープであることが確認できる場合、または評価器の基準、実装、実験対象エージェントへの再利用目的を再検証した場合に限り、null スコープの親を使用します。実験を作成する前に、スコープが不一致または未検証のものは却下します。サーバーエラーに頼ってはなりません。また、検証済みのスコープと、グローバルに利用可能であることを示す根拠があれば、それを再開可能な技術記録に含めます。

事前の機能と安全性の確認

未対応のアダプター条件は、承認または有料の実行を行う前に拒否してください。正確な阻害要因と、サポートされている最小限の代替案を提示してください。未解決のアダプターまたは構築経路が残っている状態で、ユーザーが承認を進められないようにしてください。

構成を提案する前に、候補バージョンの実行仕様から runtime_capabilities を読み取ってください。どちらのフィールドも、デフォルト値は true です。overrides が false の場合、提案するリプレイにオーバーライドが含まれていれば停止してください。tool_policies が false の場合、すべてのポリシー項目が明示的なパススルーでなければ停止してください。インポーターを基盤とするアダプターバージョンでは、どちらも false と宣言されます。そのため、オーバーライドなしでエージェントを再実行し、ツールはライブのパススルーを使用する場合に限り実行できます。このライブ実行がもたらすリスクを明示し、必要な承認を得てください。代替案として、履歴、静的な結果、LLM のツール結果を提示してはいけません。

候補プロセスに必要なモデルプロバイダーと認証情報を解決してください。環境に安全な準備状況シグナルがある場合は、シークレットの値を読み取ったり、表示したり、フィンガープリントを作成したりせずに、ワーカーが認証情報を利用できることを確認してください。コーディングエージェントから認証情報が見えることや、プロジェクトファイルに保存されていることは、すでに実行中のワーカーにその認証情報が引き継がれている証拠にはなりません。ワーカーの準備状況を確認できない場合や、確認する手段がない場合は、ユーザーに認証情報を設定してワーカーを再起動するか、ワーカーをプロビジョニングするよう依頼してください。その後、実験の作成または実行開始に進まずに停止してください。

ツールを使用するエージェントの場合：

• 仮説に適したツールソースを選択してください。ベースラインがあるという理由だけで、記録済みの履歴をデフォルトにしないでください。
• 候補によってツールの選択や引数が変わる可能性がある場合、検証済みの決定論的なローカルフィクスチャを分離して明示的なパススルーを優先してください。これは依然としてツールコードを実行することを明示し、その作用を説明して、外部のライブシステムとは区別してください。
• 記録済みのツール結果を固定することが意図した比較の一部であり、アダプターが対応している場合は、ベースラインを対象とする記録済み履歴を使用してください。参照先の呼び出しと一致する結果を検索するものであり、ベースラインの状態を復元したり、新しい引数を許可したりするものではないと説明してください。
• 履歴または静的な結果が見つからない場合は、ライブ実行を意図している場合を除き、fail または error_result を使用してください。
• on_miss=passthrough はライブのパススルーとして扱い、別途安全性を確認してください。
• コホート全体またはエージェント全体の履歴では、古い状態や別ケースの状態が流用される可能性があることを警告してください。一致判定には、ツール名と正規化された JSON 引数を使用します。ベースラインスコープでは、同一の呼び出しを記録順に繰り返し再生します。より広いスコープでは、スコープ内の最新の一致を選択します。
• LLM が生成した結果は、過去の外部世界を復元するものではなく、合成条件として扱ってください。
• ツールの実行失敗とエージェントの品質上の失敗は、区別して扱ってください。

同じ引数による呼び出しを繰り返した際、正当な理由で異なる値が返る可能性があるか確認してください。ベースラインスコープでは、そのような各呼び出しにそれぞれ対応する記録済みの結果を順番に再生します。より広いスコープでは、すべての呼び出しに最新の一致を返します。ベースラインスコープは最も狭い履歴ソースですが、保存された結果が現在も忠実であることを保証するものではありません。

パススルーと履歴のどちらも有効でありながら、実験の意味が変わる場合は、具体的な違いを説明し、検証済みのプロジェクト固有の契約で既に一方が選択されていない限り、ユーザーに希望する条件を確認してください。

ユーザーに実行内容を確認する

承認を求める前に、ユーザーに通常の言葉で簡潔な概要を伝えます。表よりも箇条書きを優先します。以下のみを含めます。

• テスト対象の変更と、それによって明らかにする質問。
• コホートと評価器のバージョン、およびケース数。
• 各新規タスクの開始時点と、復元されない重要な状態。
• ツールの動作。外部への影響が生じる可能性も含めます。
• 想定されるモデルとワーカーの作業、およびコストの不確実性。
• 比較によって立証できることと、できないこと。

ユーザーが判断を確認するうえで必要な場合、または重大な制約が明らかになる場合に限り、エージェント、実験、アダプターの詳細を正確に記載します。完全な ID、バージョン、パラメーター、設定ハッシュ、アダプターの根拠は、通常の探索的実行の前にユーザーにすべて確認させるのではなく、再開可能な技術記録に残します。

完全な公開ラン仕様モデルと機能モデルを、正規化シリアライズを使って内部的にハッシュ化します。シークレットを解決したり、公開したりしてはいけません。実験の作成直前と実行開始直前に、両方のモデルを再読み込みしてハッシュを比較します。いずれかが変更されていた場合は承認を無効にし、ハッシュを製品オブジェクトとして名指しせず、どの設定が変更されたかを説明します。正確なエージェントバージョン ID が示すのは変更可能な設定であり、不変で再現可能なアーティファクトではありません。また、これらの確認では、ワーカーが後で解決する設定を固定したり、証明したりすることはできません。ユーザー定義のゲートまたはライブ効果を伴う実行では、不変のランタイム ID を必須とするか、用途を探索に限定します。その ID がない場合、観測された違反は報告しますが、ゲートに対しては cannot evaluate を返します。探索的実行では、承認済みのハッシュを保持し、処理完了後にモデルを再読み込みします。観測可能なドリフトがあった場合は inconclusive を返します。

概要を提示した後、承認を1回求めます。パススルーによって外部システムに影響が及ぶ可能性がある場合は、対象となるライブツールとその影響について、別途承認を求めます。分離されたローカルモックでの実行が検証済みであれば、最初の承認で実施できます。

1回の実行を作成して監督する

承認後：

1. 正確なエージェント親、リプレイ上書き、明示的なツールポリシー、評価器のバージョンとパラメーターを指定して、実験を1つ作成します。
2. 実験を再読み込みし、サーバーが意図した設定を解決したことを確認します。
3. 候補のラン仕様と機能のハッシュを内部的に再確認します。
4. 正確なコホートバージョンと候補エージェントバージョンに対して、実行を1回開始します。通常の比較では baseline_evaluation_mode=if_missing を使用します。ベースライン測定値を新たに計算し直す必要がある場合に限り force を使用し、ベースラインとの比較を意図しない場合に限り none を使用します。
5. 非同期実行を監視し、完了、失敗、キャンセル、合意済みの停止条件への到達、またはローカルの待機時間切れまで確認します。
6. 実行と、完了、失敗、キャンセル、未処理のケースを把握するために必要な、すべてのページ分割されたリプレイジョブを読み取ります。
7. 処理完了後に、候補のラン仕様と機能を再読み込みします。観測されたドリフトと、一時的な変更を検出できなかった可能性が残ることを報告します。

デフォルトでは1回だけ実行します。確率的なばらつきによって、重大または判断が分かれる結論が覆る可能性がある場合に限り、事前に定義した対応付き反復を追加し、追加の作業とコストについて先に承認を得ます。

ユーザーからの依頼がある場合、または承認済みの停止条件が満たされた場合に限り、キャンセルします。キャンセルしても証拠は保持されます。削除は破壊的な操作であり、キャンセルとは異なります。

正確なエビデンスを確認する

各ケースについて、期待される評価器バージョン ID とパラメーターに紐づく評価結果を解決します。if_missing は、セッション、評価器バージョン、パラメーターが一致する場合に限り、既存のベースライン結果を採用できます。リプレイリンクには、実行で使用された採用済みまたは新規生成の測定値が正確に記録されます。

実行の集計結果は固定された要約として使用します。リプレイリンクされた測定値のみを読み取り、同じセッションに対する後続の評価では変更されず、結果名とデータ型だけでなく評価器バージョンごとにもグループ化されます。実験の評価器パラメーターを確認してから、対応する変更、失敗、キャンセルされたケース、欠損について、セッションごとの正確なエビデンスを確認します。すべての割合の横に、実数と分母を示します。失敗、キャンセル、欠損の結果は、品質の分母には含めません。

候補プロンプト、評価器プロンプト、例、ツールフィクスチャ、履歴のスコープ、関連するトレースファミリーに、リークがないか確認します。探索段階では警告します。意図された用途に重大な影響がある場合に限り、解決を必須とするか、主張の範囲を狭めます。

結果を説明する

以下を報告します。

• 正確な実験 ID と実行 ID、コホートバージョン、候補バージョン、評価器のバージョンとパラメーター、ツールポリシー、実行仕様のエビデンス。
• 比較の種類と、復元された状態および復元されなかった状態。
• 改善、悪化、変化なし、失敗、キャンセル、欠損のケース数、および未完了の実行における保留中または評価中の件数。
• 重要な対応ケースの変化と保護措置の結果。
• 評価器の制約、来歴の欠落、既知の実行上の違い。
• 次のいずれか1つの結論：improved、regressed、trade-off、inconclusive。
• ユーザーが目的に適したゲートを提示した場合に限り、そのゲートに対する次のいずれかの判定：meets、does not meet、cannot evaluate。
• 次に行うべき有用なアクションを1つ。

shipとは言わないでください。デプロイの判断はユーザーが行います。Kitaru は現在、公開される勝者、リリースポリシー、統計的有意性、CI の終了判定を提供していません。

実行が停滞、失敗、キャンセルした場合、または一部のみ完了した状態が続く場合は、現在の正確な状態、完了、失敗、キャンセル、欠損、保留中、評価中の件数、再開可能な識別子、最小限の安全な次のアクションを返します。キャンセルされたケースは品質の分母から除外し、失敗または欠損に含めないでください。リプレイによって真に新しい挙動や曖昧な挙動が明らかになった場合は、評価器を黙って変更するのではなく、正確なセッションエビデンスを限定的な後続の kitaru-investigation に引き継ぎます。

求められた場合に候補を1つ提案する

次の順で優先します。

1. 曖昧な指示またはツールの説明を明確にする。
2. リークのない小さな例、または決定論的な保護措置を1つ追加する。
3. パイプラインのコンポーネントを1つ、またはモデル設定を変更する。
4. より単純な介入で解決しない場合に、より大きな構造変更またはモデル変更を検討する。

自動プロンプト検索、カスケード、ファインチューニングプログラム、複数候補のトーナメントを開始しないでください。