Harness Engineering

Start with the failure, not the file

You may be thinking: “My agent keeps missing things, so I need a better prompt or a bigger AGENTS.md.” Sometimes that helps. Very often it only makes the instructions longer while the underlying system stays fragile.

Try this before building anything

1. Give a fresh agent one bounded real task with only a normal prompt.
2. Do not rescue it immediately.
3. Write down every place where you had to supply missing context, correct scope, explain state or verify a claim manually.
4. Use those interventions as your first harness backlog.

Common traps

• Instruction debt: every failure becomes another paragraph in AGENTS.md until the important rules are buried.
• Context duplication: copying the same project knowledge into prompts, agent files and working notes until nobody knows which copy is authoritative.
• Chat-state dependency: decisions and progress live only in conversation history, so the next session starts from amnesia.
• Self-certification: the same agent that changed the system also decides whether the change is correct.
• Fake determinism: writing “always run tests” in prose and treating that as equivalent to a real verification gate or hook.

Look out for

• You keep repeating the same project explanation to new sessions.
• Your root instruction file keeps growing faster than the project map around it.
• The same rule exists in prompts, docs and scripts with slightly different wording.
• “Done” is a chat statement rather than a state transition backed by evidence.
• Failed runs produce no new evidence, so the next attempt is mostly guesswork.

Prove the first lesson

Open a completely fresh session with no chat history. It should be able to explain the project, locate the relevant code, name the hard constraints, identify the current task and run the correct verification path using repository artifacts only. Anything you still need to explain manually is evidence of the next harness gap.

The harness is a system, not a file

A harness does not replace Prompt or Context Engineering. Those belong to Work With AI. The harness operationalises them so a delegated agent can reliably discover instructions and context, act with bounded tools, preserve state and verify work without a human rebuilding the setup every session.

Three things that decide whether the agent may stop

Working contract before the run

Goal:
Scope:
Exclusions:
Authority:
Verification:
Expected evidence:
Stop when:
Escalate when:

The contract makes observability useful: after a failure you can ask which promise broke instead of staring at a pile of logs.

When NOT to add another harness component

Do not create a new file, hook, agent or rule merely because the concept sounds mature. Add structure when an observed failure justifies it.

• If ordinary code can enforce the rule more clearly, use code.
• If a document is never consulted, remove or relocate it.
• If a sub-agent has no distinct responsibility or context boundary, keep one agent.
• If a hook adds friction to low-risk work without preventing a real failure, remove it.
• If the model/tool now handles an old workaround reliably, retest and prune the workaround.

Minimal starter pack

Start small. Four files can already change agent behavior substantially:

AGENTS.md
feature-list.json
docs/working/progress.md
scripts/agent-init.sh

1. Root instructions are a map

# AGENTS.md

## Mission
What this repository does and who it serves.

## Start here
1. Run: ./scripts/agent-init.sh
2. Read: docs/architecture.md
3. Read current work: docs/working/NEXT.md

## Non-negotiables
- Do not change ...
- Preserve ...
- Never mark work complete without ...

## Verification
- Unit: ...
- Integration: ...
- End-to-end: ...

## Deeper docs
- Product rules: docs/product.md
- Architecture: docs/architecture.md
- Operations: docs/operations.md

2. State is machine-checkable

{
  "id": "F03",
  "behavior": "User can export the report as CSV",
  "verification": "npm test -- export-report",
  "state": "not_started",
  "evidence": null
}

3. “Done” requires evidence

For every important task, write the definition of done before implementation. The strongest completion criteria are observable behaviors and executable checks, not vague phrases such as “works correctly” or “looks good”.

Failure → harness layer

Next: Loop Engineering — stop being the person who presses Continue →