mirac221/frame-judge

frame-judge は何をしますか？

自分のビジュアル作品を自分で採点してはいけません。

あなたが構築し、レンダリングします。そして、別の批評家が、実際に画面に表示されたものと、ユーザーが実際に求めたものとを照らし合わせて判断します。批評家はあなたのコード、あなたの推論、あなたの結果に対する意見を決して見ることはありません。その作品が合格するか、ラウンドの上限に達するまで、あなたはそれを完成した、磨かれた、滑らかな、美しいと呼んではいけません。

なぜか: コードを書いたモデルは、自分の意図を出力に読み込みます。実際にレンダリングされる歩行サイクルではなく、書こうとした歩行サイクルを「見て」しまいます。批評家はピクセルとユーザーの言葉だけを受け取るため、それができません。見なければならないのです。

<skill> はこのファイルがあるフォルダを意味します（Claude Codeでは ${CLAUDE_SKILL_DIR}）。スクリプトはインストール不要のプレーンなNode 18+です。ワーキングディレクトリの .frame-judge/ に状態を保持します。

ループ

ステップ	内容	担当者
0	ユーザーのリクエストをそのままロック	あなた
0b	「アンスロップ？」と確認。はいの場合、スカウトが避けるべきAIのデフォルトを調査	あなた、ユーザー、スカウト
1	構築	あなた
2	レンダリングしてキャプチャ: スクリーンショット、フレームシート、モーショントレイル	スクリプト
3	機械的なセルフチェック: レンダリングされる、空白がない、ランタイムエラーがない	あなた
4	コードなしのレビューパケットをバンドル	スクリプト
5	プラットフォームが許可する場合、批評家がどのモデルで実行されるかを確認（一度だけ）	あなた、次にユーザー
6	批評家がバンドルをレビュー	新しいサブエージェント
7	ゲートがレビューを検証し、判断を下す	スクリプト
8	修正必須の指摘にすべて対応し、ステップ2に戻る	あなた
9	批評家の判定を報告（あなたの意見ではない）	あなた

デフォルトの上限: 3批評ラウンド。

0. 依頼をロックする

node <skill>/scripts/judge.mjs init --brief-file request.txt --kind frontend,motion

インラインテキストには --brief "..." を、標準入力から読み取るには --brief-file - を使用します。

• そのまま。 ユーザーのメッセージを書かれた通りに保存します: タイプミス、大文字、すべて。言い換えたり、要約したり、「明確化」したりしないでください。批評家はあなたの解釈ではなく、彼らの言葉に照らして判断します。
• 後でユーザーからの明確化 があれば judge.mjs brief --add "<彼らの正確な言葉>" で追加します。あなた自身の仮定は絶対に入れません。
• ユーザーが与えた参照画像: --ref mock.png（繰り返し可能）を追加して、批評家がそれらと比較できるようにします。
• --kind はルーブリックを選択します: frontend はページとUI、motion はアニメーション全般、video はクリップと編集用。キャプチャから自動検出させるには省略します。
• --critic-model ユーザーがすでにモデルを指定している場合。

これにより、.frame-judge/（自身をgitignoreします）が作成され、brief.md と ledger.json が配置されます。台帳はコンテキストの圧縮後も存続します。追跡できなくなった場合は、judge.mjs status を実行してください。

0b. アンスロップモードについて確認（構築前）

ユーザーに一度だけ、次の言葉で確認します:

アンスロップにしますか？（実験的: 品質が低下する可能性があり、より多くのトークンを消費します）

Claude Codeでは、AskUserQuestionを使用して、ステップ5の批評家モデルの質問と同じプロンプトで尋ねます。他の場所ではチャットで尋ねます。ユーザーがすでに回答している場合はスキップします。

• いいえ: そのまま続行します。アンスロップはデフォルトでオフです。
• はい:
  1. judge.mjs set unslop on を実行し、次に judge.mjs scout を実行します。スロップスカウトへのメッセージが出力されます: これは、AIがこの種のリクエストをどのように間違える傾向があるかを調べる、ウェブ検索機能を持つ新しいサブエージェントです。
  2. そのメッセージだけをスカウトに送信します。批評家と同じルールが適用されます: 新しいエージェント、フォークなし、何も追加しないでください。設定されている場合は批評家のモデルを使用します。
  3. その返信を保存し、その後 judge.mjs avoid --file <reply> を実行します。これにより、実際の情報源がないリストは却下されます。
