fullseye

PoC・図・動画・展示の判断基準(依頼する人と作る人の両方へ)

Fullseye の PoC(examples/poc_*.py)や展示の図・動画は、走って PASS が出ることと読んだ人に主張が伝わることの両方で合格が決まる。この文書は後者を検査可能な形にした雛形で、人が自分で書くときにも、コーディングエージェント(Codex / Claude / Copilot 等)に依頼するときにも、そのまま使う。

言語版: 日本語(この文書)/ English。

先手と後手

CI の門(型検査・帳簿の一致・再生成の drift)は後手の対策で、作った後に落とす。この文書は先手の対策で、作る前に決める。作る前に次の 5 つが決まっていれば、門に落ちる前に安い成果物が出る余地が消える。

主張を 1 行で(「窓を 4 秒に切ると浅い欠陥の深さ誤差が十数 % に縮む」)。主張が無い成果物は作らない。
真値をどこから取るか(閉形式・公表値・第二実装・実測)。真値が無いなら、それは PoC ではなく絵。
壊れる側を何で見せるか(雑音・窓・角度・間引き)。成功だけでは主張が運ばれない。
画面に何を並べるか(op の入力 → 出力 → 真値、数字の札、限界の線)を px 座標で。
誰がどこまで作るか(下の「分担の目安」)。判断で決まる部分は依頼する側が書く。

なぜ必要か

コーディングエージェントは「依頼文に書かれた門を最小の手数で通す」実装者である。書かれていない品質は上がらない。「良い感じに」「分かりやすく」「実物らしく」は門にならない。枚数・言語・関数名・座標・下限・数値の出どころで書くと、同じエージェントが別物を返す。実例: 同じ題材で、門を書かなかった依頼は「箱の車が格子の道路を走る 5 分」を返し、形の点列と貫通ゼロと評価項目を書いた依頼は教習所の 8 課題を映す動画を返した。

雛形 A —— 依頼文の末尾に貼る「質の門」

全行が「実測」か「assert」で答えられる形にする。埋められない行があれば、仕様がまだ決まっていない。

観点	門(例。題材に合わせて書き換える)	判定の仕方
何を見せるか	題材の対象が画面にある(車なら車、欠陥なら欠陥)。op の入力 → 出力 → 真値が同じ画面にある	最初・中間・最後のコマを名指しで検分
壊れる側	限界・失敗条件(雑音を上げる、窓を変える、角度を振る)も映す。成功だけの図は主張を運ばない	失敗条件のコマが 1 枚以上
形	実物の寸法表または座標の点列どおり。箱・球・棒の代用は不合格	仕様の点列を重ねた三面図、最大ずれ [m]
物理	貫通ゼロ、接地、時間順序、保存則(題材に該当するもの)	全コマの数値の門(`gates.json`)
数字	画面・caption の数字は同じ実行の値。帳簿(`figures.json`、`exhibits.json`)に同じ量があれば一致	`assert`。差があれば止める
尺度	疑似カラーは `vmin`/`vmax` 固定。コマごとの正規化は禁止(主張が壊れる)	実装の説明と 2 コマの比較
解像度	幅×高さ・fps・コマ数を数で。データ面の最近傍拡大なし(整数倍の「拡大 N×」と明記した差し込みだけ可)	実測
文字	言語(ja / en)、最小 px(1080p で 22 px)、はみ出し 0、データの上に置かない(帯か余白へ)	描画前に文字幅を測る
体裁	図は `examplefig` の関数で(既定 matplotlib の素の体裁は不合格)	関数名を報告
決定性	2 回描いて SHA-256 一致	実測
標本	点数・枚数・課題数の下限(間引いて「負け」を出さない)	実測
再生成	生成物は `py -3.11 tools/regen_all.py` で全部作り直し、`--check` が緑	実測
検分用出力	repo の外に最初 / 中間 / 最後 / 接触印画のコマ	所在を報告
時間の門	秒数は実測の分布から決める(手元の最長 × 共有ランナーの余裕 2〜3 倍)。複数の時間の門(テストの timeout、ハング検出のダンプ、PoC 1 本の上限)は長い順に並ぶこと。「遅いだけ」と「止まった」を同じ門で裁かない	各門の値と根拠を表に

時間の門は値の決め方で意味が変わる。短すぎれば混雑した日に正しい物が落ち、長すぎればハングを拾えない。既存の例: PoC 1 本の上限 → PoC 一括実行の timeout(5400 秒)→ ハング検出のダンプ(6000 秒)の順に長くしてある。値を変えるときは隣の門も見る。

