Appearance

Language

Mastering AI agents

What Is an AI Harness? 7 Parts That Keep AI Agents Reliable (2026)

An AI harness is everything around the model: rules, rules turned into tests, skills, MCP, memory, subagents, and verification with a human sign-off. What I actually do for each part.

Kelvin Wang · · 10 min read

Key points

  1. The model starts from nothing every session; the harness puts what it needs to know, follow and check in fixed places.
  2. Keep rules in one file every tool reads; turn rules that must never break into tests or hooks instead of hoping the model remembers.
  3. Put procedures in skills, outside data behind MCP, your feedback in memory, and side work in subagents.
  4. Done needs evidence: tests, screenshots, the live page. Publishing and deploys wait for my sign-off.

Give the same model to two people and the results can be far apart. The gap is rarely the model. It’s what surrounds it: which rules it reads before starting, which tools it can reach, what stops it when it goes wrong, and who checks the work. I call all of that the harness, as in the gear that turns a horse’s strength into pulling where you want to go.

For me, the harness started on day one. A harness automates the AI workflow, but not the way a Python cron job or loop repeats the same task on a schedule. It is the process of letting the AI iterate on itself, again and again.

What is an AI harness?

Anthropic’s Claude Code best-practices page calls Claude Code itself the harness: the model reads your rules and decides what to do, while the harness runs the checks you configured at fixed points, whatever the model thinks 1. I use a slightly wider definition: everything outside the model that makes it work the same way every time, the tool’s own settings plus the rule files, tests and routines you write yourself.

The problem it solves is simple. Every new session starts with an empty context. The correction you made last week, the trap in this project, the actions that need your approval first: the model knows none of it unless it sits somewhere the model reads, or gets checked, every single time.

I use Claude Code and Codex side by side. The features have different names, but the parts I need are the same. I split them into seven:

PartWhat it solvesWhat I do
1. RulesWhat it must know every timeOne AGENTS.md shared by both tools, plus one per project
2. Rules as testsWhat must never breakTests or an audit script for design rules, writing rules and deploy settings
3. SkillsRepeated proceduresSkill sources in one git repo; setup.sh links them into both tools
4. MCPOutside data and services.mcp.json holds only the launch command; credentials live outside the repo
5. MemoryFeedback I've already givenClaude Code's memory files, one per piece of feedback
6. SubagentsSide work and parallel buildsResearch goes to subagents; parallel agents each get a worktree
7. Verification and sign-off"Done" isn't proofTests, screenshots, the live page; nothing ships without my OK

Which tool you use matters less; my comparison of Claude Code, Codex and Grok Build is in Claude Code vs Codex vs Grok Build.

1. Rules: the file the AI reads before every task

Claude Code reads CLAUDE.md at the start of every session, and Codex reads AGENTS.md 2 3. These files are the base layer: build and test commands, places where the code misleads, decisions already made. Write them once and every session sees them.

My rules come in two layers:

  • One global file. Rules for every project (how to communicate, read the latest version before editing, commit only your own changes) live in ~/ai-config/AGENTS.md, which is a git repo. Codex’s ~/.codex/AGENTS.md is a symlink to it, and Claude Code’s ~/.claude/CLAUDE.md is one line: @~/ai-config/AGENTS.md. Both tools read the same file.
  • One file per project. This website’s rules say: read DESIGN.md before changing anything visible, articles are files in the repo, run tests with npx vitest run.

The usual mistake is writing too much. Claude Code’s docs recommend keeping each CLAUDE.md under 200 lines, since longer files get followed less reliably 2; OpenAI’s Codex guide says a short, accurate AGENTS.md is more useful than a long one full of vague rules 4.

Go deeper How to Write CLAUDE.md and AGENTS.md: One Rules File for Every AI Coding Tool (2026) Which tool reads which file, where they go, what to put in and leave out, plus a template.

2. Rules as tests: let code enforce what can’t break

A rules file is context the model reads. It usually complies, with no guarantee. Claude Code’s docs put it bluntly: if you keep adding emphasis to a line and Claude still misses it, that line belongs in a hook 1.

So I turn the rules that must always hold into tests that npx vitest run enforces:

  • Spacing comes only from the spec. DESIGN.md lists the allowed spacing values, and tests/spacing-scale.test.ts scans every page and component and fails on anything else.
  • Status colors use only the named roles. tests/status-colors.test.ts rejects hard-coded Tailwind color classes.
  • Every post belongs to a topic. A new post missing from src/content/topics.ts fails tests/blog-topics.test.ts.
  • Deploy settings can’t slide back. On November 5, 2026, 5 of 7 pushes failed to deploy because the build opened too many files at once (EMFILE), and nobody noticed. After the fix, tests/build-config.test.ts fails if that setting is raised again.

To me, writing a rule as a test is simply stating the constraint I want, clearly, in writing.

Some rules are judgement calls and shouldn’t fail the build. Writing rules are like that: a question heading ends with a question mark, list items open with a bold conclusion, the first paragraph doesn’t repeat the lead. node tools/audit-writing.mjs scans every post and lists what breaks them. It only reports; I decide what to change.

Then there are blocks at the tool level. My global Claude Code settings have a PreToolUse hook that checks SQL before the AI runs it through the Supabase MCP server. Statements that drop tables or wipe data stop for confirmation until I’ve read the full query.

There’s no full guide for this part yet; it’s coming.

3. Skills: write repeated procedures down once

A skill is a folder with a SKILL.md file. Tools only see its name and description until a task calls for it, then read the whole file, so a multi-step procedure costs less context as a skill than inside the rules file 1.

