eval-driven-dev

Python LLM アプリケーションの評価駆動開発

Python ベースの AI アプリケーションをエンドツーエンドでテストする自動評価パイプラインを構築します。実際のユーザーと同じ方法で、実際の入力を使ってアプリケーションを実行し、評価器で出力を採点して、pixie test で合否結果を生成します。

テストするのはアプリケーションそのものです。リクエスト処理、コンテキストの組み立て（データの収集方法、プロンプトの構築、会話状態の管理）、ルーティング、応答のフォーマットを対象とします。アプリケーションは LLM を使用するため、出力は非決定的です。そのため、assertEqual ではなく評価器（LLM による判定、類似度スコア）を使用します。しかし、テスト対象は LLM ではなく、アプリケーションのコードです。

評価中は、ルーティング、プロンプトの組み立て、LLM の呼び出し、応答のフォーマットなど、アプリケーション自身のコードが実際に実行されます。モックやスタブは一切使用しません。一方、アプリケーションが外部ソース（データベース、キャッシュ、サードパーティ API、音声ストリーム）から読み取るデータは、インストルメンテーションによってテストで指定した値に置き換えられます。つまり、アプリケーションのコードパス全体を実行しながら、各テストケースがアプリケーションに渡すデータを正確に制御できます。

ルール：アプリケーションの LLM 呼び出しは、実際の LLM に接続する必要があります。 LLM を偽の実装に置き換えたり、モック、スタブ、インターセプトしたりしないでください。LLM は価値を生み出す中心的なコンポーネントです。置き換えると評価が同語反復的になります（入力と出力の両方を自分で制御することになり、スコアに意味がなくなります）。プロジェクトのテストスイートに LLM をモックするパターンが含まれている場合、それらはプロジェクト独自の単体テスト用です。評価用 Runnable には絶対に採用しないでください。

成果物は、実際のスコアが得られる、正常に動作する pixie test の実行結果です。計画だけ、インストルメンテーションだけ、データセットだけでは不十分です。

このスキルでは、作業を説明するのではなく、実際に作業します。コードを読み、ファイルを編集し、コマンドを実行して、動作するパイプラインを作成してください。

---

開始する前に

まず、仮想環境を有効化してください。プロジェクトに適した仮想環境を特定して有効化します。仮想環境を有効化した後、スキルのリソースに含まれる setup.sh を実行してください。 このスクリプトは eval-driven-dev スキルと pixie-qa Python パッケージを最新バージョンに更新し、まだ初期化されていない場合は pixie の作業ディレクトリを初期化して、ユーザーに更新内容を表示するウェブサーバーをバックグラウンドで起動します。

セットアップエラーへの対応 — スキップできる場合と、必ず成功させる必要がある場合：

• スキルの更新に失敗した場合 → 続行して問題ありません。既存のスキルバージョンで十分です。
• pixie-qa のアップグレードに失敗したが、すでにインストールされている場合 → 既存のバージョンで続行して問題ありません。
• pixie-qa がインストールされておらず、インストールに失敗した場合 → 停止してください。 ユーザーに支援を求めてください。pixie パッケージなしではワークフローを続行できません。
• pixie init に失敗した場合 → 停止してください。 ユーザーに支援を求めてください。
• pixie start（ウェブサーバー）に失敗した場合 → 停止してください。 ユーザーに支援を求めてください。診断のため、pixie のルートディレクトリにある server.log を確認してください。よくある原因は、ポートの競合、依存関係の不足、環境の動作が遅いことです。ウェブサーバーなしで続行しないでください。ユーザーが評価結果を確認するために必要です。

---

ワークフロー

ステップ 1～6 を中断せず、順番に実行します。途中のステップでユーザーに確認を求めず、各ステップを自分で検証してから続行してください。

作業方法 — 何よりも先に、以下をお読みください。

• 一度に 1 つのステップだけを進めます。 現在のステップの指示だけを読みます。ステップ 1 の作業中に、ステップ 2～6 を読んではいけません。
• ステップで指示された場合にのみ、参照ファイルを読みます。 各ステップでは特定の参照ファイルを指定しています。そのステップに進んだときに読み、事前には読まないでください。
• 成果物はすぐに作成します。 サブステップのコードを読んだら、次に進む前に、そのサブステップの出力ファイルを書き出してください。複数のサブステップの内容を把握してから、まとめて書き出すのは避けてください。
• 検証してから次に進みます。 各ステップにはチェックポイントがあります。検証してから次のステップに進んでください。現在のステップを検証している間に、今後のステップを計画しないでください。

作業を止めて助けを求める場合：

回避策を講じるべきではなく、講じることもできない問題があります。以下のいずれかに遭遇した場合は、直ちに作業を停止してユーザーに助けを求めてください。回避策を試みてはいけません。

