lopopolo/harness-engineering: an agent context bundle for shaping agent output

The problem harness-engineering names: process data that never reaches the model

The README makes a specific claim about why agent output disappoints. General model weights, it argues, contain only the visible tip of an organization's process-data iceberg. Below the waterline sit the current operational state, the local ontology, the quality bar, procedures, exception history and authority relationships. The repository's position is that organizations cannot presume this private, changing process data will be present in general model weights, nor that agents will reliably intuit which of it matters.

Harness engineering is the name the repository gives to the last-mile work of making that data available to a capable worker as context and tools. The definition is deliberately narrow: hold a chosen model and coding agent constant as a black box, and improve the two external levers, context and tools. That framing is what separates the repository from prompt-tuning advice. It is written for people who deploy agents against a real system and who own the nonfunctional requirements (reliability, security, compatibility, maintainability, performance, operability, risk posture, polish) that the environment has to carry.

The README also states the intended worker capabilities plainly: recover intent, operate the real system, respect authority, prove the outcome, and leave the next run better equipped. Those five are a checklist for judging a harness, and they are more useful than a definition because each one names something you can inspect in your own setup.

How the repository is put together: AGENTS.md routes, docs argue, playbooks apply

The mechanism is file routing rather than code execution. The README instructs the reader to point a coding agent at the repository alongside the system it should improve, and states that AGENTS.md routes the task to the relevant arguments, cases and proof. For direct reading it points to the thesis index under docs/, and for an application it points to playbooks/.

The top-level layout matches that description: AGENTS.md, ARCHITECTURE.md, CLAUDE.md, README.md, COPYING.md, LICENSE, plus assets/, docs/, evals/, playbooks/ and sources/. Two agent-context files (AGENTS.md for the AGENTS.md convention and CLAUDE.md for Claude Code) sit next to an ARCHITECTURE.md, which suggests the repository is meant to be consumed by an agent that reads the architecture before acting. The evals/ directory exists, but the README does not describe what is evaluated or how to run anything in it, so treat it as an unverified area until you open it.

The argument structure lives in docs/. The README links to docs/domain-modeling/#make-nonfunctional-requirements-recoverable for the claim that requirements and decisions become retrievable context, examples, tools and executable constraints, to docs/durable-systems/#make-coherence-cumulative for the feedback-loop claim, to docs/last-mile-deployment/ for the deployment argument, and to docs/lineage/ for influences and alternate framings. Sources are collected under sources/, including a fetch helper at sources/scripts/fetch_openai.py for agents blocked by the canonical OpenAI page. That fetch helper is the closest thing to executable code the README documents.

Installing the context bundle and pointing an agent at it

There is no package to install. The README gives no pip, npm or cargo command, and no release artifact is described as installable. The practical setup is to clone the repository and let an agent read it, exactly as the README describes: point a coding agent at this repository alongside the system it should improve.

Clone the default branch, which is trunk.

git clone https://github.com/lopopolo/harness-engineering.git
cd harness-engineering

If your agent is blocked from fetching the canonical OpenAI page referenced in the README, the repository ships a fetch helper under sources/scripts/.

python sources/scripts/fetch_openai.py

The README does not document the helper's arguments or output, so run it in a scratch directory and read the script before wiring it into anything. For a first real use, open the agent in the repository root and ask it to route a task through AGENTS.md, then read the linked docs and playbooks yourself. The README's own entry points are the thesis index in docs/ for direct reading and playbooks/ when you want to apply the ideas. If you are working in Claude Code, CLAUDE.md at the root is the file that context expects.

What you do not get: no runtime, no benchmarks, no rollback story

This is an anthology and a field guide, not a framework. The README describes no API, no daemon, no configuration schema and no runtime that enforces anything. If you want a library that intercepts tool calls, validates outputs or records trajectories, this repository does not provide one, and nothing in the README suggests it intends to.

The evals/ directory is the strongest hint that some verification exists, but the README is silent on what is measured, what the pass criteria are and how to reproduce a run. That silence matters: a repository arguing for executable constraints should make its own constraints runnable, and here the argument is carried by prose. The README also does not document rollback, versioning policy or how docs/ and playbooks/ are expected to change between releases.

There is a second limitation in the framing itself. Holding the model and coding agent constant as a black box is a useful discipline for isolating what context and tools contribute, but it means the repository has nothing to say when the right fix is a different model, a smaller context window budget or a different agent runtime. If your problem is model capability, this is the wrong tool, and the README would agree by construction.

Harness engineering vs context engineering, and why the distinction is load-bearing

The related searches show people asking how harness engineering differs from context engineering and from loop engineering. The README draws the line at scope. Context engineering is one of the two levers; harness engineering is the practice of curating the environment around both levers, context and tools, while treating the worker as fixed. The repository's own summary is that a central purpose of that environment is to carry an organization's nonfunctional requirements and the local decisions about how to prioritize and satisfy them.

A concrete comparison makes the difference visible. A context-engineering approach to a failing agent asks what to put in the prompt: examples, retrieved documents, a better system message. A harness-engineering approach asks what the agent can operate, what it is allowed to do, and how it proves the outcome, then encodes those as tools, boundaries and checks. The README's phrase for this is getting the whole universe of nonfunctional requirements into code, adopted from a systems-level framing it attributes to the 2026 [un]prompted conference.

The loop-engineering comparison is less developed. The README does say that work is an iterative game and that lessons from accepted work, corrections, failures and user responses become context, boundaries, tools, examples and checks that shape later trajectories. That is a feedback-loop claim, but the README does not define how it differs from loop engineering, so anyone arriving with that question should read docs/durable-systems/ rather than expect an answer in the README.

Licence and the cost of keeping the bundle current

Repository-authored material is licensed under CC BY 4.0, and the README points to COPYING.md for attribution and rights in source material. That split is the part to read carefully. An anthology that quotes and links external writing cannot relicense that writing, so the boundary between repository-authored prose and third-party sources determines what you may reuse, adapt or redistribute. This is a description of the licence terms, not legal advice; read COPYING.md and LICENSE before republishing anything.

CC BY 4.0 is a content licence, not a software licence, which fits a repository whose deliverable is prose and routing files. If your organization's policy only approves permissive software licences for dependencies, this repository is not a dependency in that sense, but a copied or vendored copy of its text still carries attribution requirements.

The upgrade cost is the maintenance question. The last push was on 2026-07-18, and v1.0.0 was released the same day. The release history shows a single tagged version. Because the deliverable is argumentative prose plus agent-context files, an upgrade is not a dependency bump: AGENTS.md and CLAUDE.md are read by your agent on every task, so any change to them changes agent behaviour. Pin a commit if you route production work through these files, and review diffs to AGENTS.md the way you would review a prompt change.

Editorial conclusion

Adopt this repository if you already run a coding agent against a real system and want a vocabulary plus routing files for the context and tools around it. Do not adopt it if you need a library, a CLI or a benchmark: the repository is prose, playbooks and sources, and the README gives no installable package. Before relying on it, verify that AGENTS.md routes to the docs and playbooks you actually need, and check COPYING.md for which files are repository-authored under CC BY 4.0 and which are third-party source material.

Frequently asked questions

Official sources

1. License: CC-BY-4.0
2. lopopolo/harness-engineering on GitHub
3. Project website
4. README
5. Releases