long-running-agent-harness（长期运行的 Agent 线束）

Long-running agent harness

Plan and scaffold work so an AI agent can make incremental, verifiable progress across many context windows. Flow: design doc (human + AI) → Initializer once (creates feature list, runbook, backlog, progress) → Coding agent in a loop until done. The implementation backlog defines one work unit per session and helps identify milestones for human check-in. Based on Anthropic: Effective harnesses for long-running agents.

Problem

Agents work in discrete sessions with no memory. Without structure they tend to: (1) try to do too much in one go and leave half-implemented, undocumented state; (2) declare the job done too early; (3) leave bugs or undocumented progress. A harness gives each new session a clear picture of state and one concrete unit of work.

Workflow overview

The top-level agent invokes the Initializer and each Coding session as sub-agents, passing the relevant prompt each time (no need to copy prompts into .cursor/rules/). Use whatever mechanism Cursor provides to spawn a sub-agent or new task and pass the prompt content (e.g. the contents of the Initializer or Coding prompt file).

Phase 0: Design doc (human + AI)

• Goal: One design doc that defines scope, acceptance criteria, and enough context for the feature list and runbook.
• Process: Human and AI iterate (in chat or a shared doc). AI suggests structure and content; human refines. Optionally use the doc-coauthoring skill for the design doc.
• Output: Design doc at _working/design.md. This is the input to the Initializer (which creates the feature list and other harness artifacts).

Two-phase execution (Initializer + Coding agent)

Initializer (run once)

Run the Initializer prompt (e.g. via sub-agent). It:

1. Reads the design doc and any existing context.
2. Creates or refreshes in _working/: agent-runbook.md, implementation-backlog.md, agent-progress.md, feature_list.yaml, and optionally init_<app\>.sh.
3. Does not implement features. Output: list of artifacts and the recommended first coding target.

Coding agent (every session, until done)

Run the Coding agent prompt (e.g. via sub-agent). Each session:

1. Session start: If any of _working/agent-progress.md, _working/agent-runbook.md, _working/implementation-backlog.md, _working/feature_list.yaml are missing → run Initializer first.
2. Get bearings: Read _working/agent-progress.md → _working/implementation-backlog.md → _working/feature_list.yaml → _working/design.md → _working/agent-runbook.md → recent git log.
3. Pick one unit: At most one page/feature from the backlog that still has failing (or unimplemented) criteria.
4. Implement: Implement only that unit. Add tests. Run lint/typecheck/tests from the runbook; fix failures.
5. Feature list: Set passes: true only for criteria verified this session.
6. Handoff: Append a "Session N" block to progress; commit; leave repo runnable.

Loop: After each session, if not all features pass and the user has not stopped, run the Coding agent again (new sub-agent). Repeat until the next milestone or all features pass.

Milestone check-in: At important points (e.g. end of a logical work-unit group, or when the design doc defines a milestone), pause the coding loop. Check in with the human: summarise progress, show what’s done and what’s next. The human may revise the plan, adjust the current implementation, or change priorities. When the human is satisfied, re-run the Initializer (to refresh backlog and progress from any plan changes), then resume the Coding agent loop until the next milestone or completion.

Artifact layout

All harness artifacts live under _working/ (scratch space for the agent; see workspace rules).

Detailed templates and full prompt bodies live in references/REFERENCE.md.

Rules to enforce in prompts

• Incremental: One work unit per Coding session. If a unit is large, split across sessions and set "continue [unit X]" as next target.
• Clean state: Each session ends with a commit and a progress update. No partial broken scaffolding.
• Feature list discipline: Never remove or reorder items. Never set passes: true without running the corresponding verification.
• Runbook as source of truth: Coding agent must use runbook commands for verify; do not guess or invent commands.

Feature list format (YAML example)

acceptance_tests:
  - description: log in as admin redirects to app (root / dashboard)
    category: auth
    passes: false
    steps:
      - Start a new browser session
      - Navigate to the login page
      - Log in as the admin user
      - Verify redirect to /
  - description: invalid resource id shows 404 or clear error
    category: edge-case
    passes: false
    steps: [...]

The feature list is YAML only; when updating passes, preserve the rest of the file structure.

Reference

• Directory layout, artifact templates, and prompt bodies for sub-agents: references/REFERENCE.md.
• Anthropic: Effective harnesses for long-running agents.