The Repo Harness

There are at least three distinct layers an agent operates through: the model, the model's harness (partly influenced by local config), and the repository harness. The repo harness is an extension of the model's harness which is entirely within the developer's control. The repo harness can be split into two further categories which are static and dynamic resources.

The three layers

The model is the LLM, the weights and training run by the company releasing the model.

The model's harness is the coding agent built around the model. These agents are fine tuned for coding tasks, with built-in prompts curated for searching, running, and testing codebases. There is some configuration typically available to a user, for example tweaking the model's "effort" level. This configuration blurs the lines between a model harness and a repo harness by introducing an area which the agent runner's environment can influence.

The repo harness is the set of resources available to an agent when they interact with that repo. The resources can be split into two categories: static and dynamic. Static resources are the files, the content of the files, the structure of the app, and other conceptual details. Dynamic resources are the resources that an agent can access or generate when running the app, for example logging or json responses from an endpoint.

Why this matters

Agents are expected to complete virtually all programming tasks and therefore it is in the interest of those responsible for producing features to have the best possible environment for the agents to act in.

The repo harness is essentially the repository itself; every file has the potential to be read (or missed) and influence the decision making of the agent.

The static layer is important for planning and implementation; it affects how an agent discovers components and related features. There is also a hierarchy of importance: a code file is not as influential as the root CLAUDE.md file, and a component's directory and file structure is not as important as the structure of the root directory.

The dynamic layer is important for validation; it affects the ability of the agent to test changes. Claude provides in-built skills like /verify (docs) which can invoke custom-built skills tailored towards known testing and validation steps for a repo.

But ultimately good repo health, like structure and developer experience, compounds for both humans and agents.

The easier it is to navigate, run, and interact with an app the more effective a human or agent will be when completing tasks.