研究框架（Research harness）
在長時間的實驗工作中，模型本身很少是問題所在。真正出問題的是它周圍的空間：一個不知不覺改變的資料分割、一個手動輸入的數字、一個洩漏到訓練集的測試集、一個早已失敗的想法第六個變體、一個鎖住帳戶的輪詢迴圈。這個技能將這些規則從文字敘述轉移到檔案、程式碼與掛鉤中，遵循 Agent 工程中的框架（Harness）/ 迴圈（Loop）/ 圖（Graph）架構。
三層架構，對應到實驗
框架（Harness，空間）。
contract.json：聲明、協定、閘門、運算規則。已凍結。CLAUDE.md：專案的簡短地圖，而非手冊。frozen/：分割清單、eval.py、複製的基線數字。以雜湊鎖定且為唯讀。harness/launch.py：啟動執行作業的唯一方式。它強制執行 GPU 允許清單與空閒規則，並以分離模式啟動作業。traces.jsonl：每個事件一行。state.json：閘門的決策。lessons.md：已造成兩次修正成本的錯誤。
迴圈（Loop，時間）。
-
L1 驗證迴圈：
frozen/eval.py為每次執行評分。它是指標的唯一來源。 -
退出由程式碼決定（
harness/gate.py）：- PASS： 候選方案以指定差距超越參考。
- BUDGET_EXIT： 已達到最大變體數量。
- STALL_EXIT： N 輪內無進展。
- REPRO_FAIL： 我們的基線重新實作與論文差異過大。
模型永遠不會自行宣告「完成」。
-
L4 等待變更： 每個作業最後寫入
runs/<id>/DONE。以一個背景監看程式等待該檔案，而非重複輪詢。
圖（Graph，路徑）。 刻意保持簡潔：
分割 → 凍結 → 特徵 → 參考執行（基線重新實作） → 候選變體 → 閘門 → 報告。
每個箭頭都是一個檔案合約（分割 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，並為每次執行記錄程式碼雜湊。 - 一次執行，一個問題。 使用執行 ID 與標籤來說明測試內容（
gfre_repro_s0、ml_l12-24_k256）。候選想法的變體共享閘門的candidate_tag。任何其他事項（例如除錯或冒煙測試）使用不同的標籤，以免消耗預算。 - 尊重閘門。
- CONTINUE 表示你可以嘗試另一個變體。
- BUDGET_EXIT、STALL_EXIT 和 REPRO_FAIL 表示停止並將證據呈交給人類。不要第六次修補那個想法。
- 凍結的協定在專案進行中永不改變。 如果必須改變（分割中的錯誤、從作者那裡學到的協定細節），由人類編輯
FROZEN.sha256並開始新的凍結。先前的結果保留在results.jsonl中，並有其自己的歷史。 - 使用單一背景監看程式等待
DONE檔案。 迴圈中的每個 ssh 呼叫都使用-o BatchMode=yes，並在退出碼為 255 時停止。 - 每次執行後，讀取
status.py的輸出，而不是原始日誌。僅在失敗時開啟log.txt。 - 當錯誤重複發生時， 在
lessons.md中新增一行，並儘可能將其轉換為檢查（src/中的 assert、掛鉤規則、清單檢查）。
審查者通過（在信任 PASS 之前）
為每個檢視角度（lens）產生一個審查者子代理。提供它們程式碼與檔案，而非你的結論：
- 資料洩漏： 訓練、驗證與測試檔案是否有重疊？排除的模式是否真的被排除？測試標籤是否曾經觸及訓練程式碼？
- 協定： 分割、測試集、閾值與指標是否符合原始論文與
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 月）。