llm-judge

LLM Judge

複数のリポジトリにまたがってコード実装を比較し、構造化された評価を行います。

使用方法

llm-judge <spec> <repo1> <repo2> [repo3...] [--labels=...] [--weights=...] [--branch=...]

引数

引数	必須	説明
spec	はい	仕様／要件ドキュメントへのパス
repos	はい	比較するリポジトリへの 2 つ以上のパス
--labels	いいえ	カンマ区切りのラベル（デフォルト：ディレクトリ名）
--weights	いいえ	重みを上書きします。例：functionality:40,security:30
--branch	いいえ	main と比較するブランチ（デフォルト：main）

ワークフロー

1. $ARGUMENTS を spec_path、repo_paths、labels、weights、branch に解析します。
2. 仕様ファイル、各リポジトリのパス、およびリポジトリの最小数を検証します。
3. 仕様ドキュメントをメモリに読み込みます。
4. このスキルと補助参照ファイルを読み込みます。
5. リポジトリごとに事実を収集します（リポジトリごとに Phase 1 のユニットを 1 つ）—事実のみで、採点は行いません。
6. 続行する前に、リポジトリエージェントの JSON 結果を検証します。
7. 各評価項目を採点します（評価項目ごとに Phase 2 のユニットを 1 つ）。
8. スコアを集計し、加重合計を計算して、リポジトリを順位付けし、レポートを作成します。
9. Markdown の概要を表示し、JSON レポートを検証します。

必須ゲート

順序どおりに進めるワークフローです。現在のゲートを通過するまで、次のフェーズを開始しないでください。 各通過条件は確認可能なものでなければなりません（ディスク上のファイル、空でない内容、または json.load の成功）。「内部で確認した」だけでは不十分です。

ゲート	通過条件	次に進める対象
A — 入力	spec_path が読み取り可能で空でないファイルであること、len(repo_paths) ≥ 2 であること、各パスに .git が含まれていること。	Phase 1 のリポジトリエージェント
B — Phase 1 の事実	各リポジトリエージェントの出力について、stdin/stdout が JSON として解析でき、必須キーと構造が references/fact-schema.md に一致すること。	Phase 2 の評価エージェント
C — Phase 2 のスコア	5 つの評価出力（評価項目ごとに 1 つ）がそれぞれ JSON として解析でき、すべてのリポジトリラベルについてスコア（および根拠）を含むこと。	集計
D — レポートファイル	.beagle/llm-judge-report.json が存在し、python3 -c "import json; json.load(open('.beagle/llm-judge-report.json'))" の終了コードが 0 であること。	ユーザー向け Markdown の概要
E — 整合性	概要表と判定で、JSON レポートと同じラベル、重み、評価項目ごとのスコアが使用されていること。	タスク完了

フェーズ内では並列処理が可能です（Phase 1 のすべてのタスクをまとめて実行し、Phase 2 のすべてのタスクをまとめて実行できます）。ただし、ゲート B を通過するまで Phase 2 を開始してはならず、ゲート D を通過する前にユーザー向けの概要を表示してはなりません。

コマンドワークフロー

ステップ 1：引数を解析する

$ARGUMENTS を解析して、以下を抽出します。

• spec_path：最初の位置引数
• repo_paths：残りの位置引数（2 つ以上必要）
• labels：--labels から取得するか、ディレクトリ名から導出します
• weights：--weights から取得するか、デフォルトを使用します
• branch：--branch から取得するか、main を使用します

デフォルトの重み：

{
  "functionality": 30,
  "security": 25,
  "tests": 20,
  "overengineering": 15,
  "dead_code": 10
}

ステップ 2：入力を検証する

[ -f "$SPEC_PATH" ] || { echo "Error: Spec file not found: $SPEC_PATH"; exit 1; }

for repo in "${REPO_PATHS[@]}"; do
  [ -d "$repo/.git" ] || { echo "Error: Not a git repository: $repo"; exit 1; }
done

