Give a skilled carpenter a clear drawing and nothing else, and you still will not get a good cabinet. They need a workbench, the right tools, measurements they can trust, a safe place to cut, and someone to inspect the joints before the cabinet is fitted in a client’s kitchen. The drawing supplies direction. The workshop is what lets the work happen well.
A coding agent is the same. The first four parts of this series were about the drawing: what a specification is, what it should contain and how intent flows down to one task. None of that stops an agent from running a command against the wrong database, importing a module it should never touch, or reporting “done” on a change that has not been tested. Those problems are solved by the environment around the agent, which is now commonly called the harness.
We are following one fictional organisation through this series. Kestrel Mutual is fictional, and all figures are illustrative. Kestrel is a South African insurer whose engineers use coding agents to build assisted account recovery (SPEC-017), a fraud-sensitive feature that lets customers who have lost their registered mobile number get back into the portal.
The spec supplies direction. The harness supplies controlled execution.
What “harness engineering” means, and what it does not
Harness engineering is the work of engineering the repository knowledge, tools, permissions, tests, sandboxes and feedback loops that let coding agents work reliably. You will also see people say “harness-driven development”. That is loose usage rather than a defined method, and there is no standards body behind either term. When your team adopts the vocabulary, define it in your own operating model. And it has nothing to do with Harness, the software delivery company.
The term gained wide attention in February 2026, when OpenAI published a write-up on harness engineering describing a team that built a product over roughly five months with its Codex agent writing the code rather than engineers typing it. Several ideas from that account, also discussed in commentary by Birgitta Böckeler on martinfowler.com, have become reference points:
- The repository is the system of record. What the agent cannot see in its context effectively does not exist, so decisions, plans and documentation live in the repo rather than in chat threads and wikis.
- A short instruction file is a map, not an encyclopaedia. A brief
AGENTS.mdpoints to deeper documentation instead of trying to hold everything. - Architecture is enforced mechanically. Boundaries are checked by custom linters and structural tests, not by hoping reviewers notice.
- Drift is cleaned up continuously. Background agent tasks periodically find and fix accumulated inconsistencies, a kind of garbage collection for the codebase.
Böckeler’s April 2026 piece, “Harness engineering for coding agent users”, frames the harness as guides that steer the agent before it acts and sensors that give it feedback afterwards, each either computational (deterministic, like a test) or inferential (model-based, like an AI reviewer). Chris Ford’s taxonomy of guides, guards, checks and sensors, which we covered in our earlier article on the coding agent harness, cuts the same space slightly differently. The frameworks agree on the essential point: most failures of coding agents in real codebases are failures of the environment, not of the model.
The harness around one change
At Kestrel, an engineer picks up TASK-017-04: add the adapter that creates a fraud case when a high-risk recovery attempt is blocked. Here is what surrounds the agent that does the work.
The agent receives three kinds of input: the approved spec and task, the repository knowledge (instructions, ADRs, contracts, glossary) and tools inside a sandbox, with permissions that limit what it can reach. It proposes a change. The change goes through deterministic verification: checks that give the same answer every time, such as tests and linters. If verification fails, a useful error message goes back to the agent, which tries again. If it passes, a person reviews and merges. Throughout, observability records what the agent did, what failed, how many tokens it used and how long it took, so the reviewer can see how the change was produced as well as what it contains.
Notice where the human sits. Not in the loop of every retry, which would waste a person’s time on problems a test can catch, but at the point where judgement is needed: is this the right change, and is it safe to merge?
The components of a harness
| Component | Purpose | At Kestrel |
|---|---|---|
| Repository instructions | Commands, conventions, boundaries and the definition of done | A short AGENTS.md that links to ADR-024 and the test command |
| Context retrieval | Relevant files and intent without flooding the agent | The task links SPEC-017’s high-risk scenario, not the whole spec library |
| Sandboxed execution | Isolate work and limit damage | Agents run in disposable containers with no production access |
| Tool permissions | Restrict writes, secrets, network and production | No customer data, no production credentials, no outbound calls except package mirrors |
| Tests and linters | Fast, deterministic local feedback | Unit and contract tests run in minutes |
| Architecture checks | Prevent prohibited dependencies | A rule fails the build if portal code calls the risk engine directly |
| Security scanning | Detect secrets, vulnerable dependencies and unsafe patterns | Secret scanning and dependency checks on every change |
| Worktree isolation | Parallel work without overwriting | Each agent task gets its own branch and working copy |
| Checkpointing | Preserve state on long-running work | Progress notes committed as the task advances |
| Observability | Record actions, failures, tokens and duration | Every agent run is logged against its task ID |
| Review gates | Human approval according to risk | Merge needs a named reviewer; recovery code paths also need the spec folder’s owners |
A few terms. A sandbox is an isolated environment where the agent can run code without being able to affect anything outside it. A worktree is a separate working copy of the same repository, so two agents can work on different branches at once without overwriting each other’s files. A linter is a tool that checks code against rules without running it.
The architecture check deserves attention because it turns a document into a guardrail. ADR-024 says identity decisions remain in the identity domain. Written only in prose, that rule depends on every reviewer remembering it. Written as a dependency rule that fails the build when portal code imports the risk engine’s client, it is enforced on every change, by a machine, for every engineer and every agent, including the ones who never read the ADR.
Kestrel’s sandbox rules also carry a South African obligation. Test fixtures use synthetic identity numbers and made-up policyholders, never copies of real customer records. POPIA requires appropriate safeguards for personal information, and a coding agent session is not a place customer data belongs.
An agent-legible repository
A repository that is hard for a new engineer to work in is harder still for an agent, which cannot lean over and ask a colleague. The practical test is whether routine work requires tribal knowledge. An agent-legible repository has:
- one reliable setup command;
- one clear test command;
- documented ownership and boundaries;
- useful failure messages that say what went wrong and where;
- small, navigable modules;
- fixtures and test data;
- current architecture views;
- discoverable schemas and contracts;
- explicit handling of secrets and environments;
- no tribal knowledge for routine work.
Almost every item on that list also makes human engineers faster. Useful failure messages are a good example. An agent that sees “test failed” will guess. An agent that sees “cooling-off period expected 72 hours, got 48” will fix the right line. So will a tired engineer at four in the afternoon.
The verification ladder
Not every check is equally cheap. A formatting check takes seconds; a performance test can take an hour and an environment. So it helps to think of verification as a ladder, from the fastest and cheapest feedback at the bottom to the slowest and most expensive at the top:
- Formatting and static analysis.
- Focused unit tests.
- Contract tests, which confirm a component still honours the agreed interface.
- Integration tests, which check components working together.
- Security and policy checks.
- Build and packaging.
- End-to-end scenarios, which exercise a whole user journey.
- Performance and resilience testing.
- Human product, architecture or risk approval.
This is an ordering by cost and speed of feedback, not a sequence every change must climb. The cheap automated rungs run on everything, because they cost almost nothing. How far up the ladder a change must go depends on its risk.
Kestrel uses four risk tiers, the same ones Part 8 sets out for governance. A copy change on the help page is low risk. A new filter on the claims history screen is medium. A change to a public API or anything touching personal data is high. Assisted recovery is critical, because a mistake can hand a fraudster control of a policyholder’s account and banking details. Critical changes climb every rung and add independent validation, a staged release and proof that the service can be restored after a failure.
One rule matters more than the ladder itself: an agent does not decide its own risk tier. The tier comes from policy, based on what the change touches, and a person confirms it.
Spec and harness need each other
It is tempting to treat these as alternatives, and teams tend to over-invest in whichever one matches their culture. Architects write beautiful specs and run them through a weak pipeline. Platform teams build superb pipelines and feed them one-line tickets. Both fail, in different ways.
| Without a good spec | Without a good harness |
|---|---|
| The agent builds the wrong thing quickly | The agent cannot prove a correct change |
| Scope expands | Feedback is slow |
| Acceptance is subjective | Permissions increase risk |
| Decisions disappear in chat | Parallel agents conflict |
The quadrant to fear most is the bottom right: a weak spec and a strong harness. Everything is green. The adapter passes every test, every linter and every scan. But suppose SPEC-017’s first version had never said that high-risk attempts must not reset automatically. Nobody would have written a test for it, and the harness would have efficiently verified the wrong behaviour. A strong harness makes a team confident. It cannot make the goal correct.
The spec controls meaning. The harness controls execution.
Where to start
For most teams, the harness already exists in pieces: a CI pipeline, some tests, a linter, a code review rule. The work is to make those pieces agent-ready and close the gaps that matter most. Kestrel’s platform team started with four things, in this order:
- Permissions first. Agents get no production credentials and no customer data, before anything else is automated.
- One setup command and one test command that work every time, with failure messages worth reading.
- One architecture rule enforced in the build, the ADR-024 boundary, to prove that documents can become checks.
- A short
AGENTS.mdthat links to the domain glossary, ADRs and specs rather than repeating them.
None of those require a new product. They require a platform team that treats the agent as a developer whose experience matters. Our article on platform engineering in the citizen and agent era covers the paved road that makes this reusable across teams.
What to take from this part
A harness is the environment around the agent. Instructions, tools, sandboxes, permissions, checks, observability and review gates, engineered on purpose.
Turn important rules into mechanical checks. An ADR enforced by the build protects every change; an ADR in a folder protects only the changes whose reviewers remember it.
Climb the verification ladder according to risk. Cheap checks run on everything; expensive ones and human approval scale with what the change could break.
Never let an agent set its own risk tier. Policy decides the tier, and a person confirms it.
A strong harness cannot rescue a wrong goal. Spec and harness fail differently, and you need both.
Next in the series: AI changes responsibilities, not accountability: team structures for SDD.
How CloudNala can help
We assess the harness a team already has, from permissions and sandboxing to test feedback, architecture checks and review gates, and identify the few gaps that most limit safe agent use. We then help the platform team close them in order, starting with access and ending with the checks that turn written decisions into enforced ones.
Work with CloudNala
CloudNala helps organisations move from technology ambition to practical execution across cloud, AI, data, platform engineering and digital services.
Whether you are exploring AI, modernising your cloud environment, building a public-sector digital service, or turning an idea into a working MVP, we can help you shape the roadmap and deliver the next step.
Plan an SDD Pilot or write to us at consult@cloudnala.co.za