Harness Engineering: Why a Powerful Model Isn't Enough — Here's What Really Matters

The Core Question Raised by a Data-Deletion Disaster

On July 9th, OpenAI released ChatGPT Work and GPT-5.6. The very next day, AI entrepreneur Matt Schumer posted on X about an incident: while testing an Agent's Ultra mode, because he had enabled Full Access permissions, an Agent mistakenly executed a recursive delete command pointed at his user directory, wiping out nearly all the files on his Mac. Screenshots showed it was the result of a "file cleanup" operation gone wildly wrong.

It's worth adding that recursive delete commands (like rm -rf on Unix/Linux) are among the most destructive commands in an operating system. The -r flag stands for recursive, and -f stands for force; combined, they mean: delete all files and subdirectories under the specified path without confirmation and without any way to undo. What makes this command so dangerous is that it bypasses nearly all of the OS's soft protection mechanisms — the trash bin, write-protection prompts, secondary confirmations — and interacts directly with the kernel's file system layer. Although macOS introduced System Integrity Protection (SIP), SIP only protects system directories (such as /System and /usr) and offers no restrictions whatsoever on the user's home directory (~/). The real danger in the Agent era is this: the command no longer needs to be typed manually by a human — it's executed in milliseconds by an automated program with Full Access permissions, leaving the user virtually no time to react. The operating system's last line of defense designed for humans — "Are you really sure?" — fails completely in the face of automation.

What's truly worth discussing here is not "how could the model be so dumb," but a more engineering-oriented question: Why was a high-risk command able to cross permission boundaries, bypass approvals and sandboxes, and land directly on the real file system?

Many people who use AI to write code have had a similar experience: the first few lines look decent, but the further it goes, the more absurd it gets. You ask it to fix a bug, and it manages to bring down the entire project along the way. Most people's first instinct is to tweak the Prompt — adding a line like "You are a senior engineer" or "Think step by step." It helps a little, but not much. Because the root of the problem doesn't lie in the model itself.

A model is like a brilliant fresh graduate hacker: extremely intelligent, but lacking engineering common sense and working memory. Expecting it to single-handedly build an entire system from scratch is absurd in itself. Real engineers don't teach the AI "how to behave" — they build the AI a cage.

Harness Engineering: Putting Reins on the Beast

The industry has a concise formula: Agent = Model + Harness.

The Model is the large model, such as GPT-5.6 or Claude Opus. And Harness literally means "tack, gear" — the reins, blinders, and saddle placed on a horse. In the AI field, Harness refers to everything besides the model: tools, memory, guardrails, validation mechanisms, and orchestration logic. Harness Engineering is the discipline of designing this system.

It's worth mentioning that the concept of a Harness is not original to the AI field. In traditional software engineering, the Test Harness was widely used as early as the 1990s, referring to an automated testing framework used to drive the system under test in a controlled environment and collect results — the IEEE software engineering terminology standard has a clear definition for this. The core value of a Test Harness lies in isolation: it provides the system under test with a controlled, repeatable execution environment, shielding external dependencies (databases, networks, file systems) so that test results are predictable. The Agent Harness inherits this idea and generalizes it from testing scenarios to runtime scenarios — essentially, it's a Control Plane built around the LLM, separated from the data plane of model inference. This is highly similar to the design philosophy of the Service Mesh (such as Istio and Linkerd) in microservice architectures: a Service Mesh strips cross-cutting concerns like traffic management, security policies, and observability out of business logic, handling them uniformly through an independent infrastructure layer. What the Harness does for the LLM is exactly what the Service Mesh does for microservices.

Back to Matt Schumer's incident — the real problem was that the Agent had been granted broad file system permissions, but the destructive command was not intercepted by a sandbox, an approval gate, or path boundaries. Putting reins on a horse isn't meant to limit its speed, but to keep it running in the right direction; putting a Harness on the AI isn't meant to limit its creativity, but to ensure its output is safe, reliable, and maintainable.

Without getting this layer right, your Agent will always be a ticking time bomb ready to explode at any moment.

The Three Major Pain Points of Agents and Their Harness Solutions

Pain Point One: Context Congestion

The model itself does not persistently store cross-conversation state; it must be externalized by the Harness. If you cram all historical records into the context window, the salience of key constraints gets squeezed out.