The skills I maintain live in ~/ai-config/skills/. Claude Code reads from ~/.claude/skills, and on the Codex side I use ~/.agents/skills, so a setup.sh script symlinks every skill into both:

  • Personal skills: each folder in ~/ai-config/skills/.
  • Third-party skills: snapshots in vendor/, never edited in place; to update, replace the whole folder. Colleagues who install from it get exactly my versions.
  • Project skills: the source stays in its project repo, with one line per skill in skills.manifest.
  • Skills installed on one side only: when an installer puts a skill into just one tool, setup.sh mirrors it to the other.

setup.sh --check changes nothing and reports what’s unlinked, what exists on one side only, and what shares a name but has drifted. I run it after adding or removing a skill and treat ok as done.

Go deeper Claude Code Skills: Where to Find Them and How to Choose Where skills live, where to find them, and what to check before installing.

4. MCP: give the AI the outside data

MCP is an open standard for connecting AI tools to outside services. I connect things like SEO data, Cloudflare and Supabase, so the AI reads the source directly instead of what I paste in.

The harness part is the credentials. This site’s .mcp.json has one launch command pointing at tools/seo-mcp.sh. The key lives outside the repo in a private file with 600 permissions, and the script reads it at run time. Push the repo to GitHub, let someone clone it, and the credentials stay behind.

Go deeper MCP setup guide: configuring MCP servers without committing secrets Scopes, approvals and launcher scripts, with my real configuration.

5. Memory: never say the same thing twice

I write the rules file; the AI writes its memory. Claude Code’s auto memory saves your corrections and preferences as files in ~/.claude/projects/<project>/memory/, and the first 200 lines (or 25KB) of the MEMORY.md index load into every session 2.

My website project has over forty memories now, one file each, with the rule, the reason and how to apply it. Two examples:

  • Check every instance of the same issue. When I review exchange pages, I ask the editor to scan all fee calculations of the same kind. I write 2.4 USDT so readers can see the amount without working out 12 × 20% themselves.
  • Cut copy the layout already explains. When the dates make the order clear, “Incident timeline” is enough of a heading. I also look for phrases like “see the link below” when I review a draft.

How memory and rules split: memory stays on this machine and only Claude Code reads it 2. Anything Codex should follow too, I move from memory into AGENTS.md.

I read every piece before it goes out. Memory makes these rules available the next time we edit a draft, and I check the finished copy myself.

There’s no full guide for this part yet; it’s coming.

6. Subagents: move side work out of the main session

A subagent has its own context and returns only a summary. It suits work that pulls in piles of search results or file contents the main session won’t need again. Claude Code already hands independent work to subagents on its own 1.

I use subagents for two things:

  • Research and data gathering. Reading official docs and collecting numbers go to subagents. My actual split: research and crawling run on Sonnet and Haiku subagents, and the main session only reads the conclusions.
  • Parallel builds. On November 16, 2026, eight calculator tools for this site went to several agents at once. Each worked in its own git worktree, and one spec held the shared rules: which files to read first, where files go, official sources only for numbers, no pushing or merging to main. An integration agent then merged the branches into one and handled the shared files everyone needed to touch, like the tool list and the topic shelves.

What lets several sessions change one repo without overwriting each other is git worktrees: one working directory and one branch per session.

Go deeper How to Get an Oracle Cloud Free ARM Instance in 2026: Claude Code 24/7 and a Git Repo Workflow Using git worktrees on an always-on server so several sessions can work on one repo.

7. Verification and sign-off: who decides it’s done?

An AI saying “done” is just a sentence. I want evidence:

  • Site features: npx vitest run passes, npm run build succeeds, and Playwright takes four screenshots: phone at 390px and desktop at 1280px, light and dark.
  • Deploys: after a push, wait for the Cloudflare build result and curl the live page to see the change is really there. Only then is it live.
  • SEO changes: once live, log what changed in the SEO tool and look at the effect after 7, 14 and 28 days.

What counts as done has to be written before the work starts. I write a spec with the goal and the finish line, then a plan; the method is in Write the Spec, Then the Plan.

The last check is me. Pushing this site to main deploys it, so committing and pushing an article needs my explicit OK. Threads and X posts need a separate OK on the exact text: “the article can go out” doesn’t cover social posts.

I approve website articles and social posts separately. A social post speaks to readers in my name, so I read every line myself and only then say yes.

Code changes go through pull requests, and I read the diff, comment and decide whether to merge from my phone.

I use that same phone to connect remotely to Codex on different computers. I allow remote access on each computer separately, and only that phone can access every connected device.

Go deeper How to Ship Code from Your Phone with Claude Code in 2026: Remote Control, Pull Requests and GitHub Mobile The AI branches, runs tests and opens the PR; I review the diff and merge on my phone.

Which part should you start with?

You don’t need all seven at once. The order I’d suggest:

  1. Rules: write a short AGENTS.md or CLAUDE.md with just your test commands and anything you’ve corrected twice.
  2. Verification: ask for evidence every time: which command ran and what it printed.
  3. Rules as tests: when a rule gets broken a second time, turn it into a test or a hook.
  4. Skills, MCP, memory, subagents: add them when you hit a repeated procedure, outside data to read, feedback you keep repeating, or side work that floods the session.

A harness grows out of your mistakes. Behind most rules and tests is a problem that really happened once.

Sources

  1. 1. Best practices for Claude Code · Claude Code Docs · checked 2026-11-16
  2. 2. How Claude remembers your project · Claude Code Docs · checked 2026-11-16
  3. 3. Custom instructions with AGENTS.md · OpenAI Codex Docs · checked 2026-11-16
  4. 4. Codex best practices · OpenAI Codex Docs · checked 2026-11-16

About the author

Kelvin Wang

Electrical engineer building tools with AI agents, sharing hands-on notes on engineering and investing.

More about me