The Harness Is the Machine: Seven Invariants for Agent Engineering

Most people respond to a failing agent by changing the prompt

Then they change the model

Then they add a larger context window

The agent still forgets decisions

It still uses the wrong tool

It still skips verification.

It still gets stuck in the same loop

The problem is not the intelligence of Claude Opus 5.5

The problem is the environment around it

That environment is the harness

And designing it is harness engineering

The model is only the engine

The harness is the machine

Run it in a standard chat window:

It produces plausible-looking code that ignores schema invariants

It attempts to modify 14 files at once, exhausts its token window midway, and leaves the workspace half-broken

It confidently asserts: "All tests passed successfully," without ever executing a test runner

Total task completion rate on complex multi-file refactoring: 18%

Now run the exact same Claude Sonnet 5.5 inside a disciplined engineering harness:

The input contract enforces path bounds and deterministic acceptance criteria before token 1 is generated

Actions execute in isolated git worktrees, physically segregated from the working branch

Static typecheckers, linters, and compiler hooks intercept syntax errors before files are written to disk

Adversarial review by Claude Opus 5.5 in a cold context inspects raw git diffs and test receipts before commit

Total task completion rate on the identical refactoring: 89%

The difference is zero parameters, zero fine-tuning, and zero prompt adjectives. The difference is substrate design

Every robust production harness executes seven non-negotiable architectural responsibilities:

+---------------+-----------------------------+-------------------------------+------------------------------+
| PHASE         | HARNESS INVARIANT           | INFRASTRUCTURE IMPLEMENTATION | FAILURE MODE WITHOUT HARNESS |
+---------------+-----------------------------+-------------------------------+------------------------------+
| 01 / CONTRACT | Bounded scope before tok 1  | Contract spec, turn ceiling   | Unbounded repo wandering     |
| 02 / CONTEXT  | Surgical AST slice          | Symbol resolver, path rules   | Context overflow & drift     |
| 03 / TOOLS    | Isolated write operations   | Git worktrees, sandboxes      | Dirty writes & broken tree   |
| 04 / STATE    | Durable disk-backed memory  | receipt.md checkpoints        | Catastrophic state loss      |
| 05 / SENSORS  | Zero trust in model claims  | Compiler stdout (pyright)     | Hallucinated test passes     |
| 06 / POLICY   | Blast radius boundaries     | Stripped network & secrets    | Token leaks & bad deletes    |
| 07 / TRACES   | Forensic audit trace        | diff manifest, dollar audit   | Unauditable chat noise       |
+---------------+-----------------------------+-------------------------------+------------------------------+

1. DEFINE (Contract)

Core Purpose: Bound the scope before generating token 1

Architectural Invariant: The contract enforces explicit target file lists, deterministic exit conditions, and an iteration ceiling

Harness Implementation: The harness rejects unconstrained requests. If an agent attempts to write outside designated paths, the tool sandbox denies filesystem access

Failure Mode Without Harness: The model wanders into neighboring packages, consumes 80,000 tokens on recursive file search, and edits unrelated utilities

2. SELECT (Context)

Core Purpose: Provide a high-fidelity topological map rather than a raw dump

Architectural Invariant: The context window receives only AST symbol signatures, import hierarchies, and localized path policies

Harness Implementation: Dynamic scoping via .claude/rules. System instructions are capped at 150 lines

Failure Mode Without Harness: A 3,000-line source file is dumped into the prompt. By step 15, the model forgets initial invariants and generates broken interfaces

3. ACT (Tools)

Core Purpose: Quarantine all destructive actions

Architectural Invariant: The model never writes directly to the primary checkout or main branch

Harness Implementation: Every task executes inside an ephemeral git worktree:

git worktree add -b patch/task-482 .worktrees/patch-482 HEAD

Commands run under an explicit whitelist of approved system binaries

Failure Mode Without Harness: The model clobbers user work, introduces merge conflicts, or alters host configurations

4. REMEMBER (State)

Core Purpose: Externalize cognitive state to durable storage

Architectural Invariant: Progress is materialized directly on disk

