AIチュートリアル

JevHarnessで高速かつタスク特化型の意思決定パイプラインを構築する

JevHarnessがタスクの観測結果を構造化された低レイテンシの意思決定に変換する仕組みを学びます。このチュートリアルでは、アーキテクチャ、Claude CodeとCodexのインストール、アーカイブ済みのPokémonの例、タスク特化型ハーネスの作成、評価に基づく改善、実行環境の要件、認証情報、トレース、検証済みハーネスを固定するための手法を解説します。

2026年9月22日約21分で読了

JevHarness の機能

JevHarness は、オーサリング LLM が Jev 用のタスク固有の意思決定ハーネスを作成できるようにします。ハーネスは、許可された観測結果を有用な特徴量に変換し、構造化された Jev の質問と基準を構築して、回答を合法的なタスクアクションに組み合わせます。

中心となる考え方は、高コストな戦略開発と日常的な実行を分離することです。

開発中に深く推論する。戦略を固定する。Jev には高速で曖昧さを含む判断を任せる。

開発中は、LLM がハーネスのコード、質問、グラフ、状態、基準、メモリを改訂できます。ハーネスを選択して固定した後は、実行時の意思決定にその固定されたロジックと Jev の呼び出しが使われます。オーサリング LLM は、すべてのアクションについて再び推論する必要がありません。

このため、JevHarness は、コードによって信頼できる事実を計算できる一方で、一部の判断が文脈依存または曖昧なまま残るタスクに適しています。たとえば、コードで合法的なアクションを判定し、数値特徴量を計算しながら、Jev によって利用可能なアクションのうちタスク固有の基準を最もよく満たすものを判断できます。

アーキテクチャと責任範囲

JevHarness は、信頼されたタスクアダプターと意思決定ハーネスを分離します。この境界により、ハーネスが自身の報酬を変更したり、隠されたタスク状態にアクセスしたりすることを防ぎます。

タスクアダプター: 観測結果、合法的なアクション、副作用、スコアリングを管理します。
ハーネス: 特徴量の構築、Jev による判断、意思決定ロジックを管理します。
環境: アクションを実行し、信頼できる結果または報酬を返します。
オーサリング LLM: 開発中および任意のリフレクション時にハーネスを作成または改訂します。

検証済みの PipelineSpec は PipelineRuntime を通じて実行されます。選択後は、パイプラインを仕様、ランタイム、評価器、宣言されたタスクリソースとともに固定できます。

主な機能

構造化された Jev の判断

Jev は choice、score、noul の回答タイプをサポートします。1つのリクエストに複数の名前付き質問を含めることができ、独立したグラフノードは並行して実行できます。

明示的な戦略表現

戦略は、コード、計算された特徴量、状態、指示、基準、メモリ、制御フローとして保持されます。これにより、意思決定プロセスがオーサリング中の会話の中に埋もれず、検査および再利用できるようになります。

完全な実行トレース

リフレクションでは、選択されたエピソードの完全な記録を受け取れます。記録には、観測結果、意思決定、ノードの入力と出力、Jev の質問と回答、メモリ、失敗が含まれます。ロスレス重複排除によって繰り返しを減らします。リフレクション入力が設定されたバイト制限を超えた場合、黙って切り詰めるのではなく、アーカイブして拒否します。

報酬ベースの任意の改善

任意の GEPA 統合では、インスタンスフロンティアから親を選択し、同じトレーニングバッチで各親と提案を比較し、採用された提案を Eval で評価します。却下された提案を含め、実際の系譜を記録します。

検査可能な固定済みアーティファクト

固定によって、選択されたハーネスと宣言された依存関係が保持されます。Jev ノードを含む固定済みハーネスには、実行時にも Jev が必要です。また、ホスト型モデルのエイリアスを使用しても、将来のプロバイダーの動作が変わらないとは限りません。そのため、保存済みのレスポンスと新規の呼び出しでは、再現性のレベルが異なります。

前提条件

実行したい内容に応じた要件を選択してください。

アーカイブ済みウェブサイト: Node.js と最新のブラウザー。モデルの認証情報、ゲームエンジン、Python サンドボックスは必要ありません。
Python プロジェクト: Python 3.11 以降。
機能的な Python ノード: 対応する macOS ネイティブサンドボックス。分離を利用できない場合、実行はフェイルクローズします。
バージョン 2 の式および Jev フロー: これらは機能的な Python ワーカーを起動しません。
ライブ Jev 呼び出し: 対応するプロバイダーのアカウントと、該当する API キー。
任意のオーサリングとリフレクション: ローカル Claude CLI、OpenAI、Azure、Anthropic エンドポイントのいずれかを使用する、設定済みの Proposer。