• ウェブ検索が利用できない場合: ユーザーにここではアンスロップを実行できないと伝え、アンスロップなしで続行します。

回避リストは .frame-judge/avoid.md に保存され、すべてのレビューバンドルに含まれ、批評家はそれに対しても作品をチェックします。

「実験的」な理由は、デフォルトから逸脱することで構築が奇妙な方向に進む可能性があり、スカウトが追加のエージェント実行とウェブ検索を消費するためです。

1. 構築

アンスロップがオンの場合、最初に .frame-judge/avoid.md を読みます。

• 各パターンを回避するように設計します。単に逆にするだけではいけません: 目標は、単に異なるだけでなく、依頼に適合する作品です。
• ユーザーが明示的に求めたものは何でも、リストよりも優先されます。

構築する前に、references/craft.md の中から該当するメディアのセクションを、セッションごとに一度だけ読んでください。批評家が最もよく指摘する内容（間隔、タイポグラフィ、AIテンプレートの痕跡、イージング、歩行サイクル、ビデオのテンポ）をカバーしています。

アニメーションがあるものについては、時間を明示的な入力にします: シーク可能なタイムライン、または window.frameJudgeSeek(ms) フック。これによりキャプチャがフレーム正確になり、HTMLを無料でビデオに変換できます。

2. レンダリングとキャプチャ

ページとUI（Playwrightが必要; セットアップは references/capture.md を参照）:

node <skill>/scripts/capture-page.mjs http://localhost:5173 --out .frame-judge/cap/page

デフォルトはデスクトップ 1440×900、タブレット 768×1024、モバイル 390×844 で、画面ごとにキャプチャします。オプション:

• --actions states.json ホバー、メニュー、エラー状態用
• --color-scheme dark
• --reduced-motion
• ローカルファイルもURLと同様に機能します

ページ上のアニメーション。 これはフレーム正確（擬似クロックとWeb Animationsのシークを使用）で、MP4にエンコードします:

node <skill>/scripts/capture-page.mjs scene.html --out .frame-judge/cap/anim --animate 3000 --fps 30 --selector "#hero"

任意のビデオ（そのMP4を含む）:

node <skill>/scripts/video-frames.mjs .frame-judge/cap/anim/animation.mp4 --out .frame-judge/cap/anim-views --as motion

得られるもの:

• ビューポートスライス: 1つの巨大な全ページ画像（縮小されてつぶれてしまう）の代わりに使用。
• アクションファイルからの状態ショット。
• タイムスタンプ付きのコンタクトシート。
• フィルムストリップ: デフォルトで12 fpsでサンプリングされたフレーム、およびスクリプトが検出した突然のジャンプや停止の周辺をフルレートでサンプリング（--motion-fps source はすべてのフレームをすべての場所で使用）。サンプリングとは、1フレームのグリッチがタイルの間に落ちる可能性があることを意味します。そのため、イベント検出が存在します。
• モーショントレイル: 静止しているべきものは鮮明に、動くものはぼやけます。
• 客観的な数値: 再生時間、fps、黒またはフリーズしたセグメント、水平方向のはみ出し、壊れた画像。

ユーザーが体験するものをキャプチャします: 彼らが使用するすべてのビューポート、重要な状態、アニメーション全体。批評家は、あなたが示さなかったものを指摘することはできません。醜い部分を除外することは、このスキルが防止するために存在する不正行為そのものです。

3. 機械的なセルフチェック

批評ラウンドを使う前に、基本的な事項を確認して修正します:

• レンダリングされるか
• 空白や黒いフレームがないか
• 各 capture.json の builder_only に何もないか（コンソールエラー、失敗したリクエスト）
• 正しい再生時間とサイズか
• horizontal_overflow_px と broken_images がゼロか

これがリストのすべてです。あなたが「見た目が良い」と判断して批評家をスキップしてはいけません。

4. バンドル

node <skill>/scripts/judge.mjs bundle .frame-judge/cap/page .frame-judge/cap/anim-views

これにより .frame-judge/round-N/bundle/ が作成されます。そこにはビジュアルファイルのみ（png, jpg, webp, gif、および --include-video を渡した場合はビデオ）と、以下のテキストファイルが含まれます:

