build-review-interface

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

概要

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

データの表示

すべてのデータを、そのドメインで最も人が読みやすい形式で表示します。メールはメールらしく、コードにはシンタックスハイライトを適用します。Markdown はレンダリングし、テーブルはテーブルとして表示します。JSON は整形し、折りたためるようにします。

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

フィードバックの収集

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

• 主な操作として、合格／不合格の二択ボタンを設けます。
• 何が悪かったか（または良かったか）をレビュアーが説明できる自由記述のメモ欄を設けます。
• 判断に迷うケースのために、保留ボタンを設けます。
• 操作のたびに自動保存します。

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

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

• 次へ／前へボタンとキーボードの矢印キー。
• 位置と進捗を示すトレースカウンター（「残り 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 ファイル）からトレースを受け入れられるようにアプリを構築します。サンプリングのロジックはアプリの外部にある別のスクリプトに分離します。まずはランダムサンプリングから始めます。

追加機能

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

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

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

デザインチェックリスト

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

テスト

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

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

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

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

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