リサーチハーネス

長期の実験作業で壊れるのは、モデルであることはめったにありません。壊れるのはその周辺の空間です。つまり、静かに変更された分割、手入力された数値、学習データにリークしたテストセット、既に失敗したアイデアの6番目のバリエーション、アカウントをロックするポーリングループなどです。このスキルは、それらのルールを散文ではなくファイル、コード、フックに移し、エージェントエンジニアリングのハーネス/ループ/グラフのフレームワークに従います。

実験にマッピングされた3つのレイヤー

ハーネス（空間）

contract.json: 請求、プロトコル、ゲート、計算ルール。凍結。
CLAUDE.md: プロジェクトの短いマップ。マニュアルではありません。
frozen/: 分割リスト、eval.py、コピーされたベースライン数値。ハッシュロックされ、読み取り専用。
harness/launch.py: 実行を開始する唯一の方法。GPU許可リストとアイドルルールを強制し、ジョブをデタッチして開始します。
traces.jsonl: イベントごとに1行。
state.json: ゲートの決定。
lessons.md: 修正に2回のコストがかかったミス。

ループ（時間）

L1 検証ループ: frozen/eval.py がすべての実行をスコアリングします。唯一のメトリクスソースです。
終了はコードで決定（harness/gate.py）:
- PASS: 候補が参照をマージン分上回る。
- BUDGET_EXIT: 最大バリアント数に達した。
- STALL_EXIT: Nラウンド改善なし。
- REPRO_FAIL: 我々のベースライン再実装が論文から乖離しすぎている。
モデル自体が「完了」を宣言することはありません。
L4 変更の待機: 各ジョブは最後に runs/<id>/DONE を書き込みます。繰り返しポーリングするのではなく、1つのバックグラウンドウォッチャーでそのファイルを待機します。

グラフ（経路） 意図的に小さく保つ: 分割 → 凍結 → 特徴量 → 参照実行（ベースライン再実装） → 候補バリアント → ゲート → 報告書。各矢印はファイル契約です（分割TSV、特徴量 DONE.json、実行の scores/）。

プロジェクトのセットアップ

template/ をサーバ上のプロジェクトにコピーします。タスクコードを src/ にコピーします（examples/aigi/ はAI生成画像検出の完全な動作例です）。
template/contract.example.json から contract.json を記述します:
- claim: 数値を含む一文。
- protocol: ソース論文が定義する通りに。特定されていない詳細と選択を open_questions にリストします。
- gate: 参照タグ、論文値、マージン、予算。
- compute: Pythonパス、ノード/GPU許可リスト、アイドルルール。
paths.json（データセットルート）を記述し、ベースライン数値を frozen/baselines.json にコピーします。PDFからスクリプトでパースし、平均を再チェックします。決して手で打ち直さないでください。
凍結: python harness/freeze.py add contract.json frozen/eval.py frozen/baselines.json。
launch.py を通じて分割を生成し、マニフェスト数を読み取り、その後分割を凍結します。
Claude Codeを実行しているマシンにガードフックをインストールします:
- hooks/research_guard.py を <project>/.claude/hooks/ にコピーします。
- <project>/.claude/research_guard.json を記述し、リモートプロジェクトディレクトリ名を project_markers エントリとして使用します。
- hooks/settings.snippet.json を <project>/.claude/settings.json にマージします。

運用ルール

数値は result.json またはゲート行からのみ取得します。 引用し、チャットでメトリクスを計算したり打ち直したりしないでください。数値が eval.py が書き込んだファイルにない場合、それはまだ存在しません。
launch.py を通じてのみ実行を開始します。 再利用された実行ID、変更された凍結ファイル、ビジーなGPUを拒否し、すべての実行のコードハッシュを記録します。
1実行、1質問。 実行IDとタグを使用して、テスト内容を示します（gfre_repro_s0、ml_l12-24_k256）。候補アイデアのバリエーションはゲートの candidate_tag を共有します。デバッグやスモークテストなど、その他のものは異なるタグを使用して予算を消費しないようにします。
ゲートを尊重します。
- CONTINUE は別のバリアントを試してもよいことを意味します。
- BUDGET_EXIT、STALL_EXIT、REPRO_FAIL は停止し、証拠を人間に持っていくことを意味します。アイデアを6回目もパッチしないでください。
凍結プロトコルはプロジェクトの途中で決して変更しません。 変更が必要な場合（分割のバグ、著者から学んだプロトコルの詳細）、人間が FROZEN.sha256 を編集し、新しい凍結を開始します。以前の結果は独自の履歴とともに results.jsonl に残ります。
DONE ファイルを1つのバックグラウンドウォッチャーで待機します。 ループ内のすべてのssh呼び出しは -o BatchMode=yes を使用し、終了コード255で停止します。
各実行後は、生のログではなく status.py の出力を読みます。 失敗時のみ log.txt を開きます。
ミスが繰り返された場合は、lessons.md に行を追加し、可能であればチェックに変換します（src/ 内のアサート、フックルール、マニフェストチェック）。

レビュアーパス（PASSを信頼する前）

レンズごとに1つのレビューアーサブエージェントを起動します。各サブエージェントにはコードとファイルを与え、あなたの結論は与えないでください:

リーク: 学習、検証、テストファイルに重複はありますか？除外パターンは本当に除外されていますか？テストラベルが学習コードに到達することはありますか？
プロトコル: 分割、テストセット、しきい値、メトリクスはソース論文と contract.json に一致していますか？open_questions の選択は開示されていますか？
公平な比較: 参照再実装は許容範囲内ですか？コピーされたベースライン数値は同じプロトコルからのものですか？再実行されたベースラインにはマークが付いていますか？

レビュアーの価値は、それが変更する決定とまったく同じです。各レンズは具体的なファイル/行の証拠、または何も返しません。

ファイル

template/                 新しいプロジェクトにコピー
  CLAUDE.md               マップ（タイトルを編集）
  contract.example.json   請求 / プロトコル / ゲート / 計算
  lessons.md
  harness/                launch.py job.sh gate.py status.py freeze.py check_frozen.py trace.py common.py
  frozen/eval.py          バイナリ検出評価器（しきい値でのACC + テストセットごとのAP）
hooks/                    research_guard.py + 設定例 + 設定スニペット
examples/aigi/            AI生成画像検出: GenImage + CNNDetection分割、CLIP特徴量キャッシング、GFREスタイル再構成検出器、GFREテーブルパーサー

クレジット: ハーネス/ループ/グラフのフレームワークは @0xwhrrari の「Harness, Loop and Graph」（2026年11月）に従います。

research-harness