• 環境変数や設定が不足していて、アプリを実行できない場合：アプリの実行に必要な環境変数や設定が未設定で、推測もできない場合です。モックや偽のコンポーネントを使ったり、アプリのコンポーネントを置き換えたりして回避してはいけません。評価では実際の本番コードを実行する必要があります。環境設定を修正するようユーザーに依頼してください。
• プロジェクトの破損を示すアプリのインポートエラー：システム依存関係の不足や互換性のない Python バージョンが原因で、アプリのコアモジュールをインポートできない場合です（インストール可能な pip パッケージの不足は該当しません）。プロジェクトの設定を修正するようユーザーに依頼してください。
• エントリーポイントが不明確な場合：同程度に有力なエントリーポイントが複数あり、プロジェクトの分析でも最も重要な対象が明確にならない場合です。どれを対象にするか、ユーザーに確認してください。

自分で解決すべき問題（問い合わせないでください）：不足している Python パッケージ（インストールする）、不足している pixie パッケージ（インストールする）、ポートの競合（別のポートを使う）、ファイル権限の問題（修正する）。

ステップ 1～6 を順番に実行します。 ユーザーのプロンプトから、前のステップがすでに完了していることが明らかな場合（例：「既存のテストを実行して」「評価を再実行して」）は、適切なステップから始めてください。判断に迷う場合は、ステップ 1 から始めてください。

---

ステップ 1：アプリを理解し、評価基準を定義する

まず、ユーザーのプロンプトに具体的な要件があるか確認してください。 アプリのコードを読む前に、ユーザーの依頼内容を確認します。

• 参照文書や仕様書：プロンプトに、従うべきファイル（例：「EVAL_SPEC.md の仕様に従う」「REQUIREMENTS.md の方法論を使う」）が記載されていますか？ 記載されている場合は、まずそのファイルを読んでください。データセット、評価項目、合格基準、方法論などが指定され、既定の内容より優先される場合があります。
• 指定されたデータセットやデータソース：プロンプトで特定のデータファイル（例：「eval_inputs/research_questions.json の質問を使う」「call_scenarios.json のシナリオを使う」）が指定されていますか？ 指定されている場合は、それらのファイルを読んでください。一般的な代替データを作成するのではなく、評価データセットの基礎として使用する必要があります。
• 指定された評価項目：プロンプトで、評価対象となる品質面（例：「事実性、網羅性、バイアスを評価する」「本人確認とツール呼び出しの正確性をテストする」）が指定されていますか？ 指定されている場合は、指定された各項目に対応する評価器をテストファイルに含めてください。

上記のいずれかがプロンプトで指定されている場合は、それらを優先します。先に内容を読み、反映してから進めてください。

ステップ 1 には 3 つのサブステップがあります。それぞれで専用の参照ファイルを読み、専用の出力ファイルを作成します。次のサブステップに進む前に、各サブステップを最後まで完了してください。

サブステップ 1a：プロジェクト分析

参照：今すぐ references/1-a-project-analysis.md を読んでください。

コード構造やエントリーポイントを確認する前に、このソフトウェアが現実の世界で何をするのか、その目的、利用者、実際の入力の複雑さ、そして失敗する箇所を理解してください。この理解が、その後のあらゆる判断の基盤になります。どのエントリーポイントを最も重視するか、どの評価基準を定義するか、どのトレース入力を使うか、どのデータセット項目を作成するかが決まります。次に進む前に、詳細なコンテキストファイルを作成してください。注：プロジェクトには tests/、fixtures/、examples/、モックサーバー、ドキュメントなどが含まれている場合がありますが、これらはプロジェクト独自の開発基盤であり、評価パイプラインのデータソースではありません。トレース入力やデータセットの内容を探す際は無視してください。

チェックポイント：pixie_qa/00-project-analysis.md を作成済み。ソフトウェアの機能、対象ユーザー、機能一覧（該当する機能がある場合は少なくとも3つ）、現実的な入力の特性、難しい問題／失敗モード（少なくとも2つ）を記載します。

サブステップ 1b：エントリーポイントと実行フロー

参照：今すぐ references/1-b-entry-point.md を読んでください。

ソースコードを読み、アプリの起動方法と、実際のユーザーによる呼び出し方法を理解してください。pixie_qa/00-project-analysis.md の機能一覧を使ってエントリーポイントの優先順位を決め、最初に見つかったものだけでなく、最も価値の高い機能を実行するエントリーポイントに注目してください。次に進む前に、詳細なコンテキストファイルを作成してください。

チェックポイント：pixie_qa/01-entry-point.md を作成済み。エントリーポイント、実行フロー、ユーザー向けインターフェース、環境要件を記載します。

サブステップ 1c：評価基準

参照：今すぐ references/1-c-eval-criteria.md を読んでください。

