Karpathy Agent Harness 實作拆解：program.md 與 Git 迴圈

AI
, , , ,
1

以 Karpathy 的 autoresearch 為例，拆解 Agent Harness 的 program.md、Git rollback、immutable evaluator 與 Inner/Outer Loop，教你建立可持續收斂的 Agent 系統。

先釐清一個常見誤會：那句「不要再直接 prompt coding agents，而要設計會去 prompt agents 的 loops」原始貼文不是 Andrej Karpathy，而是 OpenClaw 作者 Peter Steinberger 的分享；Claude Code 負責人 Boris Cherny 也表達過類似的工作方式。不過 Karpathy 確實有更具體的公開實作：GitHub 上的 karpathy/autoresearch，以及他先前公開測試過的「4 個 Claude + 4 個 Codex」多 Agent 研究組織。以下直接拆解這套設計背後的工具、迴圈與可複製原則。

一句話理解 Karpathy 的作法

Karpathy 沒有發明新的 Agent Framework，也不是完全不用 Prompt。他把 Prompt 從「每次告訴 Agent 下一步做什麼」提升為「定義一個可以持續運轉的制度」，讓 Agent 在 Eval → Feedback → Rollback → Retry 的閉迴圈裡工作。

以前的流程是：

Human
  ↓
Prompt
  ↓
Agent
  ↓
Code
  ↓
Human review
  ↓
再 Prompt
  ↓
Agent

改成 Loop 後：

Human 修改 program.md（研究制度 / organization code）
  ↓
Claude Code / Codex 修改 train.py
  ↓
git commit
  ↓
immutable evaluator（prepare.py）
  ↓
val_bpb 有改善？
  ├─ YES → keep commit
  └─ NO  → git reset
  ↓
下一次 experiment（重複）

官方 README 甚至直接指出：人類不再主要修改 Python，而是修改 program.md，也就是「programming the autonomous research org」。

Karpathy 實際使用了哪些工具

  • Claude Code / OpenAI Codex：他沒有自製 Coding Agent runtime。Agent 是可替換的 execution engine。
  • program.md：核心不是普通 prompt，而是一份持久化的 operating procedure。Karpathy 稱它是非常輕量的 skill，由人類維護。
  • Git branch / commit / reset：Git 不只是版本控制，而是 Harness 的 state machine、checkpoint 與 rollback mechanism。
  • train.py：Agent 唯一主要允許修改的 mutable surface。模型架構、optimizer、hyperparameter、training loop 都可以改。
  • prepare.py：Agent 不可以修改。裡面的 evaluator 是 ground truth，形成 immutable verifier，避免 Agent 最後「修改考卷讓自己考滿分」。
  • results.tsv + run.log：實驗、commit、score、keep/discard 狀態寫入磁碟，不全部塞進 context window；大量 console output 先寫檔，再用 grep 只餵最重要的結果回 Agent。
  • Python + uv + NVIDIA GPU：公開版是 single-GPU 設計，每個 experiment 固定約 5 分鐘，約可做到每小時 12 次實驗。
  • Git worktree + tmux + simple files：多 Agent 版本中，每個 researcher 有自己的 branch/worktree，Agent 之間用普通檔案溝通，tmux grid 顯示所有 session；當時刻意不用 Docker/VM。

program.md 裡真正的 Loop

Karpathy 公開的 program.md 寫得非常直接：要求 Agent 啟動 experiment loop 後 LOOP FOREVER、NEVER STOP，不要反問使用者「Should I continue?」，而是一直跑，直到人類手動 interrupt。Experiment 超過 10 分鐘就 kill + revert；crash 可修就修，方向錯了就 discard。

核心迴圈可以濃縮成：

while True:
    inspect_git_state()
    idea = think_of_next_experiment()
    edit('train.py', idea)
    git_commit()
    run('uv run train.py > run.log 2>&1')

    score = grep('val_bpb', 'run.log')
    memory = grep('peak_vram_mb', 'run.log')

    append_to_results_tsv(
        commit=commit,
        score=score,
        memory=memory,
        description=experiment_description
    )

    if score < best_score:
        keep_commit()
    else:
        git_reset_to_previous_best()

這已經不只是「把 Prompt 寫好」，而是一份用自然語言寫的 state machine。

Agent Harness 的系統對照

元件 角色
LLM reasoning engine
Claude Code / Codex agent runtime
program.md control policy
train.py mutable environment
prepare.py trusted verifier
val_bpb reward function
Git state + checkpoint + rollback
results.tsv persistent memory
run.log observation stream
grep / tail context compression
timeout resource budget
LOOP FOREVER scheduler / control loop

另一個容易被忽略的細節是 Context Engineering：Karpathy 刻意把 uv run train.py 的完整輸出導向 run.log，不要用 tee 讓 output 灌回 context。真正餵回 Agent 的通常只有 grep '^val_bpb:\|^peak_vram_mb:' run.log，只有 crash 時才 tail -n 50 run.log。也就是說，Harness 負責決定模型需要看什麼、不需要看什麼。

Inner Loop vs Outer Loop

Claude Code、Codex 這類 Coding Agent 本身已經有一層 Inner Agent Loop：

LLM thinks
  ↓
calls tool
  ↓
reads result
  ↓
thinks again
  ↺

Karpathy 真正在 engineering 的，是在外面再包一層 Outer Loop：

