Harness Engineering for CLI Agents: Why the Harness Matters More Than the Model
> Source: in-depth analysis from a Chinese tech forum > Tools referenced: Claude 4.7 Opus / GLM 5.1 / DeepSeek V4 Pro | Claude Code / Cursor / Gemini CLI
Key Points
- From Prompt to Harness — three engineering eras. 2023 focused on prompt engineering (few-shot, chain-of-thought, role-playing). 2025 shifted to Context Engineering (RAG, memory, tool definitions). By 2026, Harness Engineering — named by Mitchell Hashimoto in February 2026 — became the dominant paradigm: every observed agent failure is engineered into the agent's runtime so it structurally cannot recur.
- The core formula is Agent = Model + Harness. The model is the horse providing intelligence; the harness (bridle, saddle, reins) does not make decisions but governs how force is applied. The harness translates powerful but uncontrollable intelligence into reliable, predictable, shippable output.
- Four pillars of a harness:
- Constrain — narrow the possibility space via API boundaries, tool permission tiers, and architecture rules (e.g., Stripe's Minion exposes 400+ internal MCP servers but grants each agent session only a subset).
- Inform — supply the right context at the right time through CLAUDE.md, AGENTS.md, SKILL.md, MCP integrations, and RAG retrieval.
- Verify — establish deterministic feedback loops via Hooks that fire at lifecycle events (run linter after file write, run tests before stop; succeed silently, fail loudly, return errors as signals rather than flooding the context window).
- Correct — automate fixes; HumanLayer's most effective pattern runs type-check on stop, returns only error messages, and lets the agent self-repair, closing the gap between "probably works" and "provably works."
- Head-to-head: mid-tier model + hard Hooks vs top model unconstrained. Control A: Claude 4.7 Opus, single unconstrained session, no harness. Control B: GLM 5.1 / DeepSeek V4 Pro with full harness (MCP, isolated Subagents, lifecycle Hooks). On a complex multi-file refactor scenario, mid-tier model + hard hooks matched or exceeded Opus unconstrained. Deterministic boundaries (typecheck Hook, coverage Hook, loop-detection Hook, Subagent isolation) force every step to be compilable, tested, and non-oscillating. The gap is not infinitely bridgeable — Opus retains an edge on deep creative reasoning — but on engineering delivery certainty the leverage is dramatic.
- MCP + Subagent + Hook — the combined pattern.
- MCP standardizes tool exposure; Stripe's Toolshed integrates 400+ tools. Selective connection beats bulk loading — a custom CLI with six example commands outperforms a full MCP server.
- Subagents act as a context firewall (Chroma research shows performance degrades as context length grows, especially when semantic similarity to the question is low). Each Subagent gets a fresh, small, high-relevance window; the parent receives only compressed summaries. Cost structure: parent uses a strong reasoning model for orchestration, Subagents use cheaper, faster models.
- Hooks are the most underrated component — the hard floor, not a nice-to-have. Claude Code supports session, prompt, tool-use, permission, compaction, stop, and subagent events. Codex CLI supports SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, Stop. The three highest-leverage hooks are pre-commit (biome + typecheck), coverage (block completion if coverage drops), and loop detection (alert after 3+ edits on the same file).
- Agent Teams: the 5–10x token trap. Claude Code's Agent Teams feature lets 16 Opus instances spend two weeks and $200k of tokens writing a C compiler that builds Linux 6.9 — proof-of-concept impressive. In real engineering work, however, token overhead is extreme:
- Single session: 1x baseline
- Subagent: 1.5–2x
- Agent Team: 3–7x (up to 7x in Plan mode)
- 2026 tool selection guide.
- Minimal non-trivial Harness config for a TypeScript monorepo.
- Prompt layer: AGENTS.md under 60 lines, only universally-applicable constraints; SKILL.md loaded on demand; structured output format.
- Context layer: activate only 2–3 MCP servers at once; conversation buffer + structured long-term rules; treat git as the agent's native memory via small clean commits.
- Harness layer: pre-commit Hook (biome + typecheck, silent on success, loud on failure), PostToolUse Hook (surface linter errors after every write), Stop Hook (run changed test files, return errors), coverage Hook (alert on coverage drop), loop detection (alert after 3+ edits on same file), Subagent modes defined for research / code-tracing / QA, escalation rule (stop and ask after 3+ blocked tool calls).
- Closing insight. The harness is not an add-on to the model — it is a translator that converts powerful but uncontrollable intelligence into reliable, predictable, deliverable engineering output. "Intelligence not enough, engineering makes up the rest" sounds like a compromise but is in fact a victory of engineering thinking. Multi-agent setups are not a silver bullet; Subagent isolation + Hook fallback is the pragmatic default for most scenarios. CLAUDE.md, AGENTS.md, SKILL.md, and MCP are converging into a cross-tool lingua franca, making model switching near-zero cost.
- Mitchell Hashimoto, "Engineering the Harness" (2026.02)
- OpenAI Codex: 1M lines of production code by agents (2026.02)
- Anthropic Claude Code Agent Teams Documentation
- AI Harness Engineering Compatibility Matrix (Cody Lindley, 2026.05)
- Garden Skills: https://github.com/ConardLi/garden-skills/
- Claude Code: https://code.claude.com/docs/zh-CN/overview
Measured data: a 5-person Agent Team ~5x tokens; complex debugging 50万 (single) vs 95万 (team, 1.9x); full-stack feature 40–60万 vs 135万 (2.5–3x); including MCP tool metadata overhead, total redundancy reaches 5–10x. Drivers: each teammate is an independent instance with a full context window, coordination overhead (mailbox messages, task-list sync, dependency checks) burns tokens, MCP tool schemas occupy 40–50% of context, and Plan-mode multi-turn planning amplifies consumption. Use Agent Teams only when peers genuinely need peer-to-peer coordination (frontend needs backend API shape, tests need both contracts). For independent parallel work (run tests, search code, generate docs), Subagents are better at 1.5–2x with no coordination noise.
| Scenario | First choice | Alternative | Rationale | |----------|--------------|-------------|-----------| | Complex multi-file refactor | Claude Code + Hooks | Cursor | SWE-bench 80.9%, highest first-pass rate | | Very large codebase analysis | Gemini CLI | Claude Code | 1M context, 1000 free req/day | | Frontend / React | Cursor | Codex CLI | Tab completion <100ms, visual feedback | | CI/CD automation | Codex CLI | Copilot CLI | Kernel-level sandbox, script-friendly | | Budget-sensitive | Gemini CLI | Copilot CLI | Free tier covers daily needs | | Team-level Harness | Claude Code | Cursor | Richest Hook system and Skills ecosystem |
Verified efficient combination: Cursor for daily IDE coding (Tab + visual feedback), Claude Code for complex refactors (best quality, Agent Teams as escalation), Gemini CLI for large-repo exploration (1M context + free), Codex CLI / Copilot CLI for CI/CD. In 2026 the average developer uses 2.3 AI coding tools; complementary strengths beat single-stack bets.