Long Running Harness

Long-Running Agent Harness

This skill is the discipline for making progress on a project across many context windows, distilled from Anthropic's engineering post on effective harnesses for long-running agents. Compaction and context management alone are not sufficient: an agent given a high-level prompt (e.g. "build a claude.ai clone") tends to either attempt to one-shot the whole app and exhaust context mid-implementation, or — in a later session — see partial progress and declare the job done. The fix is structural: one initializer session that scaffolds the environment, then many coding sessions that each complete exactly one verified feature and hand off cleanly. Anthropic's framing: "engineers working in shifts, where each new engineer arrives with no memory of what happened on the previous shift."

When to use

Use this skill when:

• A build or task will span multiple context windows — hours or days of agent work with fresh context each session.
• You are the FIRST session on a greenfield project meant for multi-session work → run the initializer procedure.
• You are resuming a project that already has init.sh / feature_list.json / claude-progress.txt → run the coding-session procedure. Never re-run the initializer on a scaffolded project.
• You are designing a loop/harness that will spawn repeated agent sessions on one codebase.

Do NOT use when the task comfortably fits one context window — the scaffolding overhead is not worth it — or for work with no persistent codebase to hand off.

Rules

Architecture

1. Split the run into two logical roles: an initializer agent (first session only) and a coding agent (every session after). They are the same model, same system prompt, same tools — only the initial user prompt differs. Do not rely on compaction to carry a multi-hour build; it isn't sufficient on its own.

Initializer session (runs once)

1. Set up the environment; do not build the product. Produce: an init.sh script that starts the development server, a feature_list.json, a claude-progress.txt progress log, and an initial git commit recording what files were added.
2. Expand the user's high-level prompt into feature_list.json: a comprehensive file of end-to-end feature requirements. Breadth matters — the claude.ai-clone example contained over 200 features. Each entry has the shape:

``json { "category": "functional", "description": "New chat button creates a fresh conversation", "steps": ["Navigate to main interface", "Click the 'New Chat' button", "Verify a new conversation is created", "Check that chat area shows welcome state", "Verify conversation appears in sidebar"], "passes": false } ` Every entry starts with "passes": false` — the file is the visible roadmap of remaining work.

1. Use JSON, not Markdown, for the feature list. The model is less likely to inappropriately change or overwrite JSON files than Markdown files; JSON gets treated as data, prose gets rewritten.

Every coding session — startup protocol

1. Begin with the fixed orientation sequence, before touching code:
2. Run pwd — you may only edit files in this directory.
3. Read the git logs (git log --oneline -20) and claude-progress.txt to get up to speed on recent work.
4. Read feature_list.json and choose the highest-priority feature whose passes is false.
5. Run init.sh to start the development server.
6. Run a basic end-to-end smoke test (e.g. start the server and use the browser automation tool to exercise a core flow) BEFORE implementing anything new. This catches an inherited broken state early instead of building on top of it.

Every coding session — work rules

1. Work on exactly one feature per session. This is the direct counter to the do-too-much-at-once failure mode; incremental single-feature sessions keep the codebase in a recognisable state at each handoff.
2. Edit feature_list.json ONLY by changing a passes field. Use — and obey — strongly-worded constraints: "It is unacceptable to remove or edit tests because this could lead to missing or buggy functionality."
3. Set "passes": true only after self-verifying the feature end-to-end with browser automation (the reference implementation used the Puppeteer MCP): take the steps a user would take, watch the UI respond. Unit tests and curl commands passing is NOT sufficient — agents that stopped there repeatedly marked broken features complete. Testing tools that see the real UI let the agent find bugs not obvious from the code alone.
4. Know the verification blind spot: browser-native alert modals are invisible through the Puppeteer MCP, and features relying on them tended to be buggier. Treat such features as unverified by browser automation alone.
5. End the session in clean state: code appropriate for merging to a main branch — no major bugs, orderly, well-documented, so the next session can start a new feature without cleaning up an unrelated mess. Concretely: commit to git with a descriptive message and write a summary of the session's progress into claude-progress.txt.
6. Use git as the recovery mechanism. Descriptive incremental commits let any session revert bad code changes and recover a known-good working state instead of debugging forward.

Failure-mode map

| Problem | Initializer's countermeasure | Coding agent's countermeasure | |---|---|---| | Premature "project done" | Feature list with end-to-end descriptions | Read feature list each session; work one incomplete feature | | Buggy, undocumented state left behind | Git repo + progress notes file | Read notes/git logs; smoke-test at start; commit + update notes at end | | Feature marked complete without testing | Feature list with passes flags | Self-verify end-to-end before flipping passes | | Tokens wasted rediscovering how to run the app | Write init.sh | Run init.sh at session start |

Checklist

Initializer session (once, at project start):

• [ ] init.sh written — starts the dev server
• [ ] feature_list.json written — comprehensive end-to-end features expanded from the user prompt, all "passes": false
• [ ] claude-progress.txt created
• [ ] Initial git commit made recording added files
• [ ] No product features implemented

Every coding session:

• [ ] pwd — confirm working directory
• [ ] Read claude-progress.txt
• [ ] git log --oneline -20
• [ ] Read feature_list.json; pick highest-priority passes: false entry
• [ ] Run init.sh
• [ ] End-to-end smoke test passes before new work (fix/revert first if not)
• [ ] Implement ONE feature only
• [ ] Verify it end-to-end with browser automation, not just unit tests
• [ ] Flip only the passes field, only after verification
• [ ] Commit with a descriptive message
• [ ] Update claude-progress.txt with a progress summary

Anti-patterns

• One-shotting the app: implementing many features in one session until context runs out, leaving half-done, undocumented work.
• Premature victory: seeing existing progress in the repo and declaring the project finished instead of checking feature_list.json for remaining passes: false entries.
• Marking complete without proper testing: flipping passes after unit tests or curl checks alone, without end-to-end UI verification.
• Editing the feature list beyond passes: removing or rewording tests, descriptions, or steps.
• Markdown feature lists: the model overwrites prose more readily than JSON.
• Skipping the startup smoke test: building new features on top of an inherited broken state.
• Relying on compaction alone to bridge sessions instead of git history plus progress notes.
• Ending a session with uncommitted or undocumented changes, forcing the next session to burn tokens reconstructing what happened.

Source

• Effective harnesses for long-running agents — https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents — 2025-11-26 (Justin Young, Anthropic Engineering; code examples in the accompanying quickstarts repository, autonomous-coding)

Distilled from the official document(s) above on 2026-08-12. If this skill and the source disagree, trust the source.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Archive228
• Source: Archive228/lab-skills
• License: MIT

Install and usage instructions live in the source repository linked above.