If you've ever handed an AI coding agent like Claude Code, Devin, or OpenClaw a task and watched it spiral into chaos—you're not alone. Developers are reporting cases where simple bug fixes balloon into six-hour loops, half the codebase gets rewired, and unrelated tests mysteriously disappear. The culprit? Context window pollution, agent amnesia, and scope drift. But there's a growing movement in the community to fix this with something called Harness Engineering—and you can start using it today.

What Is Harness Engineering?

An Agent Harness is essentially a structured control layer that lives inside your repository. Instead of feeding your LLM one massive system prompt, you embed lightweight configuration files and feedback loops directly into the workspace so every agent knows exactly what to do—and what not to do. Author Masih Moafi has packaged his battle-tested approach into a public GitHub repo (MasihMoafi/harnesses-I-use), and it's surprisingly practical for anyone already comfortable with AI-assisted development. The core idea is deceptively simple: make your repository self-documenting for agents. Every time they enter the project, they read AGENTS.md first—which acts as the global router defining priority constraints, communication defaults, and local-first behavior rules. This single file becomes the agent's north star, keeping it grounded instead of flying off into unprompted refactors.

The Building Blocks of a Good Harness

Moafi's system includes several specialized files that work together like a well-oiled machine. CODEX_CODING_GUIDELINES.md enforces surgical coding rules adapted from Andrej Karpathy's practices—requiring minimal changes, style-matching, and goal-driven execution. TERMINAL_AND_GIT_RULES.md keeps terminal navigation safe by specifying explicit git scoping (never using "git add -A"), SOCKS/HTTP proxy configuration, and using Ubuntu pkexec for root commands instead of raw CLI password prompts. There's even a dictionary file called abbn.md that defines standard abbreviations like ctu = continue, fmy = familiarize, and ver = verify to save token count during communication. SESSION_HANDOFF_RULES.md handles context awareness and continuity between sessions—defining how state should be captured and transferred so you don't lose work when an agent restarts. ARTIFACT_RULES.md governs verified visual and math outputs including local HTML layout verification, MathML for formula rendering, and PDF inspection. The beauty here is that none of this requires complex code—it's just Markdown files living in your repository.

Lessons From Karpathy's Autonomous Research

This harness approach draws direct inspiration from Andrej Karpathy's open-source autonomous agentic research project called autoresearch. That system demonstrates how an AI agent can run a self-correcting loop: proposing changes, running experiments, and either keeping results if metrics improve or discarding them. The control is managed through a simple program.md file that defines the bounded operational context. The principles translate directly to code generation work. Moafi's harness requires three things from every agent interaction: surgical changes (touch only exact lines needed, no drive-by refactoring), verifiable outcomes (agents must run local verification scripts and attach raw logs as physical evidence before claiming completion), and harness simplification (every rule is overhead, so you continuously prune redundant ones as models improve). The goal isn't to constrain agents—it's to give them just enough structure to be genuinely useful.

Key Takeaways

  • AI coding agents without boundaries suffer from context pollution, memory loss, and scope creep that can waste hours of compute time
  • Harness Engineering adds a lightweight control layer inside your repository using Markdown configuration files
  • Essential harness components include AGENTS.md (global router), CODEX_CODING_GUIDELINES.md (coding rules), TERMINAL_AND_GIT_RULES.md (safety guardrails)
  • Inspired by Andrej Karpathy's autonomous research, the approach requires surgical changes and verifiable evidence of completion
  • The methodology has been tested on real ML research workflows with published results in the MasihMoafi/seminar repository

The Bottom Line

If you're building code with AI agents and still writing 2,000-word system prompts, stop. Repository harnesses are simpler, more maintainable, and actually work at scale—your future self (and your codebase) will thank you for making the investment upfront. Check out MasihMoafi/harnesses-I-use on GitHub to get started with ready-made templates, or visit masihmoafi.tech for more experiments and research on this approach.