Harness Engineering for CLI Agents: When the "Harness" Matters More Than the "Horse"
> Deep-dive analysis. Core conclusion: a mid-tier model with hard hooks approaches the engineering completeness of the strongest model running unconstrained; Agent Teams' 5–10x token redundancy is not a necessity. > Tool stack covered: Claude Code / Cursor / Gemini CLI / Codex CLI / Copilot CLI.
From Prompt to Harness: Three Generations of Engineering Paradigms
- 2023 — Prompt Engineering: few-shot learning, chain-of-thought, role-play.
- 2025 — Context Engineering: RAG, memory systems, tool definition management.
- 2026 — Harness Engineering: named by Mitchell Hashimoto in a February 2026 blog post. His core habit: every time the agent makes a mistake, engineer a permanent fix into the agent's runtime environment so the error becomes structurally hard to repeat.
- Typecheck hook: TypeScript compilation after every file write — code is "compiling," not "probably correct."
- Coverage hook: test suite runs before the agent stops; falling coverage blocks completion.
- Loop detection: alerts after 3+ edits to the same file, preventing oscillation in local optima.
- Subagent isolation: complex tasks go to independent sub-agents; the parent receives compressed results only, avoiding long-context degradation.
- MCP: unifying tool interfaces (Stripe's Toolshed integrates 400+ internal tools; Codex CLI, Claude Code, Cursor, Gemini CLI are compatible). Key design: selective connection — avoid tool-description bloat drowning the context window. A custom CLI with 6 example commands can outperform a full MCP server in practice.
- Subagents: a firewall for context. Chroma research shows performance degrades with context length, especially at low semantic similarity. Each subagent gets a fresh, small, high-relevance window; the parent only sees compressed results. Cost structure: high-reasoning model orchestrates, cheaper faster models execute isolated tasks.
- Hooks: the most underrated component — bottom-line insurance. Claude Code supports session, prompt, tool-use, permission, compaction, stop, and subagent lifecycle events; Codex CLI supports SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, Stop. Three most effective hooks: pre-commit (biome + typecheck, silent on success), coverage (blocks completion below threshold), loop detection (alerts on 3+ edits to one file).
- Single session: 1x baseline; Subagent: 1.5–2x; Agent Team: 3–7x (up to 7x in Plan mode).
- Complex debugging: 500k tokens single-session vs. 950k for a 5-member team (1.9x).
- Full-stack feature development: 400–600k vs. 1.35M tokens (2.5–3x).
- With MCP tool metadata overhead, total redundancy can reach 5–10x.
- Prompt layer: AGENTS.md under 60 lines with universally applicable constraints; SKILL.md loaded on demand; structured output formats.
- Context layer: only 2–3 MCP servers active at once; conversation buffer + structured long-term rules; treat git as the agent's native memory (small, semantically clear commits).
- Harness layer: pre-commit hook (biome + typecheck, silent on success, errors on failure); PostToolUse hook surfacing linter errors; stop hook running changed test files; coverage hook alerting on regression; loop detection at 3+ edits; sub-agent modes defined for research, codebase tracing, and QA; escalation rule stopping after 3+ blocked tool calls to ask a human.
- 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
The core formula: Agent = Model + Harness. The model is the horse; the harness converts strong but potentially uncontrollable intelligence into reliable, predictable, manageable productive force.
The Four Pillars of a Harness
1. Constrain — shrink the possibility space: API boundary definitions, tool permission tiers, enforced architecture rules. Stripe's Minion exposes 400+ internal MCP servers but each agent session accesses only a subset. 2. Inform — deliver just the right context: CLAUDE.md, AGENTS.md, SKILL.md, MCP tool integration, RAG retrieval. 3. Verify — deterministic feedback loops: hooks fire on lifecycle events (run linter after file writes, run test suite before agent stops). Silent on success, error on failure. 4. Correct — automated repair: per HumanLayer, the most effective pattern is running type checks after every agent stop and returning only error messages for auto-fixing.
Benchmark: Mid-Tier Model + Hard Hooks vs. Strongest Model
The most counterintuitive finding: a mid-tier model (GLM 5.1 / DeepSeek V4 Pro) with a full harness — MCP protocol + isolated subagents + lifecycle hooks — matched or exceeded the strongest model (Claude Opus) in unconstrained single-session complex development (multi-file refactors, cross-module dependencies, CI integration).
Key hooks driving this:
The takeaway: when model capability has gaps, hard harness constraints turn "probably works" into "provably works." The gap is not infinitely closable — for deep-reasoning creative tasks the frontier model retains irreplaceable advantage — but the leverage of the harness on delivery certainty is striking.
MCP + Subagent + Hook: The Combined Paradigm
Agent Teams: The 5–10x Token Redundancy Trap
Claude Code's experimental Agent Teams are impressive as proof of concept (16 Opus instances, two weeks, ~$200k API spend, produced a C compiler that compiles Linux 6.9). But measured redundancy is high:
Why: each teammate is a full independent instance, coordination (mailbox messages, task-list sync) burns tokens, MCP tool schemas consume 40–50% of context, and Plan mode amplifies consumption.
When to use Agent Teams: only when teammates genuinely need peer-to-peer communication (cross-layer contract coordination). For independent parallel tasks, subagents are better: 1.5–2x cost, no coordination noise. For most engineering tasks, single-session with subagent isolation + hook fallbacks is enough.
Tool Selection Matrix (2026)
| Scenario | First choice | Alternative | Why | |---|---|---|---| | Complex multi-file refactoring | Claude Code + Hooks | Cursor | Highest first-pass quality | | Very large codebase analysis | Gemini CLI | Claude Code | 1M context, 1000 free req/day | | Frontend / React | Cursor | Codex CLI | Fast tab completion, visual feedback | | CI/CD automation | Codex CLI | Copilot CLI | Kernel-level sandbox, scriptable | | Budget-sensitive | Gemini CLI | Copilot CLI | Free tier covers daily needs | | Team-level harness | Claude Code | Cursor | Richest hook system and Skills ecosystem |
A validated combo: Cursor for daily IDE coding, Claude Code for complex refactoring, Gemini CLI for large-repo exploration, Codex CLI / Copilot CLI for CI/CD. The average developer in 2026 uses 2.3 AI coding tools — complementary tools beat betting on one.
A Minimal but Non-Trivial Harness Configuration
For a TypeScript monorepo:
Conclusion
The core insight in one sentence: the harness is not a supplement to the model but a translator — converting powerful but uncontrollable intelligence into reliable, predictable, deliverable engineering output.
"When intelligence falls short, engineering picks up the slack" is a victory of engineering thinking. Multi-agent is not a silver bullet — subagent isolation plus hook fallbacks are more pragmatic for most scenarios. The most exciting trend in 2026 is not any single tool but harness becoming a cross-tool common language — CLAUDE.md, AGENTS.md, SKILL.md, and the MCP protocol drive model-switching costs toward zero. Choose the tools best suited to your current task, combine 2–3, and wire them into a reliable engineering pipeline with a harness.
A horse, however fast, cannot pull a cart without a harness. An agent, however smart, cannot enter production without one.
References: