Solo Agent Harness：跨 Context Window 的渐进式开发框架（整理版）

原始资料: Effective harnesses for long-running agents 配套实现: Autonomous Coding Agent Demo 补充资料: Prompting best practices：multi-context-window workflows created: 2026-07-17 18:03 整理说明: 本版本结合原始笔记与可读取的教程重排、补全和翻译，保留常用英文术语；讨论对象是跨多个串行会话持续工作的单 Agent harness。

内容简要概括

长时间运行的 Coding Agent 面临的核心问题不是单次推理能力，而是每个新的 context window 都可能丢失项目状态，从而重复劳动、留下未记录的半成品，或过早宣布完成。一个实用的 Solo Agent Harness 将首次会话与后续会话分工：Initializer Agent 建立可恢复的开发环境和可验证的功能清单，Coding Agent 每次只推进一个功能并留下可接续的状态。

要让这套机制可靠，功能状态、启动方式、进度记录和 Git 历史必须成为项目内的显式工件；每次新会话都先验证基线，再开始新增工作。这里的状态传递面向串行会话，不能直接解决并行 Agent 的任务拆分、冲突合并和共享资源协调问题。

Solo Agent Harness、context window、Initializer Agent、Coding Agent、feature_list.json、init.sh、claude-progress.txt、incremental progress、smoke test、end-to-end testing、Git、idempotency、browser automation

目录

• 1. 问题：为什么长任务会在新会话中失控
• 2. 两阶段 Harness：初始化与持续编码
• 3. 让状态可恢复的四类工件
• 4. 后续 Coding Agent 的标准启动与收尾流程
• 5. 测试与完成标准
• 6. 适用边界与安全约束
• 可复用模板汇总

1. 问题：为什么长任务会在新会话中失控

复杂软件任务通常跨越多个 context window。即使 harness 支持上下文压缩，新的 Agent 实例仍可能无法准确获知上一次会话修改了什么、测试是否通过，以及剩余工作是什么。常见后果如下。

“干净状态”不只是没有报错，而是下一位开发者可以直接开始新功能：当前修改可理解、已验证、已记录，并且能从 Git 历史中恢复。

2. 两阶段 Harness：初始化与持续编码

2.1 Initializer Agent：第一次会话建立工作台

首次会话不应急于实现大量业务功能，而应把后续会话需要的上下文固化到仓库中。其主要职责是：

1. 阅读需求规格并拆成完整的端到端功能清单。
2. 创建 feature_list.json，让每项功能包含描述、验证步骤和 passes: false 初始状态。
3. 建立项目结构、依赖安装和开发服务器启动方式。
4. 编写 init.sh，并保证它是确定性、幂等的命令：重复执行不会破坏已有环境。
5. 创建进度文件（例如 claude-progress.txt），说明当前状态、已知问题和下一步。
6. 建立 Git 仓库并完成初始 commit，使后续会话能检查基线和回退变更。

2.2 Coding Agent：后续会话只做可验证的增量

后续会话的职责不是重新规划整个项目，而是从已有工件中恢复现场，选择最高优先级且尚未通过的一项功能，完成实现、端到端验证、状态更新和 commit。一次只推进一个功能可以降低上下文耗尽时留下半成品的概率，也让失败更容易定位和回退。

3. 让状态可恢复的四类工件

3.1 功能清单：feature_list.json

功能清单是“什么算完成”的单一事实来源。每个条目应描述用户可观察到的结果和验证步骤，而非只写内部实现任务。

Copy{
  "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
}

• category：功能所属类别，便于排序和统计。
• description：以用户视角描述功能结果。
• steps：端到端验证步骤；它们应能支撑“通过”这一判断。
• passes：仅在验证完成后从 false 改为 true。不要为了让进度变好看而删除、改写或跳过测试步骤。

JSON 比自由文本更不容易被 Agent 随意改写；它也便于脚本统计已通过功能数。配套 quickstart 中会读取该文件并显示通过数量，因此格式错误会破坏恢复流程。

3.2 启动脚本：init.sh

init.sh 的目标是把“如何让项目可运行”变成可执行知识。它应安装或检查必要依赖、启动开发服务器，并清楚输出访问地址或日志位置。

幂等性尤其重要：脚本需要能安全地重复运行。例如，已经安装的依赖不应导致失败；已存在的配置不应被意外覆盖；重复启动前应能识别或处理已有开发进程。每个新会话先阅读并运行该脚本，避免凭记忆猜测项目命令。

3.3 进度文件：claude-progress.txt

进度文件负责传递 Git diff 中不易看出的信息。建议每次会话记录：

• 本次完成了什么，以及对应的功能条目。
• 实际执行过哪些测试、结果如何。
• 当前已知的 bug、限制或待排查项。
• 下一个会话应从哪里继续，以及是否需要先修复基线。