アプリのユースケースと評価基準を定義してください。ユースケースは pixie_qa/00-project-analysis.md の機能一覧から導き出します。評価基準は一般的な品質の観点ではなく、難しい問題／失敗モードから導き出してください。ユースケースはデータセットの作成（ステップ 4）を、評価基準は評価器の選定（ステップ 3）を導きます。次に進む前に、詳細なコンテキストファイルを作成してください。

チェックポイント：pixie_qa/02-eval-criteria.md を作成済み。ユースケース、評価基準、およびそれらの適用範囲を記載します。まだステップ 2 の手順は読まないでください。

---

ステップ 2：アプリを計装して実行し、参照トレースを取得する

ステップ 2 には3つのサブステップがあります。それぞれで個別の参照ファイルを読みます。次のサブステップを始める前に、各サブステップを完了してください。

サブステップ 2a：wrap による計装

参照：今すぐ references/2a-instrumentation.md を読んでください。

アプリのデータ境界に wrap() 呼び出しを追加し、評価ハーネスが制御された入力を注入して出力を取得できるようにします。これにより、ロジックを変更せずにアプリをテストできます。

チェックポイント：すべてのデータ境界に wrap() 呼び出しを追加済み。pixie_qa/02-eval-criteria.md の各評価基準に対応するデータポイントがあります。

サブステップ 2b：Runnable を実装する

参照：今すぐ references/2b-implement-runnable.md を読んでください。

評価ハーネスから、実際のユーザーとまったく同じ方法でアプリを呼び出せる Runnable クラスを作成してください。Runnable はシンプルにします。アプリの実際のエントリーポイントをハーネスのインターフェースに接続するだけです。複雑になっている場合は、何かが間違っています。

チェックポイント：pixie_qa/run_app.py を作成済み。Runnable は実際の LLM 設定を使ってアプリの実際のエントリーポイントを呼び出します。モック化、偽装、コンポーネントの置き換えは行いません。

サブステップ 2c：参照トレースを取得して検証する

参照：今すぐ references/2c-capture-and-verify-trace.md を読んでください。

Runnable を通してアプリを実行し、トレースを取得してください。このトレースによって、計装と Runnable が正しく機能していることを確認でき、ステップ 4 でデータセットを作成する際に必要なデータ形式も得られます。

チェックポイント：pixie_qa/reference-trace.jsonl が存在します。想定されるすべての wrap エントリーと llm_span エントリーが含まれています。pixie format に評価に必要なすべてのデータポイントが表示されます。まだステップ 3 の手順は読まないでください。

---

ステップ 3：評価器を定義する

参照：詳細なサブステップについては、今すぐ references/3-define-evaluators.md を読んでください。

目標：ステップ 1c の定性的な評価基準を、具体的で実行可能なスコアリング関数に変換します。各基準は、組み込み評価器、エージェント評価器（意味的または定性的な基準ではデフォルト）、または手動のカスタム関数（正規表現やフィールドの存在確認など、機械的または決定論的なチェックに限ります）のいずれかに対応します。評価器マッピングの成果物は、すべての品質次元に採点者が割り当てられるよう、基準とデータセットをつなぎます。一般的な品質次元だけでなく、pixie_qa/00-project-analysis.md で特定した難しい問題を測定する評価器を選択してください。

チェックポイント：すべての評価器を実装済みです。pixie_qa/03-evaluator-mapping.md に、基準と評価器のマッピングおよび選定理由を記述しました。ステップ 4 の指示はまだ読まないでください。

---

ステップ 4：データセットを構築する

参照：詳細なサブステップについては、今すぐ references/4-build-dataset.md を読んでください。

目標：すべてを結び付けるテストシナリオを作成します。つまり、実行可能なもの（ステップ 2）、評価器（ステップ 3）、ユースケース（ステップ 1c）を結び付けます。各データセットエントリでは、アプリに送る内容、外部サービスからアプリが取得するデータ、結果の採点方法を定義します。データの形状とフィールド名は、ステップ 2 の参照トレースを信頼できる情報源として使用してください。pixie_qa/00-project-analysis.md の機能インベントリにあるエントリを網羅し、そこで特定した障害モードを対象とするエントリも含めてください。データセットの eval_input の内容に、プロジェクト独自のテストフィクスチャ、モックサーバー、サンプルデータを使用しないでください。代わりに、実世界のデータを用意してください。アプリ内のすべての wrap(purpose="input") について、各エントリの eval_input に事前取得済みの内容を含めてください。アプリに入力ラップがある場合、eval_input を空のままにしないでください。

チェックポイント：多様なエントリであらゆるユースケースを網羅したデータセット JSON を pixie_qa/datasets/<name>.json に作成しました。データセットの実用性監査に合格済みです。エントリには代表的な規模の実世界データを使用し、プロジェクトのテストフィクスチャは混入していません。結果が不確実な障害モードを対象とするエントリを少なくとも 1 つ含み、すべての eval_input に全入力ラップの取得済みコンテンツが含まれています。ステップ 5 の指示はまだ読まないでください。

---

ステップ 5：pixie test を実行して機械的な問題を修正する

参照：詳細なサブステップについては、今すぐ references/5-run-tests.md を読んでください。

目標：パイプライン全体をエンドツーエンドで実行し、機械的なエラーなしで動作させます。このステップでは、pixie QA コンポーネント（データセット、実行可能なもの、カスタム評価器）のセットアップとデータの問題だけを修正します。アプリケーション自体の修正や結果の品質評価は行いません。pixie test がエラーなく完了し、すべてのエントリに対して実際の評価器スコアが出力されたら、このステップは完了です。

チェックポイント：pixie test が最後まで実行されます。すべてのデータセットエントリに評価器スコア（実際の EvaluationResult または PendingEvaluation）があります。セットアップエラー、インポート失敗、データ検証エラーはありません。

テストでエラーが発生した場合、それは QA コンポーネントの機械的な不具合なので、修正して再実行してください。ただし、テストでスコアが生成されたら次に進んでください。ここでは結果の品質を評価しないでください。それはステップ 6 で行います。

テストでスコアが生成されたら、必ずステップ 6 に進んでください。 分析は不可欠な最後のステップです。分析しなければ保留中の評価が完了せず、ユーザーには解釈されていない生のスコアしか提示されず、実行可能な洞察も得られません。ここで止めて、続行するかどうかをユーザーに尋ねないでください。

反復実行のサイクルルール：pixie test を実行して成功するたびに、具体的な pixie_qa/results/<test_id> ディレクトリが作成され、新しい分析サイクルが始まります。アプリケーションコード、プロンプト、データセット、評価器を編集する前、または pixie test を再実行する前に、その特定の結果ディレクトリについてステップ 6 を完了してください。前のサイクルを飛ばして最後の実行だけを分析してはいけません。

ステップ 6：結果を分析する

参照：references/6-analyze-outcomes.md を今すぐお読みください。完全な3段階の分析プロセス、執筆ガイドライン、出力形式の要件が記載されています。

目標：構造化されたデータ主導のプロセスで pixie test の結果を分析し、テストケースの品質、評価者の品質、アプリケーションの品質について、実行可能な洞察を導き出します。このステップでは、保留中の評価を完了し、エントリーごとおよびデータセットごとの分析を作成して、優先順位付きのアクションプランを作成します。すべての記述は評価実行の具体的なデータに基づく必要があります。推測や曖昧な説明は避けてください。

永続化する分析成果物：この簡略化されたワークフローでは、分析はデータセットレベルとテスト実行レベルでのみ永続化します。これらの成果物には、詳細版（エージェント向け：データポイント、証拠の経緯、推論の連鎖）と要約版（人間によるレビュー向け：2分以内で読める簡潔なTLDR）の両方を用意します。エントリーごとの分析ファイルは作成しないでください。

完了の必須条件：以下の条件をすべて満たすまで、ステップ 6 は完了していません。

• pixie_qa/results/<test_id>/dataset-*/entry-*/evaluations.jsonl にある "status": "pending" のすべてのエントリーが、score と reasoning を含む採点済みの結果に置き換えられている。
• すべてのデータセットディレクトリに analysis.md と analysis-summary.md がある。
• テスト実行ルートに action-plan.md と action-plan-summary.md がある。
• このスキルの resources/ ディレクトリにあるステップ 6 の検証スクリプトを pixie_qa/results/<test_id> に対して実行し、成功が報告されている。

以下の対応だけでは不十分です：

• pixie_qa/06-analysis.md のようなトップレベルのファイルを1つだけ作成する
• 保留中の評価はユーザーがウェブ UI で確認すると伝える
• evaluations.jsonl を更新せずに、あるエントリーが「おそらく合格する」と述べる

---

ウェブサーバーの管理

pixie-qa は、コンテキスト、トレース、評価結果をユーザーに表示するためのウェブサーバーをバックグラウンドで実行します。セットアップスクリプトによって自動的に起動します（pixie start を実行すると、デタッチされたバックグラウンドプロセスが起動し、すぐに制御が戻ります）。

ユーザーが eval-driven-dev ワークフローを終えたら、ウェブサーバーは引き続き実行中であり、次の操作で停止できることを伝えてください。

pixie stop

重要：ウェブサーバーを停止すると、ウェブ UI にアクセスできなくなります。そのため、ユーザーがすべてのウェブ UI 機能を使い終えたことを確認した場合にのみ、サーバーを停止してください。引き続きウェブ UI を使う場合は、サーバーを停止しないでください。

また、ワークフローを再開する際は、ウェブサーバーが確実に実行されるよう、必ず resources 内の setup.sh スクリプトを再度実行してください：