A practical field guide to making AI coding agents reliable across real repositories, long-running work, and eventually autonomous loops.
Ask whether the agent has a clear map, a healthy environment, durable memory, a narrow job, and an independent way to prove it finished.
Harness engineering is the design of the environment around a model so its capability becomes repeatable execution.
Completion becomes evidence-based: tests, lint, type-checks, smoke runs, and full-pipeline checks.
The next session reads progress and handoff state instead of reconstructing the last session from scratch.
Once goals, feedback, and stopping conditions are explicit, you can automate parts of the workflow safely.
These are operational benefits, not magic model upgrades. A harness exposes and reduces predictable failure modes; it cannot compensate for an impossible task or a missing product decision.
Break a large product request into verifiable slices that an agent can implement and hand off.
Run generator–evaluator loops with reproducible datasets, logs, and explicit failure states.
Keep evidence, methods, decisions, and open questions in one agent-readable workspace.
Keep a side project moving across evenings, devices, agents, and context windows.
Before adding more model horsepower, understand the structural reasons an agent can fail inside a perfectly ordinary codebase.
The lesson is not “spend more”. It is that a harness changes what the model can reliably do, while also making the extra runtime visible as a trade-off.
Use the layer as a diagnostic label. “The model is dumb” is a weak post-mortem; “verification gap in the export path” is a fixable one.
Independent smoke run shows the path is wrong. The repair is not a stronger prompt: add an end-to-end export check and make it part of the stopping condition.
Record how often the agent says “done” before an independent check agrees. The gap tells you where the harness is weak.
A harness is not one giant prompt. It is a set of cooperating subsystems that make work legible, bounded, and testable.
Give the agent a map, not an encyclopaedia.
Root guidance should explain the project, stack, first-run commands, hard constraints, and where deeper docs live. Progressive disclosure keeps task-relevant context close without making the root file unmanageable.
Capability is bounded by the actions the agent can take.
Provide enough access to inspect files, run checks, and change code. Apply least privilege deliberately: tools should be usable, observable, and appropriate to the project’s risk.
A healthy runtime is a prerequisite, not a side quest.
Versions, dependencies, services, build steps, and test commands should be reproducible. Initialisation earns the agent’s first implementation turn.
Persist decisions outside the context window.
Progress logs, feature state, git history, and handoff notes let a new session continue from a known point instead of re-discovering the project.
Replace self-confidence with executable evidence.
Tests, lint, type checks, smoke runs, end-to-end flows, and runtime observations close the loop between “I think it works” and “we can demonstrate it works”.
Humans can ask colleagues, search Slack, or remember a conversation. An agent’s practical world is the task, the files it can read, and the tool output it can observe.
Make the repository an executable map of the project: what it is, how it is shaped, how to change it, and how to prove the change.
# AGENTS.md — keep this short and navigable 1. Read docs/architecture.md before changing boundaries 2. Work on one feature from feature_list.json 3. Run ./init.sh, then the feature’s verification commands 4. Update progress.md and leave a clean handoff
Record the current feature, completed work, open issues, and the last verification result.
Keep task status machine-readable so scheduling, verification, and handoff share the same source.
Use commits as durable checkpoints and a clean restart path, not as a substitute for a progress note.
Install or check dependencies, inspect project state, and run baseline verification before implementation.
Work on one bounded feature. Keep the runtime observable while the agent makes changes.
Run the checks that count, including the full pipeline where boundaries can fail.
Update state, document unfinished work, remove temporary debris, and leave the next session a clean start.
$ ./init.sh # environment OK # baseline tests pass # app starts in smoke mode $ ./verify.sh # feature checks pass # end-to-end flow pass $ git status --short # only intended files changed
Agents overreach when the task boundary is fuzzy. They under-finish when completion is a feeling rather than a checklist.
One feature at a time. Explicit acceptance criteria. No rewriting the feature list to hide unfinished work.
{
"id": "search-api",
"status": "in_progress",
"acceptance": [
"GET /api/search?q=...",
"pagination defaults to 20",
"pytest passes",
"mypy --strict passes"
],
"evidence": "verify.log"
}The feature list is not just a project-management memo. In the repo’s model, it is shared infrastructure for the scheduler, verifier, and handoff reporter.
The agent’s confidence is not evidence. Design checks that expose the gap, then feed the result back into the next decision.
Replace the agent’s feelings with externalised, execution-based verification.
A good definition of done is phrased so a command or independent evaluator can answer yes or no.
Does an isolated function or component behave as expected with its dependencies controlled?
Do the real modules agree on data shape, paths, timing, and errors?
Can a user complete the actual flow, including startup, UI, services, and side effects?
run_id: 2026-09-03T20:42Z feature: search-api changed: [src/api/search.ts, tests/search.test.ts] tests: pass 18 / fail 1 failure: e2e path not mounted next: inspect router registration
Observability turns retrying from blind wandering into a targeted correction.
Treat the harness as an experimental system. Remove one component at a time and observe what degrades.
This is an ablation study: it shows which mechanism matters for the current model, task, and repository.
The repo’s useful warning: as models get stronger, some components may become less critical, while new bottlenecks emerge. A harness should evolve with evidence.
Main process, preload bridge, renderer, shared types, and services create meaningful boundaries.
The app stays constant while the harness grows from prompt-only to full workspace.
Import, index, retrieve, answer, and cite are testable paths with different failure modes.
Once the environment is stable, the next design question is: who presses start, how often does work repeat, and where does control flow belong?
The first twelve lectures improve the agent’s workspace. Loop engineering changes the trigger: the system starts work from a goal, a schedule, or an event.
Automation doesn’t remove control. It relocates control into explicit goals, budgets, permissions, feedback, and stopping rules.
Rule of thumb: has an end → goal. No end, just keep watching → loop.
The maker is rewarded for progress; the checker is responsible for correctness. The harness can keep the roles in one model, separate agents, deterministic scripts, or a human gate.
“It failed” is weak. “The router path is missing; add registration, rerun e2e” gives the maker a next move.
When a workflow needs specialisation, parallelism, shared state, verification, recovery, or human approval, make the hidden structure explicit.
Failure routes back to implementation. Insufficient information routes back to research. Shared state carries requirements, notes, code, and results.
The repository itself warns you not to confuse a useful design pattern with a viral term.
Its graph lecture fact-checks the “graph engineering” trend, calls out fabricated benchmark claims, and argues that graphs are often what complex loops become.
Draw the graph when the structure reduces ambiguity or failure. Don’t add a graph because the word is fashionable.
Start with a repo contract and one verifiable feature. Earn complexity through observed failure, not enthusiasm.
Explain the project, architecture, conventions, first-run commands, non-negotiables, and links to deeper docs.
Keep root guidance concise. Move domain-specific rules into docs/ or near the code they govern.
List the commands that count: tests, lint, type-check, build, smoke, and end-to-end flows.
# minimal AGENTS.md outline
## Project
## Architecture
## How to run
## How to verify
## Invariants
## Task workflow
## Deeper referencesGive it a bounded objective, acceptance criteria, and explicit dependencies.
Track todo → in_progress → verified, plus evidence and remaining risk.
End every session with the current state, changed files, checks run, and next safe action.
The agent should not spend the implementation session discovering that the project can’t install, build, or run.
$ ./init.sh → checking runtime versions → installing dependencies → running baseline checks → starting smoke environment READY baseline verified If this fails, fix the environment before the feature.
Every retry should name the observed failure and the harness layer being changed. Otherwise the loop repeats the same mistake more expensively.
Translate “looks good” into commands, expected outputs, and a clear stopping condition.
The next session’s success is determined partly by the state you leave behind.
A commit is useful. A commit plus a truthful handoff is a restart path.
Run one bounded feature end to end. Learn where the agent fails and what evidence you need.
Define the end state, independent verification, and stopping condition. Add a budget and escalation path.
Use a timer loop for genuinely ongoing checks, not for a finite implementation task that needs cumulative state.
When the loop contains parallel work, specialist roles, rollback, or approval, externalise nodes, edges, shared state, and routing.
Smallest useful progression: repo map → feature state → verification → clean handoff → goal loop → explicit graph.
The operating map: project, architecture, commands, invariants, references.
Initialise, verify the baseline, and prepare a known-good runtime.
Machine-readable scope, acceptance criteria, status, and evidence.
Truthful session state, decisions, open issues, and handoff.
$ mkdir -p harness-state docs $ touch AGENTS.md init.sh feature_list.json progress.md $ ./init.sh $ agent "implement the next verified feature"
The repository also provides a reusable skills/harness-creator/ skill with templates, scripts, and built-in eval cases for scaffolding and assessing harnesses.
The best first harness is not elaborate. It is honest, executable, and improved one failure at a time.
When an agent fails, inspect the environment before you swap the model.
README, projects, resource library, multilingual docs, and the harness-creator skill.
This is a self-contained HTML deck. Use the overview button to jump around, or the arrow keys to present it linearly.
Built from the repository’s English README and lecture/project material inspected on September 3, 2026. External claims are represented as reported by the repository unless separately linked above.