Harness Implementation: Every verified checkpoint writes an immutable receipt.md. If a connection drops, the subsequent run resumes seamlessly from disk state

Failure Mode Without Harness: A broken socket drops 40 minutes of agent reasoning, requiring a full restart

5. VERIFY (Sensors)

Core Purpose: Evaluate verifiable evidence, not conversational prose

Architectural Invariant: No diff is merged without automated sensor validation returning exit code 0

Harness Implementation: The sensor pipeline automatically executes: AST syntax parsing

Strict typechecking (pyright or tsc --noEmit)

Bounded unit test execution

Failure Mode Without Harness: The model encounters a syntax error internally but assures the user that "everything is working smoothly."

6. AUTHORIZE (Policy)

Core Purpose: Enforce blast-radius control outside token generation

Architectural Invariant: High-risk actions require cryptographic tokens or human confirmation

Harness Implementation: Production credentials and raw API secrets are stripped from execution containers. Socket egress is locked at the OS kernel level

Failure Mode Without Harness: The model invokes curl to unauthorized external endpoints or logs secret credentials

7. EXPLAIN (Traces)

Core Purpose: Guarantee forensic auditability for every automated change

Architectural Invariant: Every commit carries a machine-readable audit receipt

Harness Implementation: Comprehensive recording of token budgets, dollar costs, starting commit SHAs, and raw sensor outputs

Failure Mode Without Harness: Cryptic commits with vague messages like "fix bug" that break CI unnoticed weeks later

Axiom: One model call is just an event. The harness is the system

The most pervasive anti-pattern in AI engineering is writing behavioral rules in natural language prompts:

"Please do not touch files outside src/components"

"Remember to format code with Prettier"

"Ensure you do not delete type definitions"

This is cargo-cult engineering. A probabilistic model under token pressure will eventually ignore soft instructions

In a mature harness, instructions are compiled into deterministic infrastructure

Step 1: Path-Scoped Rules (.claude/rules)

Instead of bloated system prompts, rules attach exclusively to target paths:

# .claude/rules
contracts:
  - path: "src/auth/**"
    rules:
      - "Never expose raw tokens in error logs"
      - "All session mutations must acquire Redis lock"
    sensors:
      - "npm run test:auth"
      - "npm run typecheck"

Step 2: Deterministic Pre-Commit Compiler Hook (.claude/hooks/pre-verify.sh)

Never ask the model to run tests voluntarily. The harness intercepts tool writes automatically:

#!/usr/bin/env bash
set -euo pipefail

echo "=== SENSOR SUITE EXECUTION ==="

# 1. Static AST type verification
pyright src/auth/session.py || {
  echo "SENSOR FAILED: Type invariants violated. Patch rejected."
  git restore .
  exit 1
}

# 2. Hermetic unit suite with strict timeout
pytest tests/auth/ -q --timeout=10 || {
  echo "SENSOR FAILED: Regression detected in auth suite."
  git restore .
  exit 2
}

echo "=== SENSORS PASSED: PROCEEDING TO AUDIT ==="

Rule: Rules belong in compilers, linters, and OS permissions, not in English prose

Never let a single agent serve as architect, builder, auditor, and archivist simultaneously

Doing so guarantees cognitive contamination: the model falls in love with its own flawed diffs

A frontier architecture separates responsibilities across three distinct planes:

┌────────────────────────────────────────────────────────┐
│               THE COGNITIVE ARCHITECTURE               │
├─────────────────────────┬──────────────────────────────┤
│ 1. THE HANDS (Worker)   │ Claude Sonnet 5.5            │
│                         │ Isolated git worktree        │
│                         │ Hard turn limit: 3 attempts  │
├─────────────────────────┼──────────────────────────────┤
│ 2. THE BRAIN (Auditor)  │ Claude Opus 5.5              │
│                         │ Clean cold context           │
│                         │ Inspects raw git diffs       │
├─────────────────────────┼──────────────────────────────┤
│ 3. THE HISTORY (State)  │ Durable disk receipts        │
│                         │ receipt.md checkpoints       │
│                         │ Zero-loss session resume     │
└─────────────────────────┴──────────────────────────────┘

