← / → navigate · Space autoplay
AI Research Note
Addy Osmani · April 2026

Agent Harness
Engineering

代理人工程架構

A coding agent is the model plus everything you build around it.

Model · Harness · Ratchet · HaaS

2026-05-07
Internal
core equation
coding agent
= model(s)
+ harness
harness includes →
prompts · tools · context
hooks · sandbox · subagents
logs · traces · feedback
PART 01 What is a Harness

If You're Not the Model, You're the Harness.

文件與規則
System prompt、CLAUDE.md、AGENTS.md、skill files
工具與技能
Tools、MCP servers、瀏覽器、搜尋、API
執行環境
Filesystem、Git、Bash、Sandbox
Context 管理
Compaction、tool-call offloading、progressive disclosure
任務編排
Planner / executor / evaluator、subagent dispatch
強制機制 + 觀測
Hooks、permission gate、lint / test、logs、traces
Harness anatomy
KEY INSIGHT

Claude Code、Cursor、Codex — 底層模型不同，差異主要來自 harness。

INTERNAL
PART 02 · SKILL ISSUE

It's Not a
Model Problem.
It's a Config
Problem.

Terminal Bench 2.0

同樣 Opus 4.6，
只改 harness →
Top 30 → Top 5

symptom → harness fix
不知道 coding convention
→ 寫進 AGENTS.md
執行破壞性指令
→ 加 Hook 攔截 rm -rf / DROP TABLE
40 步任務中途迷失
→ 拆成 Planner + Executor
跑出壞 code 卻認為完成
→ typecheck / lint / test 結果接回 loop
PART 03 The Ratchet

Every Mistake Becomes a Rule.

Agent 錯誤不是一次性故事，不是「運氣差」，是永久信號。

範例：Agent 送出含 commented-out test 的 PR
①AGENTS.md：「刪除 test，不要 comment out」
②pre-commit hook grep .skip( / xit(
③reviewer subagent 把此類 PR 標為 blocker
agents.md 設計原則
保持 60 行以內
飛行員 checklist 不是風格指南。越多規則，每條份量越低。
Ratchet，不要腦爆
每條規則追溯到一個真實失敗或硬性外部約束。
"Every line in a good AGENTS.md should be traceable back to a specific thing that went wrong."
— Addy Osmani
INTERNAL
PART 04 Harness Primitives

Start from Behaviour, Not Features.

Harness behavior mapping
Filesystem + Git
版本控 · rollback · 中間產出
Bash + Code Exec
即席造工具 · 通用工具層
Sandbox
安全隔離 · 自驗迴路
Memory + Search
AGENTS.md · MCP · 知識補全
Context 管理
Compaction · offloading · reset
Hooks（強制層）
系統強制 ≠ 告訴 agent
INTERNAL
PART 05 · CONTEXT ROT

Context Fills.
Models Degrade.

模型的推理能力隨 context 填滿而下降。三種技術應對 context rot。

Anthropic Engineering Team
Compaction
接近上限時，harness 智慧摘要舊 context，agent 不中斷繼續工作。
Tool-call Offloading
大量工具輸出只保留頭尾 token，細節存至 filesystem，需要時再查。
Progressive Disclosure
啟動時不塞入所有 tool / MCP；依任務動態載入，減少 prompt 污染。
Context Reset（長任務）
產生精簡交接檔 → 重啟乾淨對話繼續。RPG 存檔機制，帶必要狀態繼續。
PART 06 Long-Horizon Execution

Planning · Evaluators · Ralph Loops.

Planning
目標拆步驟寫入 plan file。每步完成後，hook 自動跑驗證並把結果注入迴圈。
Planner / Generator / Evaluator
分離生成與評估。Agent 替自己評分會偏高——獨立 evaluator 更準確。"GANs for prose"
Sprint Contract
Generator 與 Evaluator 先協商「完成的定義」，再開始產出。
RALPH LOOP
1
Agent 嘗試結束 session
2
Hook 攔截 exit 意圖
3
重注入原始 prompt 到 乾淨 context
4
從 filesystem 讀前次狀態繼續
single session → multi session agent
INTERNAL
PART 07 · ENFORCEMENT

Hooks &
AGENTS.md

"I told the agent"

≠ "The system enforces"

Success is silent,
failures are verbose.
HOOKS — 系統強制執行
每次 edit 後跑 typecheck / lint / test，失敗文字直接注入迴圈
阻擋 rm -rf / git push --force / DROP TABLE
開 PR / push main 前需要人工 approval gate
AGENTS.MD — 最高槓桿配置點
保持 60 行以內。每行競爭注意力，越多越稀釋。
Ratchet 原則：每條規則追溯到真實失敗，不腦爆。
MCP 安裝即信任。任何 MCP server 都可能 prompt-inject。
PART 08 Harnesses Evolve

Harnesses Don't Shrink. They Move.

"Every component in a harness encodes an assumption about what the model can't do on its own."

— Anthropic Engineering

假設失效 → 元件退場
模型解鎖新能力 → 新天花板 → 新元件
Model-Harness 訓練飛輪：模型 post-training 帶著 harness，在同一 harness 下表現最佳。
Model-harness training loop
Model-Harness Training Loop — Osmani 2026
INTERNAL
PART 09 · HaaS

From LLM API
to Harness Runtime.

Claude Agent SDK · Codex SDK · OpenAI Agents SDK — 三大平台往同一方向走。
Claude Code architecture
OPEN PROBLEMS

Harnesses →
Compiler.

Parallel Multi-Agent
多 agent 同時在同一 codebase 協作
Self-Improving Harness
Agent 分析自己的 trace，找出 harness 層失敗並修復
JIT Harness Assembly
依任務即時組裝正確工具與 context，靜態 config → 動態編譯器

Top coding agents look more like each other than their underlying models do.

KEY TAKEAWAY

The gap between what today's models
can do and what you see them do
is largely a harness gap.

Ratchet
Mistakes → Rules
Core Equation
Model + Harness
Direction
Config → Compiler
Treat every failure as a signal. Tighten the harness. Ship.
— Addy Osmani, April 2026
AGENT HARNESS ENGINEERING · 11 SLIDES