runtime-behavior-probe

ランタイム動作の調査

概要

コードやドキュメントの内容を言い換えるのではなく、実際のランタイム動作を調査するには、このスキルを使用します。まず調査を計画し、次にケースマトリックスを実行して、観察した動作を記録したうえで、調査結果とその取得方法の両方を報告します。

基本ルール

• このスキルは手動でのみ使用してください。暗黙的な呼び出しには依存しないでください。
• このスキルの呼び出しによって許可されるのは計画のみです。実行時の各プローブには、提案したプローブの内容をユーザーに提示したうえで、明示的な承認が必要です。このスキルの呼び出しや、実行時の動作を調査するという一般的な依頼を、実行の承認とみなしてはいけません。
• 承認を求める前に、提案するプローブについて、ソースの識別情報、正確なコマンド、間接的に実行される要素、既知のファイルシステム、環境、ネットワーク、ホストサービスに対する機能、想定される副作用、制御方法を開示してください。機能が不明な場合は、利用できないと決めつけず、不明であると明記してください。
• 実行前に、明確な承認を待ってください。承認の対象は、開示したソース、コマンド、実行される要素、機能の範囲に限られます。これらのいずれかを変更する場合、別のプローブを追加する場合、または承認済みの対象範囲を広げる場合は、改めて承認を得てください。
• ベースラインの成功ケースやスモークテストが適切な開始点となることはよくありますが、実際の疑問にエッジケース、ドリフト、失敗時の動作が関わる場合は、そこで止めないでください。
• 実行前に計画してください。まずケースマトリックスを作成し、その後で観測結果を記入してください。マトリックスは作業メモ、一時ファイル、またはプローブスクリプトのヘッダーに記載できます。
• 原則として、ローカルまたは読み取り専用のプローブを提案してください。ライブサービスは明らかに関連する場合にのみ検討し、そのうえで、承認を求める前に以下の簡易ゲートを適用してください。
• プローブの規模は判断の目的に合わせてください。まず、現在の仮説を否定または検証できる最小のマトリックスから始め、不確実性が残る場合にのみ拡張してください。
• ライブプローブの前に、次の3つの簡易ゲートを適用してください。
  • 宛先ゲート。タスクで明確に許可されているライブの宛先のみを使用してください。
  • 意図ゲート。ユーザーがその統合に対する実行時の検証を明示的に求めている場合、またはプローブの提案後に明示的に承認した場合に限り、ライブプローブを実行してください。
  • データゲート。プローブで環境変数を読み取る、リモート状態を変更する、相応のコストが発生する、または非公開データやユーザーデータを使用する場合は、対象となる変数名またはデータの種類を明示し、事前に明示的な承認を得てください。
• 各ケースは、実行前に読み取り専用、変更あり、またはコスト発生ありに分類してください。変更ありまたはコスト発生ありのケース、あるいは環境変数を読み取るライブケースでは、プローブ実行前にクリーンアップまたはロールバックの手順を定めてください。
• 単発のプローブスクリプトには一時ファイルまたは一時ディレクトリを使用してください。
• 最終回答の作成が終わるまで、一時的な成果物を保持してください。その後、ユーザーが保持を依頼した場合や、後続作業に必要な場合を除き、原則として削除してください。成果物を削除した場合でも、報告にはコマンドの形式、実行時のコンテキスト、成果物の状態を簡潔に記載してください。
• 環境変数を読み取るライブプローブを実行する前に、使用予定の正確な変数名とその理由をユーザーに伝え、明示的な承認を待ってください。例として、OPENAI_API_KEYや、対象システムで想定されるその他の標準的な変数名があります。
• 環境変数の承認ゲートが必要で、request_user_inputツールが利用できる場合は、通常のテキストで承認を求めるのではなく、このツールを使用してください。Allow once (Recommended)やDo not allowのような、相互に排他的な選択肢を含む簡潔な質問を1つだけ提示し、autoResolutionMsは省略してください。承認は、指定された変数と宛先に対する単一のプローブに限定してください。このツールが利用できない場合は、簡潔なテキストで承認を求め、ユーザーが明示的に承認するまで先に進まないでください。
• 標準の環境変数から取得した場合であっても、秘密情報を決して出力しないでください。
• このリポジトリでOpenAI APIまたはOpenAIプラットフォームのプローブを行う場合は、まず早い段階で$openai-knowledgeを使用し、サポートされるパラメーター、フィールド名、上限など、仕様に関わる詳細を確認してください。実行時プローブは、ドキュメントの確認を省略するためではなく、記載された動作を検証または再検討するために使用してください。ドキュメント用MCPが利用できない場合は、公式のOpenAIドキュメントを代わりに参照し、その代替手段を報告してください。
• ベンチマークまたは比較のプローブでは、実行前に比較条件の公平性を明確にしてください。固定する条件、検証対象の変数、公平な比較を保つためのレスポンス形式の制約、レイテンシーやコストの解釈に関わる使用量またはトークン数のカウンターを記録してください。
• OpenAIのホスト型ツールのプローブでは、実行時の動作が原因だと判断する前に、セットアップに関する曖昧さを解消してください。
  • ツール呼び出しが前提となる疑問では、対応するtool_choiceを指定してツールの使用を強制してください。
  • container_autoとcontainer_referenceは、互換性のあるセットアップの詳細ではなく、別々のケースとして扱ってください。
  • プローブの結果を無効にしないよう、サポートされていないモデルまたはツールのオプションをあらかじめ取り除いてください。