propose experiment
  ↓
INNER AGENT LOOP
  ↓
produce code
  ↓
run verifier
  ↓
compare metric
  ↓
keep / rollback
  ↓
next experiment

所以最準確的形容不是「不用 Prompt」，而是：把 Prompt 從 task-level instruction 移到 system-level policy，再讓 deterministic feedback loop 接管日常決策。

4 Claude + 4 Codex 的多 Agent 實驗

Karpathy 公開測試過更像「Agent Organization」的版本：同時放多個 Claude 與多個 Codex，每個 research program 對應 Git branch，各 scientist 再開 feature branch，用 Git worktree 做 filesystem isolation；Agent 之間用普通檔案傳訊，所有 session 放在 tmux grid 中，方便直接介入接手。

他測試過 8 個 independent researchers，以及 chief scientist + junior researchers 等 topology。結果反而凸顯一個重點：Agent 的 implementation 很強，但 experiment design 不夠強。它們會產生沒意義的 variation、不建立強 baseline、不好好做 ablation、不控制 runtime / FLOPs，甚至可能把「增加 network size → validation loss 下降」這類 trivial / confounded 的結果誤認成研究發現。

換句話說，multi-agent 不是「1 個 Agent 不夠聰明，放 8 個就 8 倍聰明」。真正的瓶頸變成 experiment design、evaluation、coordination、memory、resource allocation 與 hypothesis selection，也就是 Harness 本身。這也解釋了為什麼 Karpathy 後來的 autoresearch 刻意保持簡單。

他在同一個脈絡下提出的「programming an organization」概念也很重要：未來的 source code 不再只有 .py、.ts、.go，還會包含 prompts、skills、tools、roles、processes、evaluation、communication protocol、standup、handoff、Git rules、resource allocation。這整包東西就是 ORG CODE。

Codex 的 NEVER STOP 問題

Karpathy 曾在 autoresearch 的 GitHub issue 反映：Codex 會忽略 NEVER STOP，跑幾輪後自己結束；Claude 對持續 loop 的表現比較符合他的預期。社群最簡單的 workaround 是在外面再包一層 Supervisor Loop：

while true; do
  codex exec 'Read program.md and run the next experiment'
  sleep 1
done

因此更完整的 Harness 架構可能是：

Supervisor / watchdog
  ↓ 必要的話重啟 agent
Agent session（Inner Agent Loop）
  ↓
modify project
  ↓
deterministic eval
  ↓
keep / reset
  ↓
next iteration

把這個模式套到一般軟體開發

autoresearch 的 pattern 可以映射成一般的軟體開發流程。Repo 可以長這樣：

my-project/
├── program.md          # Agent 的 operating system
├── src/                # Agent 可以修改
├── eval/               # Agent 不可以修改
│   ├── unit-tests/
│   ├── integration-tests/
│   ├── e2e/
│   ├── benchmark/
│   └── score.py
├── state/
│   ├── results.jsonl
│   ├── current-goal.md
│   └── best-commit.txt
├── logs/
└── harness.sh

Harness 主迴圈：

while budget_remaining():
    agent.read(
        'program.md',
        'state/results.jsonl',
        current_repo_state
    )
    agent.choose_next_change()
    agent.edit_code()
    git.commit()

    result = verifier.run(
        tests=True,
        typecheck=True,
        lint=True,
        e2e=True,
        benchmark=True
    )

    if result.hard_gates_failed or result.score <= best_score:
        git.reset_to_best()
    else:
        mark_as_best()
        update_state()

此時 Definition of Done 不再只是「請幫我確認功能做好了」，而是可驗證的閘門：Unit tests PASS、TypeScript typecheck PASS、ESLint PASS、Playwright E2E PASS、visual regression 低於門檻、Lighthouse 分數達標、API latency P95 在預算內、security tests PASS。

這背後有一條關鍵公式：Verifier 越 deterministic，Agent autonomy 就可以放得越高。因此不要急著搬出 LangGraph、CrewAI、AutoGen、Temporal、Redis、Vector DB、Message Queue 或 Kubernetes。Karpathy 的公開版本刻意選擇 Claude Code / Codex + Markdown + Git + Shell + files + deterministic evaluator，先把 Loop 做對，再處理 orchestration。

需要特別查證：LOOPS.md

網路上流傳的 LOOPS.md: Field Notes on Agents That Run for Days 常被標成 Andrej Karpathy 的私人 Harness rules。目前沒有可信的 primary source 可以確認是 Karpathy 本人公開發布；內容很多是好的 Harness Engineering 原則，但引用時應標註「attributed to Karpathy, but unverified」。

可以 100% 確認的 Karpathy 原始實作，是 autoresearch 這個 repo 及其中的 program.md。

結論

Karpathy 的 Agent Harness 本質不是設計「Agent 下一句要聽什麼」，而是設計「什麼環境會讓 Agent 自己持續朝正確答案收斂」。換成控制系統語言：

概念 對應
program.md Policy
LLM Controller / Reasoner
tools Actuators
repo Environment
tests / eval Sensors
metric Reward / Feedback
Git State + Rollback
loop Control System

這就是為什麼 autoresearch 看起來只有幾個檔案，卻比很多上萬行的 Multi-Agent Framework 更值得研究：真正的槓桿不在 Agent 本身，而在 Harness 的迴圈、驗證與 rollback 設計。