Harness Engineering: an environment for an autonomous agent

A harness isn't a prompt or a beefier model. It's the environment around the agent: a set of sources of truth it reads at the start and along the way. Same idea as the harness-engineering lesson, but the lens is the development process itself, not the in-app loop — how to get a project into a state where a coding agent runs a task with almost no supervision. The environment is built from five layers — from the global (how you work with an agent at all) to the project-specific (the rules of this exact repo) and cross-session memory. The more layers in place, the less the agent improvises and the rarer it breaks for no reason.

A harness turns a 'task' into a four-phase route: A — framing & scope (one thread = one task, check recipes, a plan if needed); B — design (sketch before code, ADRs for decisions, read the boundary's lessons); C — implementation loop (TDD, run sensors, live-update, /wrong, escalation); D — close (verify, ritual, doc-sync, commit, handoff). It's not a strict 0→24 line. The human plugs in at exactly four points — give the task, approve the sketch, say 'wrong', say 'commit'. The agent drives the rest. Play with the explorer below: filter by phase, open step details, and run the scenarios — big feature, bugfix, docs edit, correction, escalation.

The most common harness failure is confusing 'written in the rules' with 'actually followed'. A barrier is enforced mechanically: pre-commit and CI won't let code ship if it fails a check. A convention rests only on the agent's discipline — written in AGENTS.md, but nothing checks it. A conditional step fires on a trigger and is often skipped. The good news: barriers are off-the-shelf, cross-stack tools. Import boundaries: dependency-cruiser / import-linter; dead code: knip / ts-prune; cycles: madge; nesting and size: eslint (max-depth, max-lines). What isn't covered, you add as your own check script. Whatever you can't put a barrier on, you can't rely on for long.

The autonomy core is the lessons-ledger: a mechanism that turns your corrections into code rather than a forgotten chat. You tell the agent 'wrong' → the /wrong command runs normalize, which splits a fork. A computational lesson (the mistake is machine-catchable) → a sensor edit: a new linter rule, a type check. An inferential lesson (judgement needed) → a markdown file the agent reads before working on that boundary. A separate maintain step promotes matured inferential lessons into sensors. The health metric is how many lessons graduated into barriers, not the size of the notebook: the goal is for knowledge to harden into machine checks, not pile up as text.

/wrong "<mistake>"
  → normalize:
      machine-catchable? → sensor       # computational (barrier)
      needs judgement?   → lessons/<boundary>/  # inferential (nudge)
  → maintain: matured inferential → promote → sensor
health metric = lessons promoted to sensors, NOT notebook size

This recipe is a hub. A series follows it, where each rollout phase unfolds into its own recipe with copyable prompts. The front door is 'four modes of developing with AI' (A/B/B+/C): the meta-decision of how much AI a project even needs. Not everyone needs full agent-first — a harness is mandatory for modes B+/C and barely needed for A/B. Below is the series map: from picking a mode and auditing to scaling out. Each row is its own recipe; walk the phases in order or jump straight to the one you need.

Where to start without drowning? Order from cheap-and-uncontroversial to expensive-and-contentious. First an ADR: pin down your tool choices — that's for humans, no resistance. Then a Definition of Done — one checklist for what 'done' means. Then sensors — turn the DoD into machine barriers (pre-commit + CI). And only then the lessons-ledger — it pays off once barriers exist and there's something to promote into them. Every layer is useful on its own. You don't have to build it all at once: one real barrier today beats a perfect quarter-long plan.