Workflow

1. 調査対象を実運用上の言葉で言い換えます。実行時の対象範囲、主要な不確実性、テストすべきリスクの高い動作を明示します。
2. 簡単な事前確認を行います。まず関連するコードやドキュメントを確認し、質問にローカル検証とライブ検証のどちらが必要かを判断して、関係するリポジトリ、ベースライン、リリースの境界を記録します。
3. マトリックスを作成する前に、判定シグナルを定義します。不具合が疑われる場合は、ユーザーに見える具体的な症状、それを正しい動作と区別できるコマンドまたはプローブ、予想される失敗時の観測結果、既知の正常な対照ケースを明示します。そのシグナルが、隣接するヘルパーだけでなく実際の生成側と呼び出し側の経路を通ることを確認します。質問に答えられるなら、高速で決定論的なローカル実行ループを優先します。信頼できるシグナルを構築できない場合は、不足しているアクセス権または成果物を明示し、近接する別の動作を証拠の代わりにしないでください。
4. プローブを実行する前に、検証マトリックスを作成します。ベースラインの動作と、最も関連性の高い失敗またはドリフトのケースを網羅します。マトリックスは、作業メモ、一時ファイル、またはプローブスクリプト内の構造化されたヘッダーに記載できます。
5. 各ケースについて、事前に実行モードを選択します。
   • single-shot は、決定論的な単回実行のチェックに使用します。
   • repeat-N は、キャッシュ、リトライ、ストリーミング、中断、レート制限、並行処理など、実行ごとに結果が変わり得る動作に使用します。
   • warm-up + repeat-N は、初回実行のコールドスタートが結果を歪める可能性がある場合に使用します。 特別な理由がない限り、次のデフォルトを使用します。
   • 繰り返しの影響を受ける質問の簡易確認：repeat-3。
   • 意思決定に使えるレイテンシ評価またはリリース判断：warm-up + repeat-10。
   • コストの高いライブケース：まず repeat-3 で実施し、回答が不明確な場合に限って拡張します。 追加の実行に費やす時間やコストに見合うかが本当に不明な場合は、プローブを拡張する前にユーザーに尋ねます。