雛形 B —— 受け取り検分(依頼した側がやる)

報告の数字を読む前に、コマを原寸で開く。縮小一覧は欠陥を隠す(箱の車を見逃した前例がある)。
題材の対象が「それに見える」かを 1 秒で判断できるか。
門の表の各行に実測値が入っているか。「通過」だけの行は受け取らない。
before / after の向きが正しいか(遅い方・悪い方が「採用」になっていないか)。
10 秒の試作なら、全編に進む前に発注者へ見せる。
追加されたファイルの一覧を見る(画面と数値だけ見て、巻き込まれた生成物を見落とさない)。

雛形 C —— 依頼文の骨組み

# 依頼: <題材> —— <1 行の主張>
場所: <worktree>。書くのはここだけ。読むだけ: <参照先>。
## 構成(<秒数・解像度・fps・コマ数>)
<時刻ごとに何を映すか。カメラ、画面の割り付けを px 座標で>
## Fullseye の仕事(画面に映す)
<op 名 → 入力 → 出力 → 真値、どこに重ねるか>
## 変えないこと
<既存の図・caption・数値・門>
## 門(README に表で)
<雛形 A を題材に合わせて埋めたもの>
## 出力(検分用)
<ファイル名、コマの所在>
## 報告(日本語)
<門ごとに「どのコマで確かめたか」、数値の表、描画時間>

雛形 D —— 作る側の手順(エージェントが着手から報告まで辿る順)

依頼文を読み、雛形 A の各行を自分の題材の値で埋めた表を先に README に書く(埋まらない行は報告で「未定」と書き、推測で埋めない)。
既存の図・caption・数値・帳簿は触らない。足すだけ。
10 秒(または 1 枚)の試作を先に作り、最初・中間・最後のコマを repo の外へ書く。
全編を作り、門の表の各行に実測値を入れる。assert で止まったら直すか、止まった事実を報告する(門を緩めない)。
py -3.11 tools/regen_all.py → --check → 該当テストを走らせ、結果を報告に貼る。
報告は雛形 E の順で。日本語。

雛形 E —— 報告の形(受け取る側がそのまま検分に使える順)

## 直した点 / 足した点(依頼文の番号ごとに、どのコマで確かめたか)
## 門の表(雛形 A の各行: 門 | 実測値 | 判定 | 根拠のファイル)
## 画面の数字と帳簿の数字(量 | 実行の値 | 帳簿の値 | 一致/不一致)
## 検分用コマの所在(絶対パス)
## 描画時間・コマ数・解像度(実測)
## 分からなかった点・推測で埋めなかった点
## commit 一覧(push していないこと)

出典の信用と検証の打ち切り

論文・規格・公式文書は真値の出どころとして使うが、全面的には信用しない。誤植・単位の取り違え・再現できない数値は珍しくない。一方で、合わない出典を合わせようとして検証が永遠に終わらないのも失敗である。次の規則で打ち切る。

場面	規則
出典を選ぶ	公開データかコードが付いている物、複数の独立な出典が同じ値を出している物を優先。1 本しか無い数字は「出典 1 本」と明記
根拠の強さ	verified(一次文献の本文で確認)/ secondary(教科書・総説・公式文書)/ practitioner(経験則・手元の実験)を必ず付ける
再現を試みる	主張に要る数字だけを再現する。論文全体の再現はしない
打ち切り	同じ数字に 3 回の試み(または依頼文に書いた時間)で合わなければ止め、「未再現: 出典の値 X、こちらの値 Y、試した条件」を記録して先へ進む。自前の合成の真値で主張を立て直す
合いすぎる	出典と桁まで一致したら、同じ入力を両辺に渡していないか・出典の値をコードに写していないかを先に疑う
出典が怪しい	単位が合わない、図と表が矛盾する、他の出典と桁が違う —— その出典は根拠から外し、理由を書く。黙って使い続けない

打ち切った検証は失敗ではなく記録である。KNOWN_ISSUES.md か PoC の findings に「未再現」として残し、後で別の出典が出たら戻る。

分担の目安

判断で決まる部分(依頼する側が自分で書く)	量と配線(エージェントに任せる)
絵コンテ(何を映し、どの op の入出力と真値を並べるか)	描画パイプライン
画面の割り付け・カメラ経路・文字量	データ取得・前処理
図の構図と体裁、caption の 1 行目	op の実装と試験
評価の設計(真値の取り方・切り分け・標本数の下限)	帳簿と再生成、master 取込、CI の赤の修正
物理の検算