build-review-interface

カスタムアノテーションインターフェースを構築する

概要

データソース（JSON/CSV ファイル）からトレースを読み込み、一度に 1 つのトレースを表示する HTML ページを構築します。Pass/Fail ボタン、自由記述のメモ欄、次へ／前へ移動するナビゲーションを用意します。ラベルをローカルファイル（CSV/SQLite/JSON）に保存します。その後、以下のガイドラインに沿って、対象分野に合わせてカスタマイズします。

データ表示

データはすべて、対象分野において最も人が読みやすい形式で表示します。メールはメールらしく表示します。コードには構文ハイライトを適用します。Markdown はレンダリングします。テーブルはテーブルとして表示します。JSON は整形して表示し、折りたたみ可能にします。

• 繰り返しの要素を折りたたむ。 すべてのトレースに同じシステムプロンプトが含まれる場合は、<details> のトグルに入れます。
• 重要なメタデータを抽出して目立たせる。 トレース内のデータに埋もれているプロパティ名、クライアントの種類、セッション ID などを抽出し、ヘッダーやバッジとして目立つように表示します。
• 役割やステータスごとに色分けする。 左ボーダーの色を使い、ユーザーメッセージ、アシスタントメッセージ、ツール呼び出し、システムプロンプトを一目で区別できるようにします。
• 関連する要素を視覚的にグループ化する。 ツール呼び出しとその応答を、インデントや共通のボーダーを使って視覚的に結び付けます。
• 判断に役立たない情報を折りたたむ。 冗長なツール応答の JSON、中間推論ステップ、デバッグコンテキストはトグルの中に入れます。
• 最も重要な情報を強調する。 レビュアーが判断する主要なコンテンツを、視覚的に目立たせます。価格、日付、名前などの重要な要素を太字にします。フォントサイズや余白で階層を作ります。
• トレース全体を表示する。 最終出力だけでなく、中間ステップ（ツール呼び出し、取得したコンテキスト、推論）もすべて含めます。デフォルトでは折りたたみますが、必要に応じて確認できるようにします。
• レンダリングするコンテンツをサニタイズする。 LLM 出力をレンダリングする前に、生の HTML を除去します。トラッキングピクセルの可能性がある場合は、レンダリングされた Markdown 内の画像を無効にします。

フィードバックの収集

アノテーションはトレース単位で行います。レビュアーは個々のスパンではなく、トレース全体を評価します。

• 主な操作として、二択の Pass/Fail ボタンを用意します。
• レビュアーが問題点（または良かった点）を記述できる自由記述のメモ欄を用意します。
• 判断に迷うケースに備えて、保留ボタンを用意します。
• 操作のたびに自動保存します。

エラー分析によって失敗カテゴリが明らかになったら、後から、クリック可能なチェックボックス、ドロップダウン、または選択リストとして、あらかじめ定義した失敗モードのタグを追加できます。レビュアーはメモの記入に加えて、既知のカテゴリを選択できるようになります。ただし、初期構築時には追加しないでください。

ナビゲーションとステータス

• 次へ／前へボタンと、キーボードの矢印キー。
• 位置と進捗を示すトレースカウンター（「残り 87 件中 12 件」）。
• ID を指定して特定のトレースに移動。
• ラベル付け済み／未ラベルのトレース数。

キーボードショートカット

Arrow keys = Navigate traces
1 = Pass              2 = Fail
D = Defer             U = Undo last action
Cmd+S = Save          Cmd+Enter = Save and next

読み込むトレースの選択

どのソース（JSON/CSV ファイル）からでもトレースを受け取れるようにアプリを構築します。サンプリングのロジックはアプリの外部にある別のスクリプトに分けます。まずはランダムサンプリングから始めます。

追加機能

参照パネル： トレースと並べて、正解データ、期待される回答、ルーブリックの定義などを表示する切り替え可能なパネルです。

フィルタリング： 製品に関連するメタデータの項目（チャネル、ユーザーの種類、パイプラインのバージョン）でトレースを絞り込みます。

クラスタリング： メタデータや意味的な類似性に基づいてトレースをグループ化します。各クラスタの代表的なトレースを表示し、詳細を確認できるようにします。

デザインチェックリスト

• すべてのトレースでレイアウト、操作項目、用語が統一されている
• Pass ボタンと Fail ボタンが視覚的に区別できる（色、サイズ）
• すべての主要操作でキーボードショートカットが機能する
• セクションが折りたたまれていても、トレース全体を確認できる
• 明示的に保存しなくても、ラベルが自動的に保持される
• デフォルトのアノテーション単位がトレースである（スパン単位ではない）
• すべてのデータが本来の形式でレンダリングされる（Markdown は HTML として、コードはハイライト付きで、JSON は整形して、テーブルは HTML テーブルとして、URL はクリック可能なリンクとして）

テスト

インターフェースを構築したら、Playwright で動作を確認します。

ビジュアルレビュー： 代表的なトレースデータを読み込んだ状態で、インターフェースのスクリーンショットを撮影します。各スクリーンショットを確認し、次の点をチェックします。

• レイアウトと余白：視覚的な階層は明確ですか？重要な情報がすぐにわかりますか？
• 読みやすさ：すべてのデータが本来の形式で表示されていますか？生の JSON の塊、未レンダリングの Markdown、スタイルが適用されていないコンテンツはありませんか？
• 美しさ：インターフェースはプロフェッショナルで、すっきりしていますか？この分野の専門家が使いたいと思えるものですか？
• レスポンシブ対応：ウィンドウサイズを変えてもレイアウトは崩れませんか？

機能テスト： 注釈付けのワークフロー全体を実行する Playwright スクリプトを作成します。

1. アプリを読み込み、トレースが表示されていることを確認します
2. トレースの「合格」をクリックし、ラベルが保存されたことを確認します
3. トレースの「不合格」をクリックしてメモを追加し、両方が保存されたことを確認します
4. 「保留」をクリックし、記録されたことを確認します
5. ボタンとキーボードショートカットで前後に移動します
6. トレースのカウンターが正しく更新されることを確認します
7. ページを再読み込みし、ラベルが保持されていることを確認して自動保存を検証します
8. 折りたたまれたセクション（システムプロンプト、ツール呼び出し）を展開し、コンテンツにアクセスできることを確認します
9. すべてのキーボードショートカットで正しい操作が実行されることをテストします