6. 質問がベンチマーク的または比較を伴う場合は、段階的に実行します。まず対照ケースを含む、シグナルの強いパイロットマトリックスを実施し、その後、結果に残った候補または未解決のケースのみを拡張します。
7. 回帰または動作変更の疑いに関する質問では、origin/main、最新リリース、または疑わしいオプションを使わない同一リクエストなど、既知の正常な対照ケースを少なくとも1つ追加します。
8. 比較プローブでは、実行前に条件の同等性を定義します。プロンプトまたは入力の形式、ツール選択の設定、モデル設定の同等性、状態の再利用ルール、公平な比較を保つための応答形式の制約を記録します。出力長に大きな差があり結果に偏りが生じる可能性がある場合は、使用量またはトークンに関する注記も記録します。
9. あるオプションが別のオプションと同等の知能や品質を持つかという質問では、マトリックスで示せるのが例示されたパターンの同等性に限られるのか、より広範な品質の主張を支えられるのかを判断します。より広範な主張をする場合は、少なくとも1つの、より難しいケースまたは自由度の高いケースを追加します。それ以外の場合は、結果が対象パターンに限られることを明記します。
10. 隠れた状態が結果に影響する可能性がある場合は、実行前に状態の制御方法を計画します。各ケースで状態を新規作成するか再利用するか、キャッシュの再利用または無効化をどう扱うか、繰り返し実行を分離する一意の ID をどう設定するか、クリーンアップをどう確認するかを記録します。
11. ライブケースで環境変数を読み取る場合は、ケースごとに正確な変数名と用途を一覧にし、実行前にユーザーの承認を求めます。この確認に request_user_input が利用できる場合は、デフォルトで承認されることのない設定とし、このプローブだけを許可または拒否する選択肢を用意します。承認を求める文面は簡潔にし、送信先、読み取り専用か変更またはコスト発生のリスクがあるか、正確な変数名、該当する場合はクリーンアップまたはロールバックについて記載します。
12. タスク固有のプローブスクリプトは一時領域に作成します。スクリプトは小さく、観測しやすく、簡単に破棄できるものにします。
13. openai-agents-python では、実行時コンテキストを明示します。

• 実用的な場合、Python プローブはリポジトリのルートから uv run python を使って実行します。
• 現在のコミット、作業ディレクトリ、Python 実行ファイル、Python バージョンを記録します。
• 別のチェックアウトや site-packages から誤ってインポートしないようにします。uv run python から外れる必要がある場合は、その理由と、代わりに使用したインタープリターまたは環境を正確に説明します。

14. 上記の開示事項を含むプローブ案をすべて提示し、各ケースまたは承認対象のマトリックスについて正確なコマンドを記載したうえで、ユーザーに明示的な承認を求めて待ちます。
15. 承認されたマトリックスだけを実行し、証拠を記録します。リクエストの形式、設定、観測結果の概要、予期しない結果または否定的な結果、エラーの詳細、実行時間、実行時コンテキスト、承認済みの環境変数名、繰り返し回数、ウォームアップの扱い、関連する場合はばらつき、クリーンアップの動作を記録します。比較では、一定に保った条件と、解釈に影響する応答形式または使用量に関する注記も記録します。
16. 推測ではなく、実際の結果でマトリックスを更新します。
17. 最終回答の作成が終わるまで一時的な成果物を保持します。その後、ユーザーから保持を求められた場合、またはフォローアップに必要な場合を除き、削除します。ベンチマークや繰り返し回数の多いプローブではフォローアップが必要になることが多いため、結果を再検討する可能性がある場合は成果物を保持するのが一般的です。削除した場合は、短い実行概要を保持して報告します。
18. まず調査結果を報告し、予期しない結果または否定的な結果があれば最初に記載します。次に、検証方法と対象ケースを要約します。
19. プローブで明確な不具合を1つ特定できた場合は、実装に関する仮説または最小限の再現手順を簡潔に含めてもかまいません。ユーザーから求められていない限り、より大規模な次の手順の計画には広げないでください。

検証マトリクス

ニュースを一目で把握できるマトリクスを使用します。expected と pass または fail だけでなく、まず実行時の疑問と観察結果の概要を軸にします。

少なくとも以下の列を含むマトリクスを使用します。

• case_id
• scenario
• mode
• question
• setup
• observation_summary
• result_flag
• evidence

調査に実質的な価値がある場合は、以下の列も追加します。

• comparison_basis
• variable_under_test
• held_constant
• output_constraint
• status
• confidence
• state_setup
• repeats
• warm_up
• variance
• usage_note
• risk_profile
• env_vars
• approval
• control

result_flag は、unexpected、negative、expected、blocked など、すばやく確認できるフィールドとして扱います。比較対象となる信頼できる比較基準、ベースライン、または文書化された仕様がある場合に限り、status を使用します。

