PJR-23DT grade plan へ良い実例をリファレンスとして渡す
1. 概要
記載水準の判定には比較対象が要る。現在の plan は対象文書、対応する実践の型、抽象的な rubric、viewpoint の定義を含むが、良い文書の実例を含まない。
rubric は「各章が固有情報を持ち、削れる段落がない」といった抽象的な記述であり、level 4 と level 3 を分ける具体的な基準にならない。同系統で status が ready の文書をリファレンスとして渡せば、この水準が ready であるという基準が得られる。
生成より比較のほうが負荷が小さいため、ローカルモデルほど効果が見込める。
2. 完了条件
- plan に同系統の良い実例がリファレンスとして含まれる。
- リファレンスは評価対象ではなく比較材料であることが plan に明記されている。
- リファレンスが実行ごとに選び直され、特定文書への過適合が起きない。
- どの文書をリファレンスとしたかが記録される。
- plan のサイズが対象と参考資料の合計で一定の範囲に収まる。
- リファレンスなしの場合と比較して判定が変化することを確認する。
3. 作業内容
| No | 作業 | 担当 | 状態 | メモ |
|---|---|---|---|---|
| 1 | 選定基準の決定 | ARC | done | 同種別かつ status: ready |
| 2 | 選択方法の決定 | ARC | done | 1件を生成ごとに無作為選択 |
| 3 | サイズ上限の設計 | ARC | done | パス参照とし20,000文字未満を検証 |
| 4 | plan 生成の実装 | ARC | done | 選択・記録・読込指示を実装 |
| 5 | 効果の確認 | ARC | done | 比較材料の有無による入力差を検証 |
3.1. 現状の plan に欠けているもの
plan の構成は「対象項目」「参考資料」「前回の指摘」「Rubric」「Viewpoints」「完了手順」である。参考資料は対象に対応する rulebook / recipe / sample / template であり、規範を示すものであって良い実例ではない。
status の分布は rulebook で draft が 83 件、ready が 19 件である。比較対象は足りている。
3.2. リファレンスなしで観測された症状
サンプル評価では、ローカル構成（qwen を executor、gemma を reporter）の判定が高得点に偏った。
| 対象 | verdict | score | severity |
|---|---|---|---|
dec | pass | 96 | minor 1 |
ntp | pass | 98 | minor 1 |
mm | pass | 87 | minor 5 |
major と blocker が出ていない。同じ dec-rulebook.md に対して codex-expert-executor は 12 件、claude-expert-executor は 23 件の指摘を出しており、判定の差は大きい。
抽象的な基準だけでは、どの程度の不足を major とするかを判断できていない可能性がある。
3.3. ランダム選択の意義
リファレンスを固定すると、その文書に似ているかどうかだけを見るようになる恐れがある。実行ごとに選び直せば、異なる観点からの指摘が得られる。
前回 finding の引き継ぎと組み合わせると、繰り返すほど網羅性が上がる。同一 agent を2回実行しても新しい指摘が出なかった実測があるが、リファレンスが変われば同じ agent でも別の観点が生まれうる。
3.4. リファレンスの品質
status: ready は文書の成熟度を示すが品質を保証しない。当面は ready を代用し、grade の運用が進んだ後は verdict が pass かつ高性能 agent で確認済みの文書へ切り替えることが望ましい。
誤った基準の伝播に注意する。リファレンス自体に問題があれば、それが水準として扱われる。
3.5. 決定事項
- リファレンスは1件とし、Kata は同じ rulebook / recipe / sample / template 種別、成果物は同じ
specdojo.typeに限定する。 - 候補は対象以外の
status: ready文書とし、plan の生成ごとに候補集合から無作為に選び直す。候補がなければ「該当候補なし」と記録する。 - 対象・参考資料と同じくパス参照とし、本文を plan に埋め込まない。これにより大きい文書を選んでも plan 自体は20,000文字未満に保つ。
- 選択したパスは executor plan に記録する。grade 結果への永続化は行わず、保存された plan と実行ログをその実行の証跡とする。
readyは品質保証ではないため、比較リファレンスを評価対象にせず、内容の機械的な模倣や欠点の転用を禁止する。rubric と viewpoint を最終的な判定基準とする。
4. 対応結果
grade planが同種別かつstatus: readyの別文書を1件無作為に選び、「良い実例（比較リファレンス）」としてパスを記録するようにした。- executor に比較リファレンスの全文読込を求め、章ごとの具体性、根拠の密度、過不足を比較させる一方、評価対象への混入、機械的な模倣、実例自体の欠点の転用を禁止した。
- 候補選定を注入可能な乱数で検証し、同じ候補集合でも生成ごとに異なる文書を選べること、draft や別種別や対象自身を除外することをテストした。
- 本文を埋め込まずパスだけを持つため、比較リファレンスを含む plan が20,000文字未満であることをテストした。
- 実モデルによる判定品質の比較は agent の性能と実行環境に依存するため、保存済み plan を使う
exec trialで継続観測する。今回の自動検査では、リファレンスなし／ありで executor への判定入力と比較手順が変化することを確認した。 - 同種別に
status: readyの文書がない場合は、種別を跨がずリファレンスなしで評価する。種別が違うと構造も目的も異なり、記載水準の基準として誤りを招く。template はプレースホルダを正解と誤解させ、rulebook は recipe の基準にならない。--random-referenceを指定したにもかかわらず該当がない場合は警告を出し、基準なしで評価し続けることに気づけるようにした。 grade plan --reference <path>を追加し、選定を行わず特定の文書を比較材料に固定できるようにした。比較実験では選定の揺れを排除する必要があり、運用でも特定の実例へ水準を揃えたい場合がある。- plan の説明文から選定方法への言及を外し、固定指定と無作為選定のどちらでも正確な記述になるようにした。
- 比較リファレンスを既定で付けないようにした。効果が未実証であり、付けると executor の読み込み対象が増えるためである。利用する場合は
--reference <path>で固定するか--random-referenceで選定させる。両方の同時指定はエラーとする。 - リファレンスがない場合は plan から節ごと省略する。空の節を残すと、候補が存在しないのか指定していないのかを読み手が区別できない。
specdojo.grade.referenceへ判定に用いたリファレンスを文書 ID で記録する。パスで保存すると文書を移動したときに参照が壊れる。使わずに評価した場合はキーごと省略する。grade apply --reference <pathOrId>で渡し、パスを与えた場合は Frontmatter のidを読み取って変換する。- 記録がないと score の変化を切り分けられない。実測では同じ文書がリファレンスの有無で 19 ポイント動いており、対象を修正した効果なのか判定条件が変わっただけなのか判別できない。
- finding コメントの整形を修正した。message に含まれる山括弧を全角へ退避し、コメント挿入時に連続空行が生じないようにした。HTML コメント内ではインラインコードが機能せず、山括弧プレースホルダが lint に検知されるためである。
5. 関連ドキュメント
- prj-0001:pjr-4tz7-grade-per-document: plan の生成と参考資料の解決。リファレンスの追加先。
- prj-0001:pjr-x40m-grade-previous-findings: 前回 finding の引き継ぎ。ランダム選択と組み合わせて効果を高める。
- prj-0001:pjr-vqb5-agent-grade-comparison: agent ごとの判定の差と、ローカル構成の高得点への偏り。
- prj-0001:pjr-25f4-grade-two-stage-filter: 二段階フィルタ。リファレンスにより一段階目の精度が上がれば対象が絞れる。