There's a deep technical reason behind this. The core mechanism of the Transformer architecture — Self-Attention — can theoretically attend to any position in the input sequence, but in practice, there's a significant Positional Bias. The computational complexity of self-attention is O(n²), where n is the sequence length: when the context window expands from 4K to 128K or even longer, the proportion of ultra-long sequence samples the model encountered during training is far lower than that of short sequences, leading to a systematically weaker ability to model long-distance dependencies. The "Lost in the Middle" study published by Stanford University in 2023 confirmed that models pay significantly more attention to information located at the beginning and end of the context than to the middle — a phenomenon known as the "U-shaped attention curve," which has been reproduced across multiple mainstream models including GPT-3.5, GPT-4, and Claude. When the context is filled with large amounts of code and documentation, key architectural constraints often get pushed into the "middle zone" and effectively ignored — this isn't a matter of the model's intelligence, but a mathematical characteristic of the attention mechanism.

Some people dump the entire project's code, documentation, and requirements in, then ask the AI to "write me a feature," only to get output that completely fails to match the project architecture. The reason is simple: the context is too congested, and important architectural constraints are drowned out by the details.

The Harness approach is to outsource memory: using techniques like RAG (Retrieval-Augmented Generation), progress, file structures, and logs are stored in a structured way externally, letting the model "read" rather than "recall." This turns a recall problem into a retrieval problem, fundamentally circumventing the physical limitation of attention dilution. The essence of RAG is transferring vast knowledge from parametric memory (knowledge encoded in the model's weights) to external storage, and injecting context on demand via vector similarity retrieval, ensuring that what the model sees during each inference is the fragment of information most relevant to the current task. This architecture also brings a capability that traditional parametric memory cannot achieve: real-time knowledge updates. Once training is complete, parametric memory is frozen in the weights, whereas an external vector database can append, modify, or delete knowledge entries at any time, allowing the Agent to be aware of project changes that occurred after the training cutoff date.

Pain Point Two: Lack of Process Standards

The model may know how to do something, but it regenerates the workflow every single time, introducing enormous variance — steps get skipped, and stopping conditions get ignored.

An AI asked to write unit tests might write 100 tests the first time, 10 the second time, and simply skip them the third time. Because it's "inventing" how to write tests each time rather than following an established process.

The Harness approach is to make skills explicit: write operational steps as reusable instruction artifacts, so the model stops inventing workflows and starts following them. This is in line with the software engineering ideas of "Configuration as Code" and "Infrastructure as Code (IaC)" — transforming operational procedures that originally relied on human memory and word-of-mouth into version-controlled, auditable, and automatable text artifacts. For Agents, explicit workflows have an added value: they form the foundation of observability — when a workflow exists as a structured state machine or a Directed Acyclic Graph (DAG), the Harness can record execution state at each node, turning debugging and post-mortem review from "black-box guessing" into "white-box tracing."

Pain Point Three: Lack of Reliable Feedback

Let's make a simplifying assumption: a ten-step process, with each step at 99% accuracy and steps approximately independent, yields a final success rate of only about 90%. This is a classic problem of series systems in reliability engineering — overall reliability equals the product of the reliability of each stage. This model originates from hardware reliability engineering, systematized by Bell Labs in the 1950s to calculate the failure probability of complex systems like missiles and satellites. Its mathematical form is $R_{system} = \prod_{i=1}^{n} R_i$, which simplifies to $R^n$ when all components have the same reliability. When the number of steps increases to 20, even at 99% accuracy per step, the overall success rate drops below 82%; at 30 steps, it falls to 74%. This holds a profound lesson for Agent engineering: the marginal benefit of improving the model's single-step precision is far less than that of shortening the task chain and adding checkpoints. Each checkpoint is essentially a "reliability reset" — slicing a long chain into multiple independently validated short segments, so that accumulated errors are eliminated before they propagate to the next segment. This isn't a model problem; it's a math problem.

It's worth noting that the above 0.99^10 calculation relies on the assumption of "independent steps," whereas steps in real Agent task chains often have strong dependencies — an error in an upstream step not only affects that step but also cascades to contaminate the inputs of all downstream steps. This means the reliability decay curve in real-world scenarios is steeper than the mathematical model predicts, further reinforcing the necessity of checkpoint design. This cascading failure mode is isomorphic to the "Failure Propagation" problem in distributed systems, and is the fundamental motivation for introducing the Circuit Breaker pattern in microservice architectures — in Agent systems, checkpoints play exactly this circuit-breaker role.

The Harness approach is forced validation: as soon as the AI finishes writing code, it runs the tests; if the tests error out, the error messages are fed back to the AI so it can fix them itself, forming a closed loop. Don't trust the AI's verbal promises — only trust the green light of the test cases.

OpenAI's Practice: How 3 People Drove a Million Lines of Code

OpenAI ran an internal experiment: over 5 months, 3 engineers drove Codex to generate about 1 million lines of code in an empty repository, merging around 1,500 PRs — an average of 3.5 PRs per engineer per day. The humans didn't directly commit code, but were still responsible for goal decomposition, prompt constraint design, and feedback.

Their approach can be summarized in three points.

Give a Map, Not an Instruction Manual

At first, they wrote a massive agents.md, and the AI completely failed to grasp the key points. Later, they structured the knowledge base: agents.md kept only 100 lines as a table of contents, Architecture.md served as the top-level map, Design Docs held design decisions, Exact Plans held execution plans, and Product Specs held product requirements. Each layer is an independent, verifiable, maintainable unit, letting the AI operate step by step. This layered structure is no accident — it aligns closely with the classic Information Architecture principle in computer science: separating the navigation structure (table of contents) from the content body (documents), ensuring that the cognitive load at each layer stays within a manageable range. For the model, a 100-line table-of-contents file means higher information density and a lower risk of getting "lost in the middle."

This layered design also aligns with the Separation of Concerns (SoC) principle in software engineering: architectural decisions, design decisions, execution plans, and product requirements each evolve and are version-controlled independently, avoiding the maintenance nightmare where "changing anything in one giant document could affect the whole thing." When an Agent needs to understand the design intent of a certain module, it only needs to read the document at the corresponding layer, rather than extracting it itself from thousands of lines of jumbled text — this elevates the document's "Addressability" from something dependent on human experience to a mechanizable, structured query.

Expose Everything to the AI

They exposed the UI, logs, and metrics directly to Codex, letting the Agent view Chrome DevTools screenshots itself and query LogQL itself. Specifically, they enabled Codex to launch multiple independent instances of the application (one per Git worktree), operating the UI, querying logs, and querying metrics via the Chrome DevTools Protocol. The Chrome DevTools Protocol (CDP) is the low-level debugging interface exposed by the Chrome browser, supporting JavaScript execution, DOM manipulation, network monitoring, screenshots, and more — automation testing tools like Puppeteer and Playwright are all built on top of it. Incorporating CDP into the Agent toolchain means the Agent gains a "perceptual channel" nearly equivalent to what human developers have when debugging — it can not only read static code but also observe the program's dynamic behavior in a real runtime environment: whether network requests are sent as expected, whether DOM elements render correctly, and whether JavaScript exceptions are silently swallowed. This way, the AI can verify for itself whether a fix works, rather than blindly generating code — going from "blind men touching an elephant" to having true engineering eyesight.

Git worktree is an advanced Git feature that allows the same repository to simultaneously maintain multiple working directories at different paths in the file system, with each directory able to switch to a different branch or commit while sharing the same .git object store. This provides a natural isolation unit for parallel Agent tasks: each Agent instance has its own independent workspace and can advance different fix approaches simultaneously without interfering with one another — effectively implementing Agent-level "experimental branches" at the file system layer.

Permission Approval and Isolation

This is the most critical point. A Harness is typically built on top of CI/CD, static analysis, and permission systems, adding feedback that the Agent can read, execute, and self-correct.

The core is the Principle of Least Privilege (PoLP): this principle was formally proposed by Jerome Saltzer in a 1974 computer security paper and is a cornerstone tenet of the information security field, later incorporated into the U.S. Department of Defense's Trusted Computer System Evaluation Criteria (TCSEC, commonly known as the "Orange Book"). Its core idea is that any program or process should only have the minimum set of permissions necessary to complete its current task. Applying PoLP to AI Agents presents new challenges that traditional systems never faced: the permission requirements of traditional programs can be statically analyzed and determined at the design stage, whereas an Agent's "intent" is dynamically generated by the LLM at runtime — you cannot enumerate in advance all the resources an open-goal Agent might need to access. Solutions include: dynamic permission requests (the Agent declares required permissions before execution, which the Harness approves in real time), Docker container or WebAssembly sandbox isolation (restricting file system and network access scope at the OS level), and operation audit logs (recording all tool invocations for later traceability). Together, these three form the Defense in Depth system for Agent security. In practical terms: the AI should not have global file system access — it can only operate on specific directories and file types; dangerous operations should be intercepted or require approval. This isn't a replacement for CI/CD, but rather turning existing engineering controls into a closed loop the Agent can consume.

CI/CD (Continuous Integration/Continuous Delivery) plays a key role here. The concept of continuous integration was proposed by Kent Beck in the Extreme Programming (XP) methodology, and Martin Fowler systematized it in 2000: developers frequently merge code into the main branch, and each merge triggers automated builds and tests, transforming integration risk from a "big bang" periodic event into continuous, manageable incremental feedback. Traditional CI/CD pipelines were originally designed to provide fast feedback to human engineers, with results presented as Pass/Fail on the Pull Request page. The Agent Harness fundamentally reengineers this mechanism: the consumer of the feedback shifts from humans to the model itself — this requires the feedback information to be output in a structured, machine-readable format (JSON, SARIF, etc.), and error messages need to contain sufficient context (file paths, line numbers, stack traces, relevant variable values) so the model can pinpoint the issue accurately and generate an effective fix. This is an engineering transformation from a "dashboard for humans to look at" to "sensor data for the AI to read," and its core challenge is: human engineers can infer root causes from vague error messages based on experience, whereas the model needs explicit, complete context to achieve the same level of reasoning. SARIF (Static Analysis Results Interchange Format) is a static analysis result exchange format led by Microsoft and standardized by OASIS, and it is gradually becoming the universal protocol for delivering code scan results in machine-readable form to toolchains (including AI Agents).

A Cognitive Inversion: Designing Software Engineering for Agents

You might think: isn't this just wrapping traditional CI/CD around the AI? Not entirely. Traditional CI/CD is for humans to look at, whereas a Harness is for both the AI and humans — this is a massive cognitive inversion.

Our current codebases and documentation are designed for human readability. But in an Agent-first world, systems must be designed for Agent readability. Any knowledge that an Agent cannot directly access in its context — like a discussion in Slack, or an architectural decision in your head — simply doesn't exist as far as the Agent is concerned. If you don't make this implicit knowledge explicit by writing it into the Harness, the AI will never understand your intent.

The concept of Agent-first software engineering closely parallels the many paradigm shifts in the history of programming languages. From punch cards to machine code, from machine code to assembly (introducing symbolic abstraction), from procedural to object-oriented (OOP, encapsulating data and behavior as objects that map to humans' cognitive model of the real world), from monolithic architectures to microservices (splitting a single deployment unit into independently scalable services) — the essence of each shift is raising the level of abstraction and changing the collaboration interface between humans and machines, allowing humans to express intent in a way closer to the problem domain than to the machine domain. What makes the Agent-first paradigm unique is that, for the first time, it requires the codebase to serve two types of readers simultaneously — human engineers and AI systems. These two types of readers have entirely different cognitive characteristics: humans excel at inferring intent from metaphor, convention, and context, while AI needs explicit, complete, structured information. This gives rise to new standards for code readability: module boundaries must be clear (so the AI can handle a single module independently without needing to understand the entire system), interfaces must be self-describing (so the AI can understand the calling intent through function signatures, type annotations, and documentation comments), and side effects must be isolated (so the AI can safely invoke them in a test environment without triggering production impact). Some cutting-edge teams have already made "AI comprehensibility" one of the explicit criteria in code review, on par with "human readability."

This shift places specific demands on existing engineering practices. The value of type systems is being reassessed: the richer typing of TypeScript over JavaScript, or Rust over C, is no longer merely a tool for "preventing human errors" — it's a signaling system that provides precise semantics to the AI. Complete type annotations are equivalent to attaching a machine-readable usage contract to every function interface. Comment culture is also being reshaped: traditionally, comments were written for the next maintainer to read, but under the Agent-first paradigm, comments are simultaneously context supplements written for the AI — explaining "why this was done (Why)" is more valuable than explaining "what was done (What)," because the AI can usually infer the latter from the code itself, whereas the former involves business context and historical decisions, which is precisely the information the AI is most likely to lack.

In the AI era, code is not only written for machines to execute, but also for another AI to read, understand, and modify. This is what's known as Agent-first software engineering.

The engineer's role changes accordingly: previously you were the person writing the code; now you are the person designing the environment. You no longer hand-write business logic — you write guardrails, feedback loops, and constraints, transforming from a bricklayer into a shepherd. You don't need to tell the sheep how to take every step; you just build the fence and lay out the feed, and let the sheep graze on their own.

This also explains why the same GPT-5.6 can only write simple scripts in some hands, yet can architect complex enterprise-grade applications in others. The gap isn't in the model — it's in the Harness.

Conclusion

Don't expect to solve Agent reliability problems just by swapping in a different model — system design will always outweigh model capability. Harness Engineering isn't some black magic; it's solid engineering practice: outsource memory, make skills explicit, force validation, isolate permissions, and design for Agents.

In production-grade Agents, system design is often just as important as model capability. Some repetitive coding work may be compressed, but work like architectural design, system integration, and Harness construction will actually increase. The standard for judging an engineer's skill level may no longer be their speed at solving coding problems, but whether they can build a Harness robust enough to make even the most ordinary model perform at an expert level.

Key Takeaways

Key Takeaways

Key Takeaways