マトリクスに以下のカテゴリを含めるべきか、必ず検討します。

• ベースラインの成功。
• 回帰が疑われる場合のコントロールまたはベースラインとの比較。
• 境界値の入力またはパラメーターの変更。
• 無効または未サポートの入力。
• 設定の不足または誤り。
• タイムアウト、ネットワーク中断、レート制限などの一時的な外部障害。
• 再試行、冪等性、またはクリーンアップの動作。
• 共有状態や順序が影響する可能性がある場合の、並行処理または重複する操作。
• 問いがパターンの同等性を超える場合の、自由形式の品質または知能に関するサンプル。

より詳細な優先順位付けモデルや再利用可能なケーステンプレートが必要な場合は、validation-matrix.md を開きます。

一時的なプローブスクリプト

使い捨てのスクリプトは、mktemp -d や Python の tempfile で作成した一時ファイルまたは一時ディレクトリに保存します。リポジトリ内のコードをインポートする場合でも、既定ではスクリプトをリポジトリの外に置きます。

プローブでリポジトリのコードが必要な場合は、次のいずれかを行います。

• リポジトリを作業ディレクトリとして実行する、または
• PYTHONPATH か同等のインポートパスを明示的に設定する。
• openai-agents-python では、リポジトリのルートから uv run python /tmp/probe.py を実行する方法を推奨します。

観測可能性を最大限に高めるようプローブを設計します。

• 実行しているシナリオを正確に出力またはログに記録します。
• Git SHA、作業ディレクトリ、Python 実行ファイルとバージョン、関連パッケージのバージョン、モデルまたはデプロイ名、エンドポイントまたはベース URL の別名、動作に実質的な影響を与える再試行やツールのオプションなど、実行時のコンテキストを記録します。
• ライブプローブでは、使用が承認された環境変数の名前のみを記録します。値は絶対に出力しないでください。
• 可能であれば、構造化された出力を取得します。
• エラーの種類、メッセージ、ステータスコードをそのまま保持します。
• 繰り返しに影響されるケースでは、試行インデックス、ウォームアップ状態、実行間の比較に役立つ安定した識別子を取得します。
• 繰り返し実行するプローブやベンチマーク形式のプローブでは、実用的であれば、生の結果と簡潔な概要アーティファクトの両方を書き出します。
• 分岐を最小限にし、各スクリプトが単一の狭い問いに答えるようにします。

一時スクリプトまたはディレクトリを削除する前に、スクリプトのパス、使用したコマンド、実行時のコンテキスト、証拠を保持したか削除したかを記した短い実行概要を残します。

軽量で使い捨て可能な Python プローブのひな型が必要な場合は、python_probe.py を開きます。

レポート

次の順序で報告します。

1. 調査結果。想定外の結果や否定的な結果を最初に記載します。特に新しい情報がなかった場合は、その旨を明記します。
2. 検証方法。使用したコード、検証したランタイムの範囲、実行モード、ケースマトリックスの網羅範囲を要約します。
3. ケースの結果。ケース数が多い場合は、マトリックスまたはその要約版を含めます。
4. 成果物の状態と簡単な実行概要。一時成果物を削除したか保持したかを明記し、保持した場合はそのパスまたは保存した概要を提示します。
5. 任意の実装メモ。明確な不具合を1つ特定でき、簡潔な実装方針が役立つ場合にのみ記載します。

比較プローブでは、固定した条件、検証対象の変数、結果がパターンの同等性のみを裏付けるのか、より広範な品質の主張も裏付けるのかも報告します。

推奨される回答テンプレートについては、reporting-format.mdを参照してください。

リソース

• ケースマトリックスの設計と優先順位付けには、validation-matrix.mdを参照してください。
• よくある失敗シナリオを追加するには、error-cases.mdを参照してください。
• 繰り返し使用されるOpenAIおよびResponses APIのプローブパターンについては、openai-runtime-patterns.mdを参照してください。
• 最終レポートの構成については、reporting-format.mdを参照してください。
• 最小限の使い捨てPythonプローブのひな形については、python_probe.pyを参照してください。