它不是长篇工作日志；重点是让新的 context window 能快速恢复方向，减少重新调查环境的时间。

3.4 Git 历史

描述清楚的 Git commit 既是检查点，也是恢复机制。每个可验证的增量完成后提交，使 Agent 能用 git log 了解最近工作、用 git diff 审查当前状态，并在必要时回到已知可用版本。进度文件与 Git 历史互补：前者说明意图和验证，后者保存精确改动。

4. 后续 Coding Agent 的标准启动与收尾流程

4.1 启动前：先恢复现场并验证基线

Copypwd
git status --short
git log --oneline --decorate -10
git diff --stat

• pwd：确认当前工作目录；Agent 的可编辑范围往往受该目录约束。
• git status --short：快速查看未提交修改，避免覆盖上一次会话或用户留下的工作。
• git log --oneline --decorate -10：查看最近 10 个 commit 及分支/标签指向，理解刚完成的工作。
• git diff --stat：仅查看改动规模和涉及文件，用于判断未提交修改是否符合预期。

随后依次阅读进度文件、功能清单和 init.sh，启动项目并执行一个核心 smoke test。若基线已失败，应优先修复或记录该问题；在损坏的基线上继续叠加新功能会放大排查成本。

4.2 实施与收尾：只推进一个功能

推荐的会话流程如下：

1. 确认工作目录和 Git 状态。
2. 阅读 claude-progress.txt、最近 Git 历史和 feature_list.json。
3. 运行 init.sh，启动开发环境。
4. 执行核心 smoke test，确认基线正常。
5. 选择一个最高优先级且 passes: false 的功能。
6. 实现该功能，并执行与其 steps 对应的端到端测试。
7. 仅在测试确实通过后，将该条目的 passes 更新为 true。
8. 在进度文件写入实现、验证结果、已知限制和下一步。
9. 检查 diff，使用描述性的 commit message 提交干净状态。

5. 测试与完成标准

单元测试和 curl 检查有价值，但它们并不总能验证用户真正看到的行为。对于 Web 应用，应在条件允许时使用 browser automation 或 computer use 完成真实交互路径：打开页面、输入内容、触发操作、检查页面反馈与持久化结果。

功能只能在以下条件同时满足时标记为通过：

• feature_list.json 中定义的关键步骤已实际执行。
• 基线 smoke test 仍通过，没有引入无关回归。
• 结果以用户可观察的方式成立，而不只是代码能编译或接口返回 200。
• 本次改动、验证和遗留风险已写入进度文件并提交到 Git。

6. 适用边界与安全约束

本笔记的设计针对串行的多个 Agent 会话：每个新会话读取同一组状态工件后继续推进。它不能直接处理并行 Agents 之间的依赖图、文件写入冲突、共享测试环境竞争和结果合并；这些问题需要额外的任务拆分、隔离工作区和协调协议。

运行 autonomous coding harness 时还应明确工具权限。配套 quickstart 使用操作系统级沙箱、项目目录文件限制和 Bash 命令白名单进行分层防护。无论采用哪种实现，都应让 Agent 只拥有完成当前任务所需的最小权限，并避免把密钥写入项目文件或 commit。

可复用模板汇总

Initializer Agent 提示词骨架

Copy你是项目的 Initializer Agent。先阅读需求规格，不要尝试一次实现所有功能。

1. 建立 feature_list.json：将需求拆成可端到端验证的功能；每项包含 description、steps 和 passes: false。
2. 创建可重复运行且幂等的 init.sh，用于安装/检查依赖并启动开发环境。
3. 创建 progress 文件，记录项目初始状态、启动命令和后续会话应遵循的流程。
4. 初始化 Git，并完成一个只包含脚手架与状态工件的初始 commit。
5. 运行最小 smoke test，确认后续 Coding Agent 有可工作的基线。

完成后说明：已创建的工件、基线测试结果，以及最高优先级的未完成特性。

Coding Agent 提示词骨架

Copy你是持续开发的 Coding Agent。请先恢复项目状态，再做一个可验证的增量。

1. 运行 pwd；检查 git status、最近 Git 历史和当前 diff。
2. 阅读 progress 文件、feature_list.json 和 init.sh。
3. 启动项目并执行核心 smoke test；若基线失败，先修复它。
4. 只选择一个最高优先级且 passes: false 的功能。
5. 实现该功能，并按功能清单完成端到端验证。
6. 只有验证通过后才能将 passes 改为 true；不要删除或弱化既有测试。
7. 更新 progress 文件，记录改动、测试结果、已知限制和下一步。
8. 审查 diff 并创建描述性的 Git commit，使仓库保持可接续的干净状态。