Building the Minimal Harness
Reviewed by Human · Updated October 19, 2026
✗ Wrong way
# AGENTS.md This is an Electron app that shows documents and answers questions. It uses TypeScript and React. See the README for the project structure and how to run it.
This AGENTS.md is technically present, but it just restates the README. It gives the agent no definition of done, no list of features, and nothing to check. An agent reads it, learns nothing new, and behaves exactly like the prompt-only run.
✓ Better way
# AGENTS.md ## Definition of done A feature is done only when its check in feature_list.json passes. Do not mark anything done from reading the code. ## Start here 1. Run ./init.sh to verify the environment. 2. Read feature_list.json. Work one feature at a time. 3. Features: window startup, document list, QA panel, data directory. ## Rules Never claim a feature works without running it.
Now the file does three jobs the README never did: it defines done, it points at state (feature_list.json), and it forbids the exact move — claiming done without proof — that sank the baseline. Same length, completely different behavior.
What Files Make a Minimal Harness for an AI Agent?
**Minimal harness**: the smallest set of files that changes agent behavior. Project 01 uses exactly three. **AGENTS.md**: the entry point that tells the agent the rules, the definition of done, and where to look — not what the app is, but how to work on it. **init.sh**: a startup script the agent runs first to install and health-check the environment, so it never debugs app code when the real problem is a missing dependency. **feature_list.json**: a machine-readable list of features with a status field for each, so 'done' becomes a checkable fact instead of the agent's opinion. Each maps to one job. AGENTS.md is instructions. feature_list.json is state. init.sh is the first check. That's the same idea you met in what a harness actually is — one file, one job. Together they turn a vague request into a system of record the agent can actually follow.
Field note
The first AGENTS.md I ever wrote was proud and useless. I described the app, listed the folders, linked the README, and felt organized. The agent behaved exactly as it had with no file at all — same premature 'done,' same half-built features. It took me an embarrassing while to see why: I'd written a description, not an instruction. The line that finally changed everything was one sentence — 'a feature is done only when its check passes, never from reading the code.' That single constraint did more than the three paragraphs above it. Now I write AGENTS.md the way I'd brief a contractor I don't fully trust yet: what 'done' means, what to check, and what not to claim.
Live Demo — AI Terminal
Watch the same agent, now given the three-file harness, start the exact task it botched before.
Your prompt
Your turn
Write the 'Definition of done' section of an AGENTS.md for Project 01's four features. Keep it short. The test: could an agent decide, with no other context, whether a feature is done?
Reflect
If your definition of done sends the agent to a check it can run, you've built a real instruction. If it describes a feeling, you've rewritten the README.
Challenge
Turn a README into a harness
Take any project's README and draft the AGENTS.md that would sit beside it. The goal is not to summarize the README — it's to add the three things a README never has: a definition of done, a pointer to state, and a rule about what the agent may not claim. If your AGENTS.md would change agent behavior versus the README alone, you've passed.
Go deeper
You've finished this module.
Mark it complete to earn your XP and keep your streak alive.
Progress saved locally · Sign up to earn XP