Claude Code にスキルをインストールする

Claude Code の最も簡単な設定方法は、リポジトリをプラグインマーケットプレイスとして追加し、プラグインをインストールして、プラグインを再読み込みすることです。

/plugin marketplace add https://github.com/TianyuCodings/JevHarness.git
/plugin install jev-harness@jevharness
/reload-plugins

プラグインをインストールすると、スキルとそのリファレンスがダウンロードされますが、Python の依存関係のインストールやモデル認証情報の設定は行われません。リポジトリが非公開の場合、GitHub 認証がすでに機能しており、アカウントに読み取りアクセス権が必要です。

Codex にスキルをインストールする

組み込みの skill-installer を提供する Codex ホストでは、リポジトリから直接インストールを要求します。

$skill-installer Install the jev-harness skill from https://github.com/TianyuCodings/JevHarness/tree/main/skills/jev-harness

次のターンでスキルを使用してください。Codex がすぐに検出しない場合は、セッションを再起動してください。

手動インストール

Claude Code、Codex、またはその両方にスキルを手動でインストールできます。/path/to/your-project は既存のプロジェクトディレクトリに置き換えてください。

git clone https://github.com/TianyuCodings/JevHarness.git
cd JevHarness
python3 scripts/install-skill.py --target both --scope project --project /path/to/your-project

これにより、Codex 用のプロジェクトレベルのインストール先として .agents/skills/jev-harness/ が、Claude Code 用として .claude/skills/jev-harness/ が作成されます。片方だけをインストールするには、--target codex または --target claude を使用してください。

プロジェクト間で利用できるユーザーレベルのインストールを行うには、次を実行します。

python3 scripts/install-skill.py --target both --scope user

個人用のインストール先は ~/.agents/skills/jev-harness/ と ~/.claude/skills/jev-harness/ です。インストーラーは、異なる既存のインストールを上書きしません。スキルが検出されない場合は、エージェントのセッションを再起動してください。

アーカイブ済みのPokémonサンプルを確認する

付属のPokémonサンプルには、アーカイブ済みの実行結果、選択されたハーネス、閲覧可能な進化ツリー、完全な意思決定記録、却下された提案、そしてJevの回答と同期したリプレイのハイライトが含まれています。このアーカイブの閲覧中にモデルへのリクエストが発生したり、ゲームが開始されたりすることはありません。

リポジトリをクローンします。
ウェブサイトをビルドします。
ローカルプレビューサーバーを起動します。
最新のブラウザでサイトを開きます。

git clone https://github.com/TianyuCodings/JevHarness.git
cd JevHarness
node website/build.mjs
node website/preview.mjs --port 8768

localhost:8768を開いてください。バトルアニメーションでは、公式のPokémon Showdownレンダラーからアセットをダウンロードします。アーカイブ済みのバトルログはブラウザ内に保持され、リプレイサーバーにはアップロードされません。

報告されたPokémonの結果では、5回のリフレクションラウンド後、Evalの勝率が25パーセント（12試合中3勝）から75パーセント（12試合中9勝）に向上しました。探索では、第3ラウンドの候補が最良のハーネスとして保持されました。これは選定用Evalセットで測定されたものであり、未知のゲームに対する性能の独立した推定値として扱うべきではありません。

基本的な意思決定を理解する

ハーネスは、state、名前付きの questions、回答の type、そして利用可能なアクションを評価するための instructions と criteria を含む、タスク固有のJevリクエストを作成します。

記録されたPokémonの例では、ハーネスが、SlowbroはGastrodonとのダメージレースで負ける可能性が高いと計算します。3つの技とScizorへの交代を含む、4つの合法な選択肢を提示します。アクションに関する質問では choice 型を使用し、一覧にあるアクションIDを1つだけ返すようJevに要求します。

