Claude Code Harness Explained: Model, Inner Loop, Outer Config

As you spend more time with Claude Code, the word “harness” can sound like another name for prompt craft. In practice it usually means the whole runtime around the model: the product agent loop, tools, context handling, and the outer settings you add with CLAUDE.md, hooks, MCP, and subagents.

📑Table of Contents

1. Model, inner harness, and outer harness
2. Long-running failure modes from Anthropic
3. Why separate generator and evaluator
4. Harnesses go stale as models improve
5. Minimal quality-loop materials before custom work
6. Minimal harness checklist you can run today
7. FAQ
8. Summary — separate layers, add the minimum

What to understand first

---

Map the problem first

This article starts from a community three-layer map—model, inner harness, outer harness—and lines it up with Anthropic Engineering guidance on long-running agent failure modes. The goal is not to stack more config. It is to name which layer you are touching, then add only the smallest verification and handoff pieces that multi-session work still lacks.

---

Check the primary sources

Primary sources: Effective harnesses for long-running agents, Harness design for long-running apps, Scaling Managed Agents, and the demo repository cwc-long-running-agents.

---

Practical check

For vocabulary, a Speaker Deck community talk is useful; for failure modes and verification design, prefer Anthropic Engineering.

---

Model, inner harness, and outer harness

A harness is not “better prompts” by another name. In Claude Code discussions it covers the system that keeps a model useful in a real loop—from tool delivery to context management. A practical three-layer map looks like this:

Name the layer before changing it

1. Model — the inference engine (Opus, Sonnet, and so on)
2. Inner harness — Claude Code’s agent loop, tools, sandbox, and context management (the product itself)
3. Outer harness — CLAUDE.md, skills, hooks, slash commands, MCP, subagents (what users and teams can design)

If the same model feels different in Cursor, Devin, or Claude Code, the gap is often the inner harness. Anthropic’s Managed Agents write-up even cites Claude Code as an example of an excellent harness.

---

Compare the layers side by side

Layer	Examples	Who changes it	Change speed	Typical risk
Model	Opus / Sonnet	Provider choice	Release-driven	Mistaking ability gaps for “missing settings”
Inner harness	Loop, tools, sandbox, compaction	Product updates	Fast	Custom outer work gets absorbed and goes stale
Outer harness	CLAUDE.md, hooks, MCP, subagents	Users / teams	Immediate	Too much surface area to debug

---

Read the table as a decision aid

---

Read the comparison table

---

Compare the three layers

Sources: Speaker Deck community talk, Scaling Managed Agents (article content as of 2026).

Reader action: name the layer you are changing or debugging in one sentence—model, inner, or outer. When that label is fuzzy, teams often add hooks after a model update, or try to paper over product-loop limits with more outer config.

---

Practical check

For concrete outer-layer examples, see our guides on Claude Hooks and Skills.

---

Long-running failure modes from Anthropic

Across long jobs and multiple context windows, compaction alone is not always enough. Effective harnesses highlights two recurring failures:

Two failure modes

1. Trying to do too much in one shot — the run dies mid-context and the next session must guess at a half-finished state
2. Declaring the project done too early — work stops while the system is only partially complete

---

Handoff between sessions

The structural fix mirrors a human shift handoff:

• Initializer agent — first session sets up the environment (init.sh, progress log, initial git, feature list treated as failing until done)
• Coding agent — later sessions ship incremental features and leave a clean end state with structured updates

---

What counts as clean

“Clean” means merge-ready for main: no large bugs, orderly docs, and a state where the next developer (or next agent session) can start a new feature immediately. Progress logs plus git history let a fresh context recover state quickly.

Reader action: for your own long runs, answer Yes/No for progress log, git, and a feature list (or equivalent unfinished work list). Missing all three before multi-session work is a high-risk setup.

---

Why separate generator and evaluator

When the builder also grades the work, mediocre output can look “confidently done.” Harness design for long-running apps argues for separating generator and evaluator, and for tuning the evaluator to be skeptical.

A related failure mode is context anxiety: as the window fills, some models wind down early. Keep these levers distinct:

• compaction — summarize while staying in the same conversation
• context reset — clear fully and pass a structured handoff to the next agent

Separate the two quality roles

Official write-ups note cases where Sonnet 4.5 needed reset-style mitigation, while Opus 4.5 no longer did. The “must-have” harness layer can become dead weight after a model upgrade.

---

