Stop Resetting Your Agents: Building Long-Running Engineering Harnesses
TL;DR: Long-running AI agents fail because they lack persistence across context windows. By using a specialized “Initializer Agent” to scaffold state and a “Coding Agent” that commits incremental progress to git, developers can build complex systems that span days without context rot.
The “Shift Worker” Problem in AI
Imagine a software team where every engineer arrives for their shift with total amnesia. They have no memory of the codebase, no record of what was implemented ten minutes ago, and no idea what the priorities are. This is exactly how most AI agents operate today when tasks exceed a single context window.
Standard “compaction” (summarizing the conversation) isn’t enough. When an agent tries to “one-shot” a complex app, it eventually hits the context wall, leaves half-baked code, and the next session is forced to spend precious tokens just guessing what happened.
Architecture of a High-Persistence Harness
To solve this, Anthropic’s engineering team developed a dual-agent harness that treats AI development like a marathon, not a sprint.
1. The Initializer Agent
The first session is never about coding. It’s about scaffolding. The Initializer Agent is tasked with:
- Creating an
init.shscript to boot the environment. - Initializing a
gitrepository to track history. - Generating a
claude-progress.txtfile as a persistent memory log. - Building a comprehensive
feature_list.json.
2. The Coding Agent
Every subsequent session uses the Coding Agent. Instead of trying to finish the project, this agent is restricted to working on exactly one feature at a time, ensuring that the environment is always left in a “clean state” (ready for a hypothetical main branch merge) before the context window ends.
Feature Lists: Why JSON is Better for Agents
One of the most practical insights from the Anthropic research is the shift from Markdown to JSON for requirement tracking.
While humans love Markdown, agents tend to be over-zealous with formatting, often overwriting entire sections or deleting “unnecessary” notes. By using a strictly structured feature_list.json, the agent is forced to interact with requirements as data. Each feature has a passes: false field that only changes once verification is complete.
{
"category": "functional",
"description": "User can open a new chat and see response",
"passes": false
}Git as the Ultimate Memory Buffer
We often think of git as a version control tool for humans, but for agents, it is a safety net. By requiring the agent to commit progress with descriptive messages, the harness allows the agent to:
- Recover working states if a hallucination breaks the build.
- Provide context to the next agent instance through the commit log.
- Maintain a clean diff, making it easier for the model to see exactly what changed.
Verification: Puppeteer and the End-to-End Trap
A major failure mode for coding agents is “false completion”—declaring a feature done because the code looks right, even if it fails at runtime.
The Anthropic harness solves this by integrating Puppeteer MCP. The agent doesn’t just run unit tests; it opens a headless browser, clicks the “New Chat” button, and verifies that the UI actually responds. If the end-to-end test fails, the agent is prohibited from marking the feature as passed in the JSON log.
Comparison: Compaction vs. State-Harness
| Feature | Standard Compaction | Anthropic State-Harness |
|---|---|---|
| Persistence | Volatile (Summary-based) | Durable (File/Git-based) |
| Task Scope | Tries to “One-Shot” | Incremental (One feature/session) |
| Verification | Guesswork / Unit tests | End-to-End (Puppeteer) |
| Memory Recovery | High token cost (Re-reading) | Low token cost (git log) |
| Failure Mode | Half-implemented “Vibe” code | Clean, documented commits |
FAQ
Q: Does this work with any LLM? A: While designed for the Claude Agent SDK, these principles (JSON logs, Git commits, Initializer prompts) are model-agnostic and will improve any long-running agentic workflow.
Q: Isn’t running an Initializer Agent expensive? A: Actually, it saves tokens in the long run. By spending tokens upfront to define a structured path, subsequent sessions avoid the “context rot” that leads to redundant re-implementations.
Q: What is a “clean state” in this context? A: A clean state means the code has no major bugs, is orderly, and is well-documented. It mimics a state that is ready to be merged into a production branch.
Q: Why Puppeteer specifically? A: For web apps, browser automation is the only way to catch visual regressions or state-management bugs that unit tests often miss. It forces the agent to experience the app as a user would.
Q: Can this be used for non-coding tasks? A: Yes. The same harness logic—Initializer for requirements, Progress file for memory—can be applied to scientific research, financial modeling, or legal document drafting.
The Engineering Conclusion
The era of “vibe coding” where we hope the agent finishes in one go is ending. To build production-grade software with AI, we must treat agents like senior engineers: give them a project management structure, a version control system, and a rigorous testing harness. Stop treating the context window as a constraint and start treating it as a shift.