• brief.md（コードブロックは削除済み）
• ルーブリック
• CRITIC.md（批評家への指示）
• manifest.json（引用可能なアーティファクトID付き）
• prior.json（ラウンド2以降: あなたの「修正済み」という主張なしの未解決の指摘を含むため、批評家自身が確認します）

スクリプトは、修正必須の指摘が未対応のまま、またはラウンド上限に達している場合は、新しいラウンドを開始しません。批評家に送信する正確なメッセージを出力します。

画像予算: ラウンドごとに最大20画像を目指します。Claudeは1リクエストあたり20画像を超えると画像ごとの制限を厳しくします。各画像は約 ⌈w/28⌉×⌈h/28⌉ トークンを消費します。1440×900のショットは約1.7kです。コンタクトシートとフィルムストリップは1つの画像に12〜16フレームを詰め込めるので、それらを活用してください。--slices 3 は長いページをトリミングします。

5. 批評家のモデルを選択する（プラットフォームがサポートしている場合のみ）

サブエージェントのモデルを選択できるプラットフォームでのみ、かつラウンド1の前に一度だけ尋ねます。ユーザーがすでに指定している場合はスキップします。judge.mjs set critic-model <エイリアス> で回答を保存し、毎ラウンド再利用します。

プラットフォーム	確認するか？	方法
Claude Code, Claude apps	はい	AskUserQuestion、アンスロップの質問と同じプロンプトで: Sonnet（バランス良し、推奨）、Opus（最も鋭い目、最も多くの割り当て）、Haiku（最も安い、微妙な問題を見逃す）、Same as me
Codex app, Codex CLI	はい	チャットで尋ね、批評家を生成するときに選択を渡す
Antigravity	いいえ	生成ごとのモデル選択はありません。批評家はそのエージェントファイルの設定で実行されます。ユーザーにその旨を伝えてください。
その他	いいえ	サブエージェントごとのモデルを明らかにサポートしている場合を除きます。デフォルトを使用し、どのモデルが作品をレビューしたかをユーザーに伝えてください。

尋ねる場合は、トレードオフを正直に伝えてください。弱い批評家は安価ですが、より多くの欠陥を幻覚し、微妙なものを見逃します。ゲートは偽の証拠をキャッチしますが、悪い味をキャッチすることはできません。

プラットフォームごとの正確な構文: references/platforms.md。

6. 批評家を実行する

毎ラウンド新しい批評家を使用し、prior.json を超える記憶や以前の判断への関与がないようにします。バンドルが出力したメッセージのみを批評家に送信します:

あなたはフレーム批評家です。あなたのバンドルは <絶対パス> です。<絶対パス>/CRITIC.md を読み、それに正確に従ってください。そのフォルダの外にあるものは開かないでください。レビューJSONのみを返信してください。

• 何も追加しないでください。 自分が何を構築したかの要約も、「ヘッダーに注目」も、「脚を修正しました」も不要です。あなたの意見は、批評家が決して受け取ってはならない唯一の入力です。ユーザーが何かをチェックしてほしい場合、それはすでに依頼書に彼らの言葉で書かれています。
• フォークは禁止。 批評家をフォークやコンテキストを継承するものとして決して実行しないでください。そうすると、あなたの会話全体、コードを含めて見えてしまいます。
• インストールされたエージェントを優先。 frame-critic が存在する場合はそれを使用します。ファイルの読み取りに制限されているためです。スキルがClaude Codeプラグインとして提供された場合の名前は frame-judge:frame-critic、Codexでは frame_critic です。それ以外の場合は、同じメッセージを持つ汎用サブエージェントを使用します。
• Claude Code: 可能ならサンドボックスを実行。 claude CLIがPATHにある場合、サブエージェントを生成する代わりに node <skill>/scripts/critic-sandbox.mjs を実行します。これにより、批評家はバンドルのプライベートコピーで別のヘッドレスプロセスとして実行されます。そのプロセスはReadツールのみを持ち、コピーの外部への読み取りをブロックするフックがあり、スクリプト自体がレビューをゲートします（ステップ7をスキップ）。これが、コードブラインドネスが要求されるだけでなく強制される唯一のパスです。
• その他すべての場所: セッション内のサブエージェントを使用します。コードブラインドネスは批評家の指示に依存します。Claude Codeでは、ステップ7のトランスクリプト監査が、覗き見した批評家を依然としてキャッチします。Codex、Antigravity、Cursorではそれをチェックするものがないため、レポートでその旨を伝えてください。