{
  "questions": {
    "action": {
      "type": "choice",
      "instructions": "このターンだけでなく、バトル全体に勝つ可能性が最も高い単一のアクションを選択してください。",
      "criteria": {
        "switch:2": "Scizorに交代する。交代すると相手に1回分の無償攻撃を許す",
        "move:2": "Psychic。相手を倒すには約3回の攻撃が必要",
        "move:3": "Ice Beam。相手を倒すには約4回の攻撃が必要",
        "move:4": "Slack Off。予測される被ダメージが現在のHPを上回る"
      }
    }
  }
}

Jevはアクション選択確率 0.72 で switch:2 を選択し、ハーネスはその選択を受け入れます。この値は一覧にあるアクション同士を比較したものであり、プレイヤーがバトルに勝つ確率が72パーセントだと予測しているわけではありません。

記録されたリクエスト、回答、タイミング、出典情報の完全な内容は、Pokémonの12ターン目のJSON記録で確認できます。

独自のハーネスを構築する

Jevの指示や基準をすべて手作業で記述する必要はありません。インストールしたスキルを呼び出してタスクを説明すれば、コーディングエージェントが必要な契約の詳細を収集します。

Claude Codeプラグインの呼び出し

/jev-harness:jev-harness Build a harness that routes support tickets to the right team.
First clarify my inputs, legal actions, examples, success criteria, and budget.
If we have reliable rewards, add evaluation and reflection optimization.

スタンドアロンClaude Codeの呼び出し

/jev-harness Build a harness that routes support tickets to the right team.
First clarify my inputs, legal actions, examples, success criteria, and budget.
If we have reliable rewards, add evaluation and reflection optimization.

Codexの呼び出し

$jev-harness Build a harness that routes support tickets to the right team.
First clarify my inputs, legal actions, examples, success criteria, and budget.
If we have reliable rewards, add evaluation and reflection optimization.

スキルは、すぐにパイプラインを生成するのではなく、まずタスクの明確化を行う必要があります。次の情報を収集することが期待されます。

許可されるタスク観測情報と、隠れた状態の境界。
合法なアクションと、アクションの検証方法。
代表的な例と利用可能なデータ。
成功基準、報酬、または評価手順。
実行時および分離に関する要件。
認証情報とプロバイダーの利用可能性。
実験予算と最適化リソース。

契約が明確になれば、エージェントはハーネスを構築して検証できます。信頼できるフィードバックがあり、最適化を依頼した場合は、選択した結果を確定する前に、軌跡と報酬を使ってリフレクションを行えます。

Jevの認証情報を設定する

JevHarnessは、文書化されている次の2種類のJevトランスポート設定をサポートしています。

Vercel AI Gateway: JevClient(transport="vercel") を作成し、AI_GATEWAY_API_KEY を設定します。
TypeSafeを直接使用: JevClient(transport="typesafe") を作成し、TYPESAFE_API_KEY を設定します。

プロバイダーアダプターを使用しても、すべてのモデルやエンドポイントがアカウントで利用できるとは限りません。認証情報は環境変数、または無視対象にしたローカルの .env ファイルに保存してください。認証情報をタスクの観測情報、トレース、凍結済みアーティファクトに含めないでください。

ハーネスを評価して改善する

リフレクションは任意です。信頼できる報酬または評価方法がある場合にのみ使用してください。実用的なワークフローは次のとおりです。

タスクの境界を定義する。 隠れた状態、スコアリング、合法手の検証、そして副作用は、信頼できるアダプター内で管理します。
ベースラインのハーネスを作成する。 信頼性の高い特徴量はコードで計算し、コンテキストに依存する判断にはJevを使用します。
パイプラインを検証する。 PipelineSpecとランタイムがタスクの契約を満たしていることを確認します。
完全なトレースを収集する。 観測、ノード入力、出力、質問、回答、メモリ、失敗、報酬を保持します。
改訂案を提示する。 作成用LLMに証拠を調査させ、コード、プロンプト、グラフ構造、またはメモリを改訂させます。
公平に比較する。 同じトレーニングバッチで、親と改訂案を比較します。
採用した改訂案を評価する。 完全なEval評価を実行し、却下した改訂案も含めて、実際の候補の系譜を保持します。
選択したハーネスを固定する。 採用した仕様を、そのランタイム、評価器、宣言済みタスクリソースに紐付けます。

トレーニングの証拠とEvalの選択結果は、明確に分けて管理します。Evalを候補の選択に使用した場合は、未知のタスクに対する性能の不偏推定値ではなく、選択時の性能として報告してください。

レイテンシーと並行性

