This is a documentation page, not an essay — the “Explanation” section of the Habitat-Thinking ai-literacy-superpowers Obsidian plugin — but it’s the most complete treatment of Birgitta Boeckeler’s harness-engineering framework (martinfowler.com) available anywhere. The definition up front: harness engineering is the practice of surrounding AI-assisted code generation with deterministic tooling, agent-based review, and periodic entropy checks so that AI-generated code stays correct and coherent over time.

Why the harness exists

AI assistants produce plausible-looking code, but left unconstrained they drift: they forget conventions, repeat mistakes, and slowly erode a codebase’s internal consistency while the code still compiles and passes tests. The degradation is quiet. The solved analogue is the test harness — tests don’t make code correct by construction, they detect when it stops being correct. But functional tests aren’t enough: a harness for AI coding has to check the broader agreements — architectural decisions, naming conventions, security constraints, structural rules.

The three components

  • Context engineering — making sure the AI knows what it needs to know, via a HARNESS.md that captures the stack, decisions, conventions, constraints, and the rationale behind each. Not a README: a README explains what the project does; a context document tells an AI what it must and must not do, and why. Different audience, different update rhythm.
  • Architectural constraints — knowing the rules and enforcing them are separate problems, because an LLM optimizes for plausibility, not rule-following. Enforcement happens at “verification slots”: defined moments where a check passes or blocks. Prefer deterministic tools (linter, script, regex, structure assertion — pass/fail with no judgment) when a constraint can be expressed precisely; use agent-based review when intent or semantics are involved.
  • Garbage collection — the periodic fight against entropy: dead code, month-old TODOs, stale dependencies, abandoned conventions. Unlike the other two, GC isn’t triggered by a coding event; it runs because time passed. Its output is a report that surfaces accumulating problems, not a PR blocker.

Progressive hardening

The promotion ladder: Unverified (declared but no mechanism — honest accounting, a commitment to build enforcement) → Agent (an LLM judging against the constraint — catches most violations most of the time, needs human review) → Deterministic (a script or linter in CI that passes or blocks with no judgment involved). Movement is always toward deterministic: when an agent repeatedly catches the same class of violation, that’s the signal the pattern is understood well enough to automate. The ladder prevents both failure modes — demanding deterministic enforcement of novel constraints from day one, and accepting expensive agent enforcement as a permanent state.

The three enforcement loops

  • Inner — advisory, at edit time. Lightweight, low-friction suggestions; makes problems visible early without interrupting flow.
  • Middle — strict, at PR time. Full agent + deterministic suite with authority to block the merge.
  • Outer — investigative, on a schedule. GC rules, fitness functions, harness audits; produces reports that feed back as new constraints.

All agents run with bounded trust: review, suggest, report, flag — never unilateral authority to modify production code or merge. Humans decide.

The self-improving dimension

The plugin’s extension beyond Boeckeler: the harness learns from its own operation. A /reflect command after each coding session accumulates a learnings log the agents read; regression detection scans violation history — repeated violations signal that a constraint needs stronger enforcement, a clearer rationale, or reconsideration. “A static harness gets better only when humans notice failures… A self-improving harness treats its own operational history as input data.” Humans still decide what to accept; the pattern recognition is delegated. HARNESS.md itself is self-referential — each constraint tracks its status (unverified/agent/deterministic) and a harness-auditor keeps the document honest, making it both specification and health record. And harness-init bootstraps a candidate HARNESS.md by inferring constraints from the existing codebase, with the human confirming, rejecting, or refining each entry — incremental adoption instead of full commitment up front.

The through-line for anyone who runs an agent stack: the harness framework isn’t a tool, it’s an enforcement discipline — and the direction of travel (agent checks graduating into deterministic scripts) is the same path your own skills and cron mesh evolve along.