返信をそのまま、.frame-judge/round-N/review.json に保存します。

7. ゲート

node <skill>/scripts/judge.mjs gate --review .frame-judge/round-N/review.json --reviewer subagent --transcript auto

Claude Codeでは、--transcript auto は批評家サブエージェントのトランスクリプトを見つけるため、ゲートは実際に開かれた画像（主張されたものではなく）をカウントし、バンドル外のものに触れた場合、レビューを無効にします。他の場所ではフラグをオフのままにします。その場合、カバレッジは自己報告となり、レポートはそのように述べます。（critic-sandbox.mjs は独自のトランスクリプトを自動的に渡します。）

ゲートが判断を下します。批評家の気分やあなたではありません:

• 拒否します: 存在しない、または批評家が開いたことのないアーティファクトIDを引用する指摘、証拠のない指摘、依頼書にない依頼書の引用、および不適切な重大度または信頼度の値を拒否します。
• カバレッジをチェック: 合格は、批評家がすべての画像を開いた場合にのみカウントされます。トランスクリプトが存在する場合はトランスクリプトから、そうでない場合は批評家自身の opened リストから検証します。
• 分離をチェック: トランスクリプトがある場合、バンドル外の読み取りはレビューを無効にします（RERUN_CRITIC）。
• 残りを分類:
  • must-fix（修正必須）: ブロッカーまたはメジャー、信頼度0.6以上
  • verify（検証）: ブロッカーまたはメジャー、信頼度0.6未満。より近くで再キャプチャ。盲目的に修正しないでください。
  • polish（改良）: マイナー
  • ignored（無視）: 細かい点
• チェック: CRITIC.md とルーブリックが編集されていないことを確認し、誰も審判を甘くしていないことを確認します。
• 台帳を更新し、1つの判断を出力:

判断	意味	あなたの行動
PASS	修正必須は残っておらず、依頼書からの欠落もなし	報告（ステップ9）
SELF_PASS	同上だが、自己レビューのフォールバックから	報告し、独立していなかったことを伝える
REVISE	修正必須の項目が存在する	ステップ8、その後新しいラウンド
RETHINK	批評家がアプローチ自体が根本的に間違っていると言っている	再構築前にユーザーに伝える
STOP_MAX_ROUNDS	上限に達したが、まだ不合格	何が未解決かを報告し、続行するか尋ねる
STOP_PLATEAU	このラウンドで何も解決しなかった	循環を停止。報告し、尋ねる
RERUN_CRITIC	レビューが使用不可（JSONがない、証拠のほとんどが偽、画像をスキップした批評家による合格、またはバンドル外を読んだ批評家）	同じバンドルで新しい批評家を実行
STOP_CRITIC_UNRELIABLE	2回連続で使用不可のレビュー	より強力な批評家モデルまたはフォールバックを提案

8. 修正

修正必須の項目をIDごとに、ブロッカーから順に処理します。次のラウンドまでにすべてに回答してください:

node <skill>/scripts/judge.mjs respond R1-F2 fixed "接触している足が4フレーム接地"
node <skill>/scripts/judge.mjs respond R1-F4 disputed "両側のガターは等しい" --evidence crop.png
node <skill>/scripts/judge.mjs respond R1-F6 wont-fix "ユーザーがこのグラデーションを要求した" --quote "purple to blue gradient"

• disputed（異議あり） には視覚的な証拠が必要です（例: 切り抜き、追加フレーム）。それは次のバンドルに含まれ、次の批評家が判断します。「CSSが16pxと言っている」は証拠ではありません。ピクセルが証拠です。
• wont-fix（修正しない） には、修正が違反するであろう依頼書からの正確な引用が必要です。
• 原因を修正し、キャプチャを修正しないでください。 指摘をかわすためにキャプチャを決して変更しないでください: 壊れたフッターを切り取る、モバイルビューポートを削除する、クリップをトリミングするなど。
• 検証項目と批評家の requests（リクエスト）: その箇所をより近くでキャプチャし（clip 付きのアクション、より密な --motion ウィンドウ）、次の批評家が確認または却下できるようにします。
• 批評家が keep（維持）にリストしたものを後退させないでください。
• ...