Apply the split to page checks

Frontend experiments share scoring rubrics (for example design quality, originality, craft, functionality) between generator and evaluator, and verify live pages with tools such as Playwright. Longer app work extends toward planner + generator + evaluator.

---

Practical check

Reader action: check whether “done” is decided by the same actor that builds the change. If not separated, optimistic self-pass is more likely.

---

Harnesses go stale as models improve

A harness encodes assumptions about what the model still cannot do. When the model improves, yesterday’s mandatory gate becomes ballast. Managed Agents design assumes this and separates session (durable logs), harness (loop), and sandbox (execution) so each can be replaced.

Practical implications:

Keep boundaries replaceable

• Brain vs hands — keep credentials unreachable from the sandbox; separate decisioning from execution
• Cattle, not pets — prefer re-provisionable boundaries over nursing a single all-in-one container
• Inventory after upgrades — after model or Claude Code updates, list hooks, resets, and MCP servers that no longer pay for themselves

More config is not more strength. Add only after you observe a missing capability, and remove when the assumption dies.

Reader action: after your latest model update, name one outer setting you could delete. If you cannot name one, your outer harness may still be thin—or you have not measured what still helps.

---

Minimal quality-loop materials before custom work

Before building a thick custom stack, test product features and official demo primitives. cwc-long-running-agents is not a turnkey product; it is demo material. Still, three quality-loop primitives are easy to map:

Three quality-loop primitives

1. Default-FAIL contract — each criterion starts false; no pass before evidence is read
2. Fresh-context evaluator — a separate agent without Write/Edit scores the result
3. Agent-maintained handoff — progress notes plus git for the next session

On the product side, Claude Code /goal is a practical entry point for generator/evaluator-style loops. Custom hooks should wait until you need project-specific gates or audit rules. For hook mechanics, see the Hooks guide.

---

Use the demo as a yardstick

Caveat: the demo repo is not positioned as a maintained production template. Use it as a yardstick for missing primitives, not as a drop-in system of record.

---

Practical check

Reader action: try /goal or a minimal handoff (progress + git) first; promote only the missing criteria into hooks.

---

Minimal harness checklist you can run today

Five checks to start with

1. Name the layer you are touching: model, inner, or outer
2. For multi-session work, check progress log, git, feature list, and init-equivalent setup
3. Confirm “done” is not judged only by the builder (/goal or a separate evaluator)
4. Add outer harness only for observed gaps; keep it small and portable
5. After model/product updates, inventory and delete dead-weight resets/hooks

---

Match each check to a situation

Situation	Try first	If still insufficient
Short interactive coding	Bare inner harness + minimal CLAUDE.md	One skill or slash command
Multi-session implementation	Progress + git + feature list	Initializer-style first-session setup
Soft self-declared quality	/goal or independent evaluator	Default-FAIL hooks
Config bloat	Delete via inventory	Move procedure into portable Markdown

---

Pick one row

Sources: Anthropic Engineering articles above and cwc-long-running-agents (as of 2026).

Pick one row and complete one item today. You do not need to adopt the whole stack at once.

---

Practical check

Related reading for outer-layer hygiene: Claude Code efficiency tips. For execution boundaries and in-app browser sandbox behavior, see Desktop in-app browser.

---

FAQ

Q1. Is a harness the same as prompt engineering?

A. No. Prompting shapes instructions. A harness is the full execution machinery: loops, tools, context, verification, and handoffs.

Q2. Is a thicker CLAUDE.md always better?

A. No. Both official and community guidance emphasize stale assumptions and keeping outer config small. Thickness makes root-cause isolation harder.

Practical check

Q3. If I have /goal, do I still need custom hooks?

A. Often start with /goal plus minimal handoff. Add custom hooks only for project-specific Default-FAIL rules or audit needs.

Q4. Can I design only from the Speaker Deck talk?

A. Use it as a vocabulary map. For failure modes, verification separation, and session design, treat Anthropic Engineering as primary.

---

Summary — separate layers, add the minimum

1. Do not conflate model, inner harness, and outer harness
2. For long jobs, prioritize incremental progress and clean handoffs
3. Separate “done” judgment from the builder
4. Add outer settings only after observing a gap; remove them after model upgrades

Harness design is not a contest to collect config files. It is choosing the smallest execution machinery that reduces known failure modes, then keeping it light as models improve. Start today by naming your layer and answering Yes/No on progress log, git, and feature list.