Addy Osmani on Agent Harness Engineering: Model + Harness

Key takeaways

1. Date and author. April 19, 2026, Addy Osmani (Google, Cloud + Gemini, ex-Chrome).
2. Pivot equation. (credited to Viv Trivedy): "Agent = Model + Harness. If you're not the model, you're the harness." Osmani's reformulation: "a decent model with a great harness beats a great model with a bad harness".
3. Explicit credits:
4. Viv Trivedy. coined the term harness engineering; the "Anatomy of an Agent Harness" post is the clearest derivation.
5. Dex Horthy / HumanLayer. "skill issue" framing — most agent failures are configuration problems, not weight problems.
6. Anthropic Engineering. best public breakdown on long-running harness design.
7. Birgitta Böckeler. good user-side view.
8. Ratchet principle. "Every line in a good AGENTS.md should be traceable back to a specific thing that went wrong." A constraint is added only after a real failure. It is removed only once a more capable model has made it redundant.
9. Skill issue reframe (HumanLayer). "It's not a model problem. It's a configuration problem." The default "wait for the next version" is explicitly rejected.
10. Terminal Bench data. (Trivedy/HumanLayer cited): on Terminal Bench 2.0, Claude Opus 4.6 inside Claude Code scores markedly lower than the same model inside a custom harness. The Trivedy team took a coding agent from Top 30 to Top 5 by changing only the harness. Massive empirical proof.
11. The "working backwards from behaviour" pattern: "behaviour we want (or want to fix) → harness design to help the model achieve this". If you can't name the behavior a component delivers, it shouldn't be there.
12. 7 harness primitives. 1. Filesystem & Git: durable state, shared human/agent workspace, free versioning. 2. Bash & code execution: "the difference between teaching someone to use a single kitchen gadget and handing them a kitchen." Willison cited. 3. Sandboxes: isolation, good defaults (pre-installed runtimes, headless browser for verification). 4. Memory & search: AGENTS.md reloaded every turn + MCP/Context7 to fill the cutoff. 5. Battling context rot: 3 techniques — compaction (intelligent summaries), tool-call offloading (head/tail tokens, full output kept on disk), skills with progressive disclosure (reveal tools/instructions on demand). Anthropic adds the full context reset with a structured hand-off file. 6. Long-horizon execution: Ralph Loop (a hook that re-injects the original prompt into a fresh context window), planning with a plan file, planner/generator/evaluator split (Anthropic explicitly states: "separating generation from evaluation outperforms self-evaluation"), sprint contract (negotiate the "done" condition before writing code). 7. Hooks: enforcement layer. HumanLayer principle: "success is silent, failures are verbose". Block destructive bash, run typecheck after edit, require approval before pushing to main.
13. AGENTS.md. "flat markdown rulebook at the root of your repo... lands in the system prompt every turn." HumanLayer keeps theirs under 60 lines. "Pilot's checklist, not style guide. Earn each line."
14. Tool economy. "Ten focused tools outperform fifty overlapping ones because the model can hold the menu in its head." MCP security: tool descriptions = trusted text, a malicious MCP can prompt-inject before you type anything.
15. Layered Claude Code architecture. (Fareed Khan reference): input layer (UI, session manager, permission gate) → knowledge layer (skill registry, context compressor, task graph, memory store) → integration layer (MCP runtime) → execution layer (tool dispatch, streaming runtime, prompt cache) → output layer → observability layer → multi-agent layer (subagent spawning, mailboxes, FSM protocol, autonomous board, worktree isolator). Master agent loop at the center.
16. "Harnesses don't shrink, they move". (Anthropic): the debate's structuring aphorism. Opus 4.6 killed Sonnet 4.5's context-anxiety failure mode → all the "anxiety-mitigation" scaffolding is now dead code. But the ceiling moved: new tasks unlocked → new failure modes → new scaffolding (multi-day memory policy, coordination across 3 specialized agents, design-quality evaluators).
17. Key Anthropic quote. "every component in a harness encodes an assumption about what the model can't do on its own."
18. Model-harness training loop. a primitive discovered in the harness → standardized in the product → used for post-training the next model → next model gets better at that primitive. Cycle. Creates co-training / overfitting: "a genuinely general model wouldn't care whether you used apply_patch or str_replace, but co-training creates overfitting." Explains why Opus 4.6 "feels different inside Claude Code than inside someone else's harness".
19. Harness-as-a-Service (HaaS). Trivedy's framing. Shift from "build on LLM APIs (completion)" → "build on harness APIs (runtime)". Cited triad: Claude Agent SDK, Codex SDK, OpenAI Agents SDK. Four configuration pillars: system prompt, tools, context, subagents. Trivedy's aphorism: "good agent building is an exercise in iteration. You can't do iterations if you don't have a v0.1."
20. 3 open questions for what's next. 1. Multi-agent orchestration on a shared codebase. 2. Self-analyzing harnesses that detect and fix their own failure modes. 3. JIT tool/context assembly — "harnesses stop being static config and start becoming something closer to a compiler."
21. Underlying observation: "Look at the top coding agents side by side (Claude Code, Cursor, Codex, Aider, Cline) and they look more like each other than their underlying models do. The models are different. The harness patterns are converging."
22. Watch-file positioning: a piece of doctrinal consolidation across Trivedy (coined the term, March 2026), Böckeler (user-side view, April 2026), Seale (semantic agent, April 2026). Osmani aggregates and stabilizes the shared vocabulary.