アーカイブ済みのPokémon Eval実行では、選択されたハーネスが1回の完全な意思決定を完了するまでの中央値は568ミリ秒でした。個々のJevリクエストの所要時間の中央値は269ミリ秒でした。初期ハーネスの完全な意思決定時間の中央値は678ミリ秒でした。

初期ハーネスの完全な意思決定: 中央値678ミリ秒、P95 1,495ミリ秒、238回の意思決定。
選択されたハーネスの完全な意思決定: 中央値568ミリ秒、P95 657ミリ秒、113回の意思決定。
選択されたハーネスの個々のJevリクエスト: 中央値269ミリ秒、P95 348ミリ秒、226件のリクエスト。

完全な意思決定時間には、特徴量の計算、並列Jev呼び出し、最終的なアクション選択が含まれます。個々のリクエスト時間には、クライアントとネットワークのオーバーヘッドが含まれます。並列呼び出しの所要時間は重複するため、合計してはいけません。バトルシミュレーションと作成またはリフレクションの時間は、これらの意思決定測定の対象外です。

これらのアーカイブ済みの観測値では、ローカルのレスポンスキャッシュヒットは除外されていますが、ランタイムのすべての意思決定をLLMが行う場合との統制されたベンチマークではありません。

高度なヒント

判断を求める前に事実を計算する

合法手、数値的な推定、しきい値、導出状態などの事実には、決定論的なコードまたは式を使用します。残りの曖昧な選択については、Jevに焦点を絞った状態と明示的な基準を渡します。

アクションの基準を具体化する

利用可能な各アクションを、タスクに関連する証拠を使って説明します。Pokémonハーネスでは、残り体力、ダメージ推定値、素早さ、一撃で倒すまでに必要なターン数、交代時に無料の攻撃を許すコストなどが基準に含まれます。

独立性が実際にある箇所では並列ノードを使う

独立したグラフノードは同時実行でき、複数の質問で1つのリクエストを共有できます。タスクが必要としない依存関係を導入しないようにしながら、これを活用できる形でグラフを構成します。

確率を正しく解釈する

選択確率は、リクエストで提示された選択肢の順位を示します。評価器が別途その意味を確立していない限り、タスク全体の成功確率として再解釈してはいけません。

失敗を完全な形で保持する

失敗からは、無効な前提、欠落した観測、脆弱な基準が明らかになることがあります。リフレクションが完全な証拠を受け取れるよう、成功した意思決定とともにトレースへ保持します。

暗黙の切り捨てを避ける

現実的なリフレクションのバイト上限を設定します。JevHarnessは、サイズ超過したリフレクション入力を切り捨てるのではなくアーカイブして拒否します。これにより証拠の完全性は守られますが、実験の規模を適切に計画する必要があります。

固定したロジックと固定したプロバイダーの挙動を区別する

ハーネスを固定すると、選択したパイプラインと宣言済みリソースは固定されますが、ホスト型モデルのエイリアスは時間とともに変わる可能性があります。正確な過去の検証が重要な場合は、記録済みのレスポンスを保持し、新たなプロバイダー呼び出しは異なる再現性の条件として扱います。

リポジトリマップを利用する

auto_jev/には、仕様検証、並列ランタイム、Jevトランスポート、リフレクション、GEPA、ストレージ、固定処理が含まれます。
examples/pokemon/には、信頼できるバトルアダプター、シード付きローカルエンジンブリッジ、ハーネス、プレゼンテーションコードが含まれます。
examples/pokemon/sample/には、選択されたハーネスと整理済みのウェブサイトアーカイブが含まれます。
docs/には、タスク作成用の資料、記録されたJev呼び出し、動画、スクリーンショットが含まれます。
skills/jev-harness/には、タスク固有のハーネスを作成するコーディングエージェント向けの指示が含まれます。
website/には、読み取り専用のデモとデプロイ用アダプターが含まれます。

まとめ

JevHarnessは、LLMが開発した戦略を、明示的で検査可能なランタイムロジックに変換します。まず厳密なタスク境界を定義し、スキルにパイプラインの構築と検証を行わせ、リフレクションに基づく改善を望む場合は、完全なトレースと信頼できる報酬を使用します。候補を選択したら、それを固定することで、通常の意思決定では、アクションごとに作成用LLMを呼び出すことなく、そのコードと焦点を絞ったJevの判断を利用できます。