[ ${#REPO_PATHS[@]} -ge 2 ] || { echo "Error: Need at least 2 repositories to compare"; exit 1; }

ステップ 3：仕様ドキュメントを読み込む

SPEC_CONTENT=$(cat "$SPEC_PATH") || { echo "Error: Failed to read spec file: $SPEC_PATH"; exit 1; }
[ -z "$SPEC_CONTENT" ] && { echo "Error: Spec file is empty: $SPEC_PATH"; exit 1; }

ステップ 4：スキルを読み込む

この llm-judge スキルとその参照ファイルをコンテキストに読み込みます。

ステップ 5：Phase 1 — リポジトリごとに事実を収集する

エージェントがサブエージェントに対応している場合は、リポジトリごとに Phase 1 のリポジトリエージェントを 1 つ割り当てて並列実行します。対応していない場合は、同じ事実収集の手順をリポジトリごとに 1 つずつ順番に実行します。どちらの場合も出力は同一です。各ユニットには以下の概要を渡します。

You are a Phase 1 Repo Agent for the LLM Judge evaluation.

**Your Repo:** $LABEL at $REPO_PATH

**Spec Document:**
$SPEC_CONTENT

**Instructions:**
1. Load the **llm-judge** skill's references/repo-agent.md for detailed instructions
2. Follow references/fact-schema.md for the output format
3. Load the **llm-artifacts-detection** skill ([../../../beagle-core/skills/llm-artifacts-detection/SKILL.md](../../../beagle-core/skills/llm-artifacts-detection/SKILL.md), if available) for dead-code/overengineering analysis

Explore the repository and gather facts. Return ONLY valid JSON following the fact schema.

Do NOT score or judge. Only gather facts.

すべてのリポジトリの出力を ALL_FACTS に集めます。

ステップ 6：Phase 1 の結果を検証する

echo "$FACTS" | python3 -c "import json,sys; json.load(sys.stdin)" 2>/dev/null || { echo "Error: Invalid JSON from $LABEL"; exit 1; }

ステップ 7：Phase 2 — 評価項目ごとに採点する

エージェントがサブエージェントに対応している場合は、評価項目ごとに評価エージェントを 1 つ（合計 5 つ）割り当てて並列実行します。対応していない場合は、各評価項目を順番に採点します。出力は同一です。各ユニットには以下の概要を渡します。

You are the $DIMENSION Judge for the LLM Judge evaluation.

**Spec Document:**
$SPEC_CONTENT

**Facts from all repos:**
$ALL_FACTS_JSON

**Instructions:**
1. Load the **llm-judge** skill's references/judge-agents.md for detailed instructions
2. Follow references/scoring-rubrics.md for the $DIMENSION rubric

Score each repo on $DIMENSION. Return ONLY valid JSON with scores and justifications.

ステップ 8：スコアを集計する

for repo_label in labels:
    scores[repo_label] = {}
    for dimension in dimensions:
        scores[repo_label][dimension] = judge_outputs[dimension]['scores'][repo_label]

    weighted_total = sum(
        scores[repo_label][dim]['score'] * weights[dim] / 100
        for dim in dimensions
    )
    scores[repo_label]['weighted_total'] = round(weighted_total, 2)

ranking = sorted(labels, key=lambda l: scores[l]['weighted_total'], reverse=True)

ステップ 9：判定を作成する

勝者を挙げ、勝因を説明し、僅差の結果やトレードオフがあれば記載します。

ステップ 10：JSON レポートを書き込む

mkdir -p .beagle

.beagle/llm-judge-report.json に、バージョン、タイムスタンプ、リポジトリのメタデータ、重み、スコア、順位、判定を書き込みます。

ステップ 11：概要の表示

スコア表、ランキング、判定、詳細な根拠を含む Markdown の概要を表示します。

ステップ 12：検証

python3 -c "import json; json.load(open('.beagle/llm-judge-report.json'))" && echo "Valid report"

出力形式

生成するレポートには、以下を含めます。

• リポジトリのラベルとパス
• 各評価項目のスコアと根拠
• 加重合計とランキング
• 勝者を説明する判定

参照ファイル

ファイル	用途
references/fact-schema.md	フェーズ 1 の事実情報に関する JSON スキーマ
references/scoring-rubrics.md	各評価項目の詳細な評価基準
references/repo-agent.md	フェーズ 1 エージェント向けの手順
references/judge-agents.md	フェーズ 2 の判定エージェント向けの手順

スコアリングモデル

評価項目	デフォルトの重み	評価内容
機能性	30%	仕様への準拠、テストの合格率
セキュリティ	25%	脆弱性、セキュリティパターン
テスト品質	20%	カバレッジ、DRY、モックの境界
過剰な設計	15%	不要な複雑さ
デッドコード	10%	未使用コード、TODO

スコア基準

スコア	意味
5	優秀 - 期待を上回っています
4	良好 - 要件を満たしており、軽微な問題があります
3	平均的 - 機能しますが、目立った不足があります
2	平均以下 - 重大な問題があります
1	不良 - 基本的な要件を満たしていません

フェーズ 1：リポジトリごとの事実情報の収集

各リポジトリについて、サブエージェントがサポートされている場合は並列で、サポートされていない場合は逐次で、以下を用いて事実情報を収集する単位を実行します。

You are a Phase 1 Repo Agent for the LLM Judge evaluation.

**Your Repo:** $REPO_LABEL at $REPO_PATH
**Spec Document:**
$SPEC_CONTENT

**Instructions:** Follow the **llm-judge** skill's references/repo-agent.md

Gather facts and return a JSON object following the schema in references/fact-schema.md.

Load the **llm-artifacts-detection** skill ([../../../beagle-core/skills/llm-artifacts-detection/SKILL.md](../../../beagle-core/skills/llm-artifacts-detection/SKILL.md), if available) for dead code and overengineering analysis.

Return ONLY valid JSON, no markdown or explanations.

すべての repo-agent の出力を ALL_FACTS に収集します。

フェーズ 2：評価項目ごとのスコアリング

フェーズ 1 の事実情報をすべて収集した後、5 つの評価項目を、サブエージェントがサポートされている場合は並列で、サポートされていない場合は逐次で、評価項目ごとに 1 つの単位で採点します。

You are the $DIMENSION Judge for the LLM Judge evaluation.

**Spec Document:**
$SPEC_CONTENT

**Facts from all repos:**
$ALL_FACTS_JSON

**Instructions:** Follow the **llm-judge** skill's references/judge-agents.md

Score each repo on $DIMENSION using the rubric in references/scoring-rubrics.md.

Return ONLY valid JSON following the judge output schema.

集計

1. 5 つの判定結果を収集します。
2. 設定された重みを使って、各リポジトリの加重合計を計算します。
3. 加重合計の降順でリポジトリをランク付けします。
4. 結果と僅差のケースを説明する判定を作成します。
5. .beagle/llm-judge-report.json に書き込みます。

出力

スコア、ランキング、判定、詳細な根拠を含む Markdown の概要を表示します。

検証

完了前に（ハードゲート D および E に対応）：

1. ゲート D： .beagle/llm-judge-report.json が存在し、json.load が成功すること。
2. ゲート E / 完全性： すべてのリポジトリラベルに全評価項目のスコアがあること。各 weighted_total が、設定された重みを使った各評価項目の (score × weight / 100) の合計と一致すること。Markdown の概要が JSON レポートと一致すること。

ルール

• 先に進む前に、必ず入力を検証します
• フェーズ 2 の採点を始める前に、フェーズ 1 の事実情報の収集をすべて完了します（サブエージェントがサポートされている場合はフェーズ内で並列に、そうでない場合は逐次で実行します）
• フェーズ 2 では評価項目ごとに 1 つの単位を実行します
• すべてのスコアに根拠を示します
• 概要を表示する前に JSON レポートを書き込みます