Deep Dive into Harness Design for Long-Running Agents: Reading Anthropic's Engineering Blog

> Based on the Anthropic Engineering Blog "Effective Harnesses for Long-Running Agents" (Nov 26, 2025), with commentary inspired by a Chinese-language close-reading series.

The Core Conflict: Timescale vs. Memory Scale

Anthropic pinpoints the central engineering challenge for AI agents: complex tasks may take days, but the context window fragments work into disconnected sessions.

| Dimension | Human Engineer | AI Agent | |-----------|---------------|----------| | Work duration | Weeks or months | Fragmented by context windows | | Memory continuity | Naturally maintained | Restarts each session | | State recovery | Reopen IDE and continue | Must "guess" what happened before | | Progress awareness | Intuitive | Prone to misjudgment |

Anthropic offers a vivid analogy: imagine a software project staffed by shift engineers, where each new engineer arrives with no memory of the previous shift. Even frontier models like Opus 4.5, looping through multiple context windows in the Claude Agent SDK, cannot build a production-grade web app from a high-level prompt like "build a claude.ai clone" alone.

Two Failure Modes

1. Trying to do too much at once: The agent attempts a one-shot build, exhausts its context mid-implementation, and leaves behind half-finished work and undocumented state. The next session wastes time reconstructing basics. 2. Prematurely declaring victory: Late in the project, the agent sees partial progress and announces completion—while many features remain unimplemented or broken.

What a Harness Really Is

"Harness" here means not a restraint but a structured framework that channels the model's computation into purposeful, goal-directed action. It acts as an orchestration layer, an engineering contract between agents and their environment, and a state bridge across context windows.

Importantly, context compaction alone is not sufficient: compressed summaries lose key details and implicit assumptions, so the next agent cannot fully recover working state.

Dual-Agent Architecture: Initializer + Coding Agent

Phase 1: Initializer Agent (runs once)

• feature_list.json: Expands the high-level prompt into 200+ concrete features, each with acceptance steps and a "passes": false flag. JSON is chosen over Markdown because models are less likely to accidentally modify it; agents may only change the passes field.
• init.sh: A one-command script to launch the dev environment.
• claude-progress.txt: A working log passing memory across sessions.
• Git repository: Version control with an initial commit.

Phase 2: Coding Agent (loops per context window)

Each session follows a standard flow:

1. Get bearings: pwd, read progress file and feature list, git log --oneline -20 2. Sanity check: run init.sh, execute basic end-to-end tests 3. Pick one feature from the list 4. Implement incrementally 5. Verify end-to-end with Puppeteer MCP browser automation 6. Leave clean state: git commit + update progress file

"Clean state" means code quality ready to merge to main: no major bugs, clean code, ready for the next feature.

Testing: Why Unit Tests Are Not Enough

Anthropic observed a counterintuitive result: agents that wrote unit tests and curled the dev server still missed end-to-end functional defects. A 200 response doesn't mean the frontend renders correctly. The fix: Puppeteer MCP Server gives agents "the user's eyes"—real browser control, screenshots, and interaction simulation.

Limitations: native browser alert modals can't be captured, some visual details go unrecognized, and e2e testing is slower and more token-expensive than unit tests.

Failure Modes Mapped to Solutions

| Failure Mode | Initializer Prevention | Coding Agent Correction | |--------------|------------------------|--------------------------| | Premature victory declaration | feature_list.json | Read list each session, pick one incomplete feature | | Bugs / undocumented progress | Git repo + progress notes | Read notes/git log, run baseline tests; commit and update notes at end | | Marking features done too early | feature_list.json | Verify thoroughly before marking "passing" | | Time spent figuring out how to run the app | init.sh | Read init.sh at session start |

Parallels with Human Engineering Practice

| Human Practice | Agent Mechanism | Problem Solved | |----------------|-----------------|----------------| | PRD / requirements docs | feature_list.json | Unclear goals, scope creep | | Standups / work logs | claude-progress.txt | Information asymmetry | | Git version control | commit history | Traceability, rollback | | README / env docs | init.sh | Onboarding cost | | Layered testing | Puppeteer e2e tests | Quality verification | | Small PRs | One feature at a time | Lower complexity, fast feedback |

The core insight: agent engineering problems are a microcosm of software team collaboration problems.

Open Questions

• Single generalist vs. multi-agent: Anthropic notes it is unclear whether one universal coding agent or specialized multi-agent architectures (planner, generator, evaluator, tester, cleanup) perform better. This echoes Martin Fowler's "Harness Engineering" concept.
• Cross-domain generalization: Findings are optimized for full-stack web development; scientific research, financial modeling, and long-form content creation need validation.
• Deeper challenges: information loss in compaction (possible hierarchical memory), quality decay over long runs, multi-agent coordination complexity, and evolving acceptance criteria.

Practical Takeaways for Developers

1. Don't rely on context compaction alone—it extends single sessions, not cross-session continuity. 2. Explicit state files (like claude-progress.txt) are necessities, not optimizations. 3. Prefer structured formats: JSON over Markdown, since models are less likely to tamper with them. 4. Enforce incremental constraints—one feature per session. 5. Invest in end-to-end testing to give agents the user's perspective. 6. Standardize environment startup with scripts like init.sh.

Conclusion

Agent development is shifting from a model-capability-driven to an engineering-framework-driven paradigm. Explicit state management beats implicit compaction; incremental constraints beat free-form work; end-to-end verification beats local tests; and 50 years of software engineering practice is the ultimate inspiration for agent harnesses.

If the model is the racehorse, the harness is the track, saddle, reins, and race plan. No matter how fast the horse, it cannot win a long race without a harness.

References:

• Anthropic Engineering Blog. (2025, Nov 26). *Effective harnesses for long-running agents*. https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
• Martin Fowler. *Harness Engineering*. https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html
• Anthropic quickstart example: github.com/anthropics/claude-quickstarts/tree/main/autonomous-coding
• Anthropic. *Claude 4 prompting guide — multi-context window workflows*.