1. The Hands (Worker Plane): Claude Sonnet 5.5

Optimized for velocity, tool calling, and high-frequency code edits. It works exclusively inside an isolated git worktree:

git worktree add -b patch/session-fix .worktrees/patch-482 HEAD

Claude Sonnet 5.5 operates under a hard turn limit (maximum 3 self-correction iterations)

It has zero permission to merge into main and cannot inspect root secrets

2. The Brain (Auditor Plane): Claude Opus 5.5

Operates in a completely cold, unpolluted context window

It has no access to the worker's chat history or rationalizations

It receives only three raw artifacts:

The original bounded contract

The raw git diff generated in the worktree

The sensor stdout logs

Claude Opus 5.5 evaluates the diff adversarially

It specifically searches for hallucinated edge cases, silent signature breaks, and unhandled exceptions.

If any invariant is violated, it rejects the patch with a surgical failure classification

3. The History (Substrate Plane): Durable Disk State

Neither model is trusted to remember context across hours

All state is serialized to disk as structured markdown receipts (receipt.md)

If the process crashes or token limits trigger a reset, the next session resumes seamlessly from disk state

When an agent fails, junior engineers prompt-engineer a patch for that specific run

Senior harness engineers fix the entire failure class

Every failure must execute a closed-loop immunization cycle:

RUN: The agent produces code in a sandboxed branch

OBSERVE: Sensors capture compilation errors, assertion failures, or linter warnings

CLASSIFY: The harness categorizes the root cause (context gap, tool deficiency, or permission boundary)

REPAIR: The agent patches the local branch under strict step bounds (max 3 attempts)

VERIFY: Sensors re-run. If tests fail twice on the same error, execution halts immediately to prevent token burn

ACCEPT: If tests pass, the patch is accepted with a forensic change receipt

Most importantly, the harness updates its own permanent substrate:

Missing domain knowledge becomes a project-scoped guide

An uncaught edge case becomes a regression test fixture

A clumsy shell operation becomes a purpose-built CLI tool

Principle: The patch fixes one run

The harness change improves every run after it

Autonomous agents must never leave unrecorded commits

Every finished run must generate an immutable receipt.md at the repository root:

# AGENT EXECUTION RECEIPT // RUN-48291
- Model: Claude Sonnet 5.5 (Worker) / Claude Opus 5.5 (Auditor)
- Target: auth/session_manager.py
- Input Hash: e9a1f0c2
- Status: PASSED (exit code 0)

## Verified Invariants:
1. Redis lock timeout bounded to 500ms (checked via unit test)
2. Zero new dependencies introduced in requirements.txt
3. Pyright strict type check: 0 errors

## Forensic Trace:
- Files modified: 2 (+48 lines, -12 lines)
- Total tokens: 34,210 ($0.11)
- Sensor runtime: 3.4s
- Worktree SHA: d83b7e1

If an engineer cannot read a receipt in 15 seconds and verify why a change was made, the agent run is rejected by CI

Before allowing any frontier agent (Claude Sonnet 5.5 or GPT-6 Astra) to run unattended overnight, verify this 8-point checklist:

Task Contract: Is the input spec bounded to fewer than 5 files with explicit acceptance criteria?

Isolation: Is execution locked to an isolated git worktree with no write access to main?

Sensor Gating: Are linters, typecheckers, and test suites wired to block changes on exit code != 0?

Loop Breaker: Is there a hard ceiling (e.g., max 3 identical sensor failures) to halt runaway loops?

Context Budget: Is context loading restricted to under 150 lines of instructions plus path-relevant AST symbols?

Adversarial Audit: Does an independent auditor model inspect raw git diffs before PR creation?

Blast Radius: Are credentials, network egress, and database writes completely stripped from tools?

Durable State: Is session progress written to disk so crashes resume without loss?

Stop prompting. Start building harnesses

-> Join my Telegram

→ Follow @damkina7 for deep architectural teardowns of frontier AI systems

-> Bookmark this article so you have the pre-flight checklist ready before your next autonomous run