Harness engineering: guides and sensors

A coding agent is a model plus everything around it. You can't change the model, but you can change everything around it: what steers the agent before it writes, and what catches its mistakes after. Thoughtworks calls this the agent's harness. This module shows how to build one that makes the agent correct itself, and how to improve it every time a mistake repeats. It works the same way in any coding agent.

1. The idea

Birgitta Böckeler (Thoughtworks) defines the harness as "everything in an AI agent except the model itself". The coding agent comes with a built-in harness (its tools, its loop, its prompts). Harness engineering is the part you add for your codebase, and it has two kinds of control:

• Guides (feedforward) steer the agent before it acts, so the first attempt is more likely to be right.
• Sensors (feedback) observe after it acts, so the agent can correct itself before a person looks.

Each can be computational (deterministic code: fast, cheap, always gives the same answer) or inferential (another model's judgement: slower, costs tokens, can vary, but understands meaning).

You need both kinds. Böckeler's point: with only sensors, the agent keeps repeating the same mistakes; with only guides, you write rules and never find out whether they were followed.

2. How it works

The last step is what makes a harness get better over time. Thoughtworks calls it the feedback flywheel: treat recurring agent mistakes like a retrospective, and fix the harness instead of correcting the agent by hand again. Follow one recurring mistake:

Agent-written tests have their own trap: they can be "perpetually green", passing whatever the code does because they assert too little. Coverage can't see this; mutation testing can. It makes small deliberate bugs ("mutants") in the code and checks that some test fails for each one.

3. Try it yourself

Which control fixes this?

Each line is a problem that keeps happening. Pick the control that fixes it best, then check.

Trim this AGENTS.md

This file grew for a year and now the agent ignores half of it. For each line: keep it, turn it into a sensor (a check that enforces it), move it into a skill (loaded only when relevant), or delete it.

4. Why it matters at work

Thoughtworks' April 2026 Technology Radar made this its theme "Putting coding agents on a leash", warning that as agents improve, people are tempted to step out of the loop. Where the related practices stand:

Where each sensor runs

Fast sensors go as early as possible; slow ones later. Böckeler's lifecycle:

The portable setup

One check script, called from everywhere. Any agent can run it, a git hook runs it whoever commits, and CI runs it again.

#!/usr/bin/env bash
# scripts/check: the fast sensors, in one place. Exit non-zero on any failure.
set -euo pipefail
npx tsc --noEmit            # types
npx eslint . --max-warnings 0   # lint, including architecture rules
npx vitest run --changed    # tests for what changed

# AGENTS.md: the guide that points at the sensor (short, so it isn't lost)
Before you say a task is done, run ./scripts/check and fix every failure.
Never edit eslint.config.js, the tests' assertions or CI files to make a check pass.

// eslint.config.js: a sensor whose message tells the agent how to fix it
rules: {
  "no-restricted-imports": ["error", { patterns: [{
    group: ["**/infra/**"],
    message: "Domain code can't import infra. Depend on the port in domain/ports/ and inject it (see docs/architecture.md#ports).",
  }] }],
}

1. Git pre-commit hook runs scripts/check: works with all five tools, because it runs whoever (or whatever) commits.
2. The agent's own hook (Module 12) runs the fast part after every edit, so mistakes are fixed in the session. Where each tool keeps it is in section 5.
3. CI runs scripts/check again, plus mutation testing on core logic and the AI review from Module 13a.

5. In your five tools

Guides are portable (AGENTS.md and the SKILL.md format work everywhere); sensors in the session use each tool's hooks. Checked October 2026; see Modules 09, 11 and 12 for details.

The git pre-commit hook and CI catch everything the in-session hooks miss, for every tool.

6. Remember it

7. Common mistakes

8. Hands-on lab (roadmap week 12)

1. Collect the repeats: list three review comments you've made on agent code more than once.
2. Write the check script: types, lint and fast tests in scripts/check; point AGENTS.md at it in one line.
3. Turn one repeat into a sensor: a lint rule or structural test whose message says how to fix it. Ask an agent to make the mistake on purpose and watch it correct itself.
4. Wire it in: a git pre-commit hook for every tool, plus the after-edit hook in tool A.
5. Run mutation testing (Stryker, Pitest, mutmut or cargo-mutants) on one core module the agent wrote tests for. Add tests until the important mutants are killed.
6. Trim AGENTS.md: remove or move every line that a sensor now enforces or only one task needs. Compare its length before and after.

9. Self-check quiz

10. Go deeper