Harness engineering is not AGENTS.md

Once you understand harness engineering, a natural question is:

if I’ve already written an AGENTS.md or CLAUDE.md for my project, have I prepared the agent’s working conditions?

Not really.

These files matter, but what they mainly solve is:

what should the agent know first on entering the project?

A real harness still has to go on to solve:

where it finds information, how it completes tasks, which boundaries it mustn’t cross, and how it checks and recovers when it’s done.

AGENTS.md isn’t better for being more detailed

In practice, OpenAI tried stuffing large amounts of project knowledge and rules into one huge AGENTS.md.

It didn’t work well.

A file that big crowds out the context needed to actually do the task; with too many rules, the agent struggles to tell what matters; and the content easily goes stale, while the agent may not know which information is still trustworthy.

So they later kept a shorter AGENTS.md, mainly as a map of the project, pointing to more specific product descriptions, architecture docs and execution plans.

OpenAI summed it up as:

give the agent a map, not a thousand-page manual.

Anthropic’s advice on CLAUDE.md is very similar.

CLAUDE.md is for stable information needed every time you enter the project, such as build commands, project conventions, architecture decisions and common workflows.

But rules that only apply to certain files can go into per-directory rules; processes needed only for certain kinds of tasks can go into a Skill. Anthropic also recommends keeping a single CLAUDE.md under about 200 lines.

More importantly, Anthropic says explicitly:

CLAUDE.md is context provided to the model, not enforced system configuration.

Claude will try to follow it, but can’t guarantee strict compliance every time. Rules that truly must not be broken need to become permissions, automatic checks or confirmation before execution.

So AGENTS.md and CLAUDE.md are more like onboarding notes.

They’re the entrance to the harness, but not the whole harness.

What else does a harness need?

Without too much engineering jargon, I’d split it into five parts.

1. A trustworthy project entry point

The agent first needs to know:

what problem this product solves; which document is authoritative right now; how code and material are organized; which decisions have been confirmed; which directions have been abandoned; where to look for answers to different kinds of questions.

The point isn’t to feed it all the material at once.

It’s to let it know:

which information is trustworthy, and how to keep finding relevant information.

Otherwise, even with dozens of documents in the project, the agent may read an outdated one and very earnestly carry out the wrong direction.

2. A clear current task

Knowing what the whole project is still isn’t knowing what to do now.

Each time the agent starts work, it’s best if it can clearly see:

which single problem to solve this time; what’s within the task’s scope; what not to change while it’s at it; what counts as done; what evidence it needs to leave at the end.

For example, rather than just writing:

improve the sign-up flow.

it’s better to spell out:

fix enterprise users not receiving the verification email after signing up. Don’t refactor any other sign-up logic. When done, test both regular and enterprise users separately and provide the results.

The key here isn’t just a longer prompt, but turning the task’s scope and acceptance criteria into state in the project that can be tracked over time.

In its long-task experiments, Anthropic also used feature lists, progress files and Git history so that different sessions could see what the last round completed, whether the project was in a healthy state, and what to do next.

3. The tools needed to complete the task

An agent being able to read and write code only means it can change the project.

It doesn’t mean it can judge whether the product really works.

Depending on the task, it may also need to:

start the app; operate a browser; create test accounts; look at error logs; read a test database; run the full user flow; compare results before and after a change.

If it can only look at code, a lot of the time it can only infer the result from the code.

If it can open the product, reproduce the problem, carry out the steps and read the logs, it has a much better chance of discovering:

the code runs, but the real flow still has a problem.

4. Boundaries that are actually enforced

Some rules are enough written down in docs, such as:

how files are named; where drafts go; which tests to run before committing.

But some boundaries can’t rely on a single reminder:

don’t touch production data; don’t send customer emails directly; don’t delete key files; confirm before adding new dependencies; hand anything involving payment to a person.

These boundaries are best truly enforced by permissions, automatic checks or confirmation flows.

For example:

“don’t modify the production database” written in AGENTS.md is guidance for behavior.

Only if the agent doesn’t have write access to the production database at all is it a system boundary.

Both matter, but their reliability differs.

5. Checking, isolation and recovery

An agent changing the code doesn’t mean the task is done.

It also needs to know:

which tests must be run; whether to go through the full user flow; how to check existing features weren’t broken; whether to provide screenshots, logs or test results at the end; how to roll back if the change is wrong.

Process files also need a clear home.

While working, agents often generate:

temporary scripts; test data; screenshots; logs; drafts; intermediate exports.

If these are scattered across the project root, over time neither people nor agents can easily tell:

which are official deliverables; which are just process files; which are no longer useful.

So isolation can be part of a minimal harness too:

put temporary scripts in a fixed directory; save screenshots and test output separately; keep official files apart from intermediate output; check at the end of the task whether anything needs cleaning up.

Version history matters just as much.

Keeping clear diffs, small commits and a state you can roll back to stops the agent from piling more work on top of a bad change.

Does a personal project need such a complicated setup?

No.

OpenAI’s case comes from a large codebase developed with agents over a long period, and can’t be copied directly into every personal project. OpenAI itself stresses that the autonomy its agents achieved depended heavily on structure, tools and feedback mechanisms designed specially for that project.

A personal project can start with a very light version:

• a short AGENTS.md or CLAUDE.md as the project’s entry point;
• one trustworthy current plan that separates what’s confirmed, pending and abandoned;
• a clear scope and acceptance criteria for each task;
• written instructions on how to start, test and check the project;
• a note of what mustn’t be changed and which operations need confirmation;
• fixed, separate directories for temporary files, screenshots and test output;
• Git for reviewing changes, keeping versions you can restore.

The shorter the task and the easier the result is to check by eye, the lighter this preparation can be.

But when tasks span multiple files and multiple sessions, or the agent starts having broader permissions, a prompt and one entry document become less and less enough.

AGENTS.md or CLAUDE.md tells the agent how to enter the project.

Harness engineering is about what happens once it’s in: how it finds information, completes tasks, respects boundaries, checks results, and backs out when it gets something wrong.