# osmani-agent-harness-engineering-2026-04-19

## Veille

Synthesis by Addy Osmani (Google, Chrome/Cloud) of the emerging field of *harness engineering*: the equation `agent = model + harness`, the *ratchet* principle ("every mistake becomes a rule"), the HumanLayer "skill issue" reframe, Terminal Bench evidence (Top 30 → Top 5 from a harness change alone), the layered Claude Code architecture, Anthropic's "harnesses don't shrink, they move" vision, and Harness-as-a-Service (Claude Agent SDK, Codex SDK, OpenAI Agents SDK). Pivot article that consolidates Trivedy, HumanLayer, Anthropic, and Böckeler into a doctrine.

## Titre Article

Agent Harness Engineering

## Date

2026-04-19

## URL

https://addyosmani.com/blog/agent-harness-engineering/

## Keywords

harness engineering, agent harness, Addy Osmani, Viv Trivedy, HumanLayer, Dex Horthy, Anthropic engineering, Birgitta Böckeler, agent = model + harness, ratchet principle, skill issue reframe, Terminal Bench, Claude Code architecture, Fareed Khan, Ralph Loop, planner evaluator split, AGENTS.md, hooks lifecycle, sandboxes, context rot, compaction, tool offloading, progressive disclosure, full context resets, model-harness training loop, Harness-as-a-Service, Claude Agent SDK, Codex SDK, OpenAI Agents SDK, just-in-time tool assembly

## Authors

Addy Osmani (Software Engineer at Google, Cloud + Gemini)

## Ton

**Profile**: A synthesis article signed by a recognized software engineer (Addy Osmani, Google, ex-Chrome) on his personal blog. Tech-editorial register with high conceptual density, first-person narration ("I've watched this play out", "in my own workflows"). Target audience: senior engineers and tech leads who build or operate coding agents in production, readers of Trivedy/HumanLayer/Böckeler looking for a consolidation piece. Authority built through the Google position and openly claimed personal practice.

**Style**: Long-form article structured in eight sections (pivot equation → "skill issue" → ratchet → 7 harness primitives → production architecture → harness movement → training loop → HaaS → open questions). Crisp sentences, tight metaphors (*"teaching someone to use a single kitchen gadget vs handing them a kitchen"* for bash, *"pilot's checklist, not style guide"* for AGENTS.md, *"GANs for prose"* for the planner/evaluator split). Explicit, credited citation of every source (Trivedy, Horthy/HumanLayer, Anthropic, Böckeler, Willison, Khan). Firm, programmatic tone, no hype. The document's strength lies in its **aggregative function**: Osmani doesn't propose a new framework, he gathers into doctrine what the pioneers published separately. It is the piece that shifts harness engineering from an emerging discipline to a shared consensus. The pivot figures circulate ("Top 30 → Top 5", "60 lines max in AGENTS.md") and the Anthropic line *"harnesses don't shrink, they move"* becomes the structuring aphorism of the 2026 debate.

## Pense-betes

- **Date and author**: April 19, 2026, Addy Osmani (Google, Cloud + Gemini, ex-Chrome).
- **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"*.
- Explicit credits:
- **Viv Trivedy**: coined the term *harness engineering*; the "Anatomy of an Agent Harness" post is the clearest derivation.
- **Dex Horthy / HumanLayer**: "skill issue" framing — most agent failures are configuration problems, not weight problems.
- **Anthropic Engineering**: best public breakdown on long-running harness design.
- **Birgitta Böckeler**: good user-side view.
- **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.
- **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.
- **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.
- 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.
- **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.
- **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."*
- **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.
- **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.
- **"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).
- **Key Anthropic quote**: *"every component in a harness encodes an assumption about what the model can't do on its own."*
- **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"*.
- **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."*
- **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."*
- 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."*
- 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.

## RésuméDe400mots

Addy Osmani (Google) published an article on April 19, 2026 that consolidates into doctrine what Viv Trivedy, HumanLayer, Anthropic, and Birgitta Böckeler have published separately since early 2026: *harness engineering*. His thesis holds in one equation, credited to Trivedy:

> *"Agent = Model + Harness. If you're not the model, you're the harness."*

Reformulated by Osmani: a correct model in a great harness beats a great model in a bad harness. The empirical proof comes from Terminal Bench 2.0: Claude Opus 4.6 inside Claude Code scores markedly lower than the same model inside a custom harness, and the Trivedy team took a coding agent from **Top 30 to Top 5 by changing only the harness**.

Osmani articulates three methodological principles. The ***skill issue reframe*** (HumanLayer): most failures are not model limitations but configuration problems. The ***ratchet principle***: every line of an AGENTS.md must be traceable to a concrete past failure — *"add only when you've seen a real failure, remove only when a capable model has made them redundant"*. The ***working backwards from behaviour*** approach: don't pre-build infrastructure, derive each component from the expected behavior.

Seven harness primitives follow: filesystem and Git (durable state), bash and code execution (*"hand them a kitchen, not a single kitchen gadget"*), sandboxes (isolation and defaults), memory and search (reloaded AGENTS.md, MCP, Context7), battling context rot (compaction, tool-call offloading, progressive-disclosure skills, Anthropic's full context resets), long-horizon execution (Ralph Loop, planning, **planner/evaluator split** — *"GANs for prose"*), hooks (*"success is silent, failures are verbose"*).

On AGENTS.md, two lessons: under 60 lines (HumanLayer), *"pilot's checklist, not style guide"*. On tools: *"ten focused tools outperform fifty overlapping ones"* — including MCP security.

Osmani then draws on Fareed Khan's breakdown of the Claude Code architecture into seven layers (input, knowledge, integration, execution, output, observability, multi-agent) to show that every prior concept has a concrete home in production.

Then comes the Anthropic phrase that frames the debate: *"Harnesses don't shrink, they move."* When a model improves, the scaffolding that encoded its limitations disappears, but the ceiling moves and new scaffolding emerges. Added to this is the **model-harness training loop**: useful primitives become standard, get post-trained into the next model, creating co-training and overfitting (Opus 4.6 *"feels different inside Claude Code"*).

The article closes on *Harness-as-a-Service* (Claude Agent SDK, Codex SDK, OpenAI Agents SDK) and three open questions: multi-agent orchestration on a shared codebase, self-analyzing harnesses, JIT tool/context assembly *"closer to a compiler than to static config"*.

A consolidation piece that stabilizes the field's shared vocabulary and shifts harness engineering from an emerging discipline to a shared consensus.

## GrapheDeConnaissance

- Addy Osmani —publie→ Agent Harness Engineering (DOCUMENT, 0.98)
- Addy Osmani —travaille_chez→ Google (ORGANISATION, 0.97)
- Addy Osmani —affirme_que→ un modèle correct dans un excellent harnais bat un excellent modèle dans un mauvais harnais (AFFIRMATION, 0.97)
- Viv Trivedy —a_créé→ Harness engineering (METHODOLOGIE, 0.97)
- Viv Trivedy —a_créé→ équation Agent = Model + Harness (CONCEPT, 0.97)
- Harness engineering —est_basé_sur→ ratchet principle (CONCEPT, 0.95)
- Ratchet principle —est_basé_sur→ AGENTS.md (CONCEPT, 0.95)
- HumanLayer —recommande→ reframe skill issue pour échecs d'agent (CONCEPT, 0.95)
- Dex Horthy —dirige→ HumanLayer (ORGANISATION, 0.92)
- Terminal Bench 2.0 —mesure→ passage Top 30 → Top 5 par changement de harnais seul (MESURE, 0.97)
- Harnais custom (Trivedy) —surpasse→ Claude Code (même modèle Claude Opus 4.6, Terminal Bench 2.0) (TECHNOLOGIE, 0.93)
- Anthropic —affirme_que→ "harnesses don't shrink, they move" (CITATION, 0.97)
- Anthropic —recommande→ planner generator evaluator split (METHODOLOGIE, 0.95)
- Ralph Loop —utilise→ hook qui ré-injecte prompt dans fresh context window (CONCEPT, 0.93)
- HumanLayer —recommande→ garder AGENTS.md sous 60 lignes (AFFIRMATION, 0.92)
- Hooks —est_basé_sur→ Success is silent failures are verbose (CONCEPT, 0.95)
- Fareed Khan —publie→ architecture Claude Code en 7 couches (DOCUMENT, 0.92)
- Claude Code —est_basé_sur→ architecture en 7 couches (input, knowledge, integration, execution, output, observability, multi-agent) (CONCEPT, 0.93)
- Model-harness training loop —permet→ co-training et overfitting (CONCEPT, 0.95)
- Claude Agent SDK —fait_partie_de→ Harness-as-a-Service (CONCEPT, 0.95)
- Codex SDK —fait_partie_de→ Harness-as-a-Service (CONCEPT, 0.95)
- OpenAI Agents SDK —fait_partie_de→ Harness-as-a-Service (CONCEPT, 0.95)
- Addy Osmani —affirme_que→ les patterns de harnais convergent entre Claude Code, Cursor, Codex, Aider et Cline (AFFIRMATION, 0.92)
- Birgitta Böckeler —publie→ vue utilisateur du harness engineering (DOCUMENT, 0.9)

---
Canonical: https://www.thekb.eu/en/fiches/osmani-agent-harness-engineering-2026-04-19/