## Sources

1. [Agent Harness Engineering](https://www.oreilly.com/radar/agent-harness-engineering/)

---

### **Agent Harness Engineering – Addy Osmani**

The source material explores the emerging discipline of **harness engineering**, which focuses on the "scaffolding" built around AI models to create functional, reliable coding agents [1]. The core thesis is that **an agent equals the model plus its harness**, and the performance of an agent is often dominated more by the quality of its harness than the raw capabilities of the underlying model [2-4].

#### **Main Arguments**
*   **The "Harness" is the Differentiator:** While much public debate focuses on which AI model is "smartest," the most significant engineering leverage lies in the harness—the prompts, tools, context policies, and execution logic wrapped around the model [2, 5, 6].
*   **Failures as "Skill Issues":** Most agent failures should be viewed as **configuration problems** rather than inherent model flaws [6, 7]. If an agent makes a mistake, harness engineering dictates treating that failure as a signal to improve the system so the mistake never happens again [8].
*   **Performance Gap:** There is a significant "harness gap" between what today’s models can do and what they are observed doing [8]. A model running in a custom, optimized harness can significantly outperform the same model running in a generic or less-developed environment [7].

#### **Key Takeaways**
*   **Harness Composition:** A comprehensive harness includes **system prompts** (like `AGENTS.md`), **tools/skills**, bundled **infrastructure** (filesystems and sandboxes), **orchestration logic**, and **hooks** for deterministic execution [3].
*   **The "Ratchet" Workflow:** Harness engineering is an iterative discipline where **every mistake becomes a rule** [8]. Constraints should only be added when a real failure is observed and should be traceable to specific past errors [9, 10].
*   **Harness as a Service (HaaS):** The industry is moving from building directly on LLM APIs to building on **harness APIs** that provide pre-configured runtimes, including loops, tool-calling, and context management [11, 12].

#### **Important Details and Techniques**
*   **Durable State via Filesystems:** The filesystem is a foundational primitive that allows agents to read data, offload intermediate work, and coordinate with humans through shared files [13, 14].
*   **General-Purpose Tools:** While focused tools are useful, providing an agent with **Bash and code execution** within a sandbox allows it to build its own tools on the fly and solve complex problems autonomously [14, 15].
*   **Context Management:** To combat "context rot" (degraded reasoning as context fills up), harnesses use **compaction** (summarizing old context), **tool-call offloading** (storing large outputs on the filesystem), and **progressive disclosure** (revealing tools only when needed) [16, 17].
*   **Long-Horizon Execution:** Techniques like the **Ralph loop** (re-injecting prompts into fresh context windows) and **planner/generator/evaluator splits** help agents handle complex, multi-step tasks without losing coherence [18, 19].
*   **The Enforcement Layer (Hooks):** Hooks are scripts that run at specific lifecycle points to **enforce constraints**, such as blocking destructive commands (e.g., `rm -rf`) or requiring manual approval before pushing code [20].
*   **AGENTS.md:** This flat markdown file serves as a high-leverage "pilot’s checklist" for repository-specific conventions. It should be kept short (under 60 lines) to ensure the model can prioritize every rule [10, 21].
*   **The Future of Harnesses:** Leading coding agents (e.g., Cursor, Aider, Claude Code) are beginning to share similar harness patterns [22]. Future developments may include **self-fixing harnesses** that analyze their own traces to identify failure modes [23].