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

あなたは、Python ベースの AI アプリケーションをエンドツーエンドでテストする自動評価パイプラインを構築しています。実際のユーザーと同じ方法で、本物のインプットで実行してから、評価器を使用してアウトプットをスコアリングし、pixie test 経由で合格/不合格の結果を生成します。

テスト対象はアプリケーション自体です — リクエスト処理、コンテキスト組立て(データ収集方法、プロンプト構築、会話状態管理)、ルーティング、レスポンス形式化です。アプリケーションは LLM を使用するため、出力は非決定的です。そのため assertEqual ではなく評価器(LLM-as-judge、類似度スコア)を使用します。ただし、テスト対象はアプリケーションのコードであり、LLM ではありません。

評価中、アプリケーション自身のコードは実際に実行されます — ルーティング、プロンプト組立て、LLM 呼び出し、レスポンス形式化 — モック化やスタブ化は一切ありません。しかし、アプリケーションが外部ソース(データベース、キャッシュ、サードパーティ API、音声ストリーム)から読み込むデータは、計測を通じてテスト指定値で置き換えられます。つまり、各テストケースはアプリケーションが見るデータを正確に制御しながら、完全なアプリケーションコードパスを実行します。

ルール: アプリケーションの LLM 呼び出しは実際の LLM に対して行う必要があります。 LLM を偽装実装で置き換え、モック化、スタブ化、インターセプトしないでください。LLM はコア価値生成コンポーネントです。置き換えると評価は同語反復的になります(インプットとアウトプットの両方を制御するため、スコアは無意味になります)。プロジェクトのテストスイートに LLM モックパターンが含まれている場合、それはプロジェクト独自のユニットテスト用です — 評価 Runnable で採用しないでください。

成果物は実際のスコアを含む動作する pixie test 実行です — 計画ではなく、単なる計測ではなく、単なるデータセットではありません。

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

---

開始前に

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

セットアップエラーハンドリング — スキップ可能なもの vs. 必ず成功すべきもの:

• スキル更新が失敗 → 続行して OK。既存のスキルバージョンで十分です。
• pixie-qa アップグレードが失敗したが既にインストール済み → 既存バージョンで続行して OK。
• pixie-qa が未インストールで、インストール失敗 → 停止してください。 ユーザーに支援を求めてください。ワークフローは pixie パッケージなしでは進行できません。
• pixie init が失敗 → 停止してください。 ユーザーに支援を求めてください。
• pixie start (Web サーバー) が失敗 → 停止してください。 ユーザーに支援を求めてください。pixie ルートディレクトリの server.log で診断を確認してください。一般的な原因: ポート競合、依存関係の欠落、環境が遅い。Web サーバーなしでは進行しないでください — ユーザーが評価結果を見るためにそれが必要です。

---

ワークフロー

ステップ 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 を読んでください。

目標: すべてをまとめるテストシナリオを作成します — runnable(ステップ 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 コンポーネント(データセット、runnable、カスタム評価器)のセットアップとデータ問題の修正に厳密に関するものです — アプリケーション自体の修正または結果品質の評価についてではありません。pixie test が機械的なエラーなく完了し、すべてのエントリに対して実際の評価器スコアを生成したら、このステップは完了です。

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

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

ステップ 6 に必ず進んでください。分析は必須の最終ステップです — それなしでは、保留中の評価が完了されず、ユーザーは解釈されていない生のスコアと実行可能なインサイトなしで得ます。ここで停止して、ユーザーに続行するかどうか尋ねないでください。

反復実行のサイクルルール: 成功した pixie test 呼び出しはそのつど具体的な pixie_qa/results/<test_id> ディレクトリを作成し、新しい分析サイクルを開始します。アプリケーションコード、プロンプト、データセット、評価器を編集する前に、または pixie test を再実行する前に、その正確なリザルトディレクトリに対してステップ 6 を完了してください。以前のサイクルをスキップして最後の実行だけを分析しないでください。

---

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

リファレンス: 完全な 3 段階分析プロセス、書き方ガイドライン、出力形式要件については今すぐ references/6-analyze-outcomes.md を読んでください。

目標: テストケース品質、評価器品質、アプリケーション品質に対する実行可能なインサイトを生成するための構造化されたデータ駆動プロセスで 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 を持っています。
• このスキルのリソース/ ディレクトリから pixie_qa/results/<test_id> に対してステップ 6 検証器スクリプトを実行済みで、成功を報告しています。

明確に不十分なもの:

• pixie_qa/06-analysis.md などの単一トップレベルファイルの作成
• 保留中の評価はユーザーが Web UI で確認する対象だと述べる
• エントリが evaluations.jsonl を更新せずに「おそらく合格」だと述べる

---

Web サーバー管理

pixie-qa はバックグラウンドで Web サーバーを実行して、コンテキスト、トレース、評価結果をユーザーに表示します。セットアップスクリプトによって自動的に起動されます(pixie start を通じて、デタッチされたバックグラウンドプロセスを起動し、すぐに戻ります)。

ユーザーが評価駆動開発ワークフローを完了したら、Web サーバーはまだ実行中であることを通知し、以下を使用してクリーンアップできることを伝えてください:

pixie stop

重要: Web サーバーが停止した後、Web UI はアクセスできなくなります。ユーザーが Web UI 機能の使用を続けたい場合にのみサーバーを停止してください。サーバーの停止を確認したユーザーの場合のみ。

そしてワークフローを再開するたびに、Web サーバーが実行されていることを確認するために、常にリソース内の setup.sh スクリプトを再実行してください: