Harness Design for Long-Running Application Development（整理版）
原始资料: Anthropic Engineering - Harness design for long-running application development created: 2026-06-25 12:49 整理说明: 本版本结合原始笔记和可读取的原始教程重排、补全和翻译，保留常用英文术语。
内容简要概括
这篇文章讨论如何为长时间自主软件开发设计 agent harness，核心思路是用 Planner、Generator 和 Evaluator 分别补足模型在需求扩展、持续实现和自我评估上的短板。作者先从前端设计中的主观质量评估入手，把“好不好看”转化成可评分的 criteria，再把 generator-evaluator 反馈环迁移到 full-stack coding。最重要的结论是：harness 的每个组件都隐含一个关于“模型自己做不好什么”的假设，因此组件要随着模型能力、任务难度和成本收益不断重新评估。
agent harness、Planner、Generator、Evaluator、Playwright MCP、sprint contract、criteria、few-shot examples、visual convergence、context reset、compaction、QA prompt、hard threshold、复杂度取舍、长时间自主开发
目录
- 1. 文章背景与核心问题
- 2. 前端设计：把主观审美转成可评估标准
- 3. Full-stack coding 的三 Agent 架构
- 4. Planner：从短需求生成产品规格
- 5. Generator：按规格和 sprint contract 实现
- 6. Evaluator：用真实交互和硬阈值做 QA
- 7. Sprint contract：在实现前定义完成标准
- 8. 迭代与调参：让 Evaluator 变得更严格
- 9. Harness 复杂度：组件不是越多越好
- 10. 模型升级后的 Harness 简化
- 11. 实践启发
- 12. 可复用模板汇总
1. 文章背景与核心问题
文章关注两个相互关联的问题：
- 如何让 Claude 生成更高质量、更有设计感的 frontend。
- 如何让 Claude 在没有人工持续干预的情况下，完成更长时间、更完整的 application development。
朴素的单 agent 实现容易遇到两个问题。第一，长任务会让模型在 context window 逐渐填满后失去连贯性，甚至提前收尾。早期 harness 用 context reset 配合结构化 handoff 来缓解这个问题；它不同于 compaction，后者会压缩历史上下文，但仍然让同一个 agent 继续带着压缩后的历史工作。
第二，模型自我评估不可靠。尤其是设计类任务没有明确的二元测试，模型很容易高估自己的输出；即使在可验证的软件任务里，模型也可能忽略 bug 或把问题淡化。因此，文章引入独立的 Evaluator，让负责实现的 agent 和负责判断的 agent 分离。
2. 前端设计：把主观审美转成可评估标准
“这个设计漂亮吗？”很难稳定回答；但“这个设计是否符合明确的设计原则？”更容易被模型评估。文章先在 frontend design 场景中建立 generator-evaluator loop，让 Generator 负责产出页面，让 Evaluator 负责依据 criteria 打分和反馈。
2.1 评分标准示例
作者把以下 criteria 同时提供给 Generator 和 Evaluator：
| Criteria | 关注点 | 作用 |
|---|---|---|
Design quality |
颜色、排版、布局、图像和细节是否形成统一整体 | 判断设计是否有清晰的 mood 和 identity |
Originality |
是否有定制化决策，而不是模板、默认组件或常见 AI 生成痕迹 | 鼓励有意识的创意选择 |
Craft |
字体层级、间距、色彩协调、对比度等执行质量 | 检查基础技术和视觉执行是否扎实 |
Functionality |
用户是否能理解界面、找到主操作、完成任务 | 保证可用性独立于审美存在 |
其中 Design quality 和 Originality 权重更高，因为 Claude 默认在 Craft 和 Functionality 上较容易达到基本水平，但在审美风险和原创性上更容易保守。
2.2 Few-shot calibration
Evaluator 需要通过 few-shot examples 校准。示例不只是给一个分数，而要包含详细的 score breakdown，让模型学会什么样的输出应该被判高分、什么样的输出只是表面完整但实际普通。
如果没有校准，Evaluator 往往会过于宽容；而校准后的 Evaluator 更容易稳定地贴近作者的审美偏好和质量标准。
2.3 Playwright MCP 的作用
Evaluator 不应只看静态截图或代码。文章中的 Evaluator 配备了 Playwright MCP，可以像真实用户一样打开页面、点击、截图、观察交互，再对每个 criterion 写 critique。
这点很重要：对 UI 和应用来说，很多质量问题只有在运行时交互中才会暴露，例如主流程不清晰、按钮不可用、状态没有保存、布局在实际 viewport 中浪费空间等。
2.4 Prompt wording 会塑造生成方向
评分标准本身不仅是评价规则，也会变成 Generator 的设计方向。比如在 criteria 中加入类似 “museum quality” 的表述，会把生成结果推向更克制、更艺术、更展览化、更大留白的视觉风格。
这会带来 visual convergence：不同任务的输出逐渐向同一种审美靠拢。它说明 criteria 里的语言需要谨慎设计，因为 evaluator prompt 同时也是 generator 的隐性风格指南。
2.5 迭代不是越多越好
多轮 evaluator feedback 通常会提升输出，但并不保证最后一轮一定最好。后期 Generator 可能为了回应反馈而选择更复杂、更激进的实现，导致 implementation complexity 上升。有时中间轮次比最后一轮更平衡。
因此，迭代次数应该看质量趋势和成本收益，而不是机械地追求更多轮。
3. Full-stack coding 的三 Agent 架构
文章把 frontend design 中的 generator-evaluator 模式迁移到 full-stack coding，并形成三 agent 架构：
| Agent | 主要职责 | 解决的问题 |
|---|---|---|
Planner |
把 1-4 句短 prompt 扩展成完整 product spec | 防止原始需求太短导致 under-scope |
Generator |
按 spec 和 sprint contract 逐步实现应用 | 管理实现范围，保持交付节奏 |
Evaluator |
用 Playwright 和 QA 标准测试应用 | 捕捉真实 bug，弥补模型自评偏乐观 |
这个架构的关键不是“多 agent 一定更好”，而是每个 agent 都对应一个明确的模型短板。如果某个短板在新模型上已经不明显，那么对应组件就可能从必要组件变成成本负担。
4. Planner：从短需求生成产品规格
Planner 的输入通常只有 1-4 句话，但输出应该是一份较完整的 product spec。它的价值在于把模糊需求扩展成可实现、可测试、有产品完整度的目标。
4.1 Planner 应补全的内容
Planner 应该补全：
- 产品目标
- 目标用户
- 核心场景
- 主要功能
- 用户流程
- 高层架构
- 概念级数据模型
- AI features
- 验收标准
- non-goals / constraints
4.2 重点定义“做什么”，避免过度规定“怎么做”
Planner 应该约束 deliverables，而不是写死低层实现细节。
更合适的写法：
用户可以创建、编辑、删除项目。
系统需要保存项目状态。
需要提供可测试的核心工作流。
不合适的写法：
创建 ProjectCard.tsx。
数据库必须有 name、created_at、updated_at 三个字段。
第一个 API 路由必须叫 /api/projects/create。
核心原则：
Planner defines deliverables, Generator decides implementation.
如果 Planner 过早规定错误的技术细节，Generator 可能会照着错误路径实现，导致后续工作连锁出错。因此 Planner 应保持在高层技术设计层面：概念级数据模型、模块职责、验收行为，而不是具体文件结构、函数名、数据库字段或复杂算法细节。
4.3 Scope 要有野心，但不能失控
Planner 不应只规划 toy demo，而要把产品扩展到“像真实应用”的程度。合适的方向是：
- 覆盖核心用户流程。
- 补足必要功能模块。
- 加入能体现产品完整度的高级功能。
- 避免无关功能膨胀。
文章中的 retro game maker 例子里，完整 harness 的 planner 把一句话 prompt 扩展成多 sprint、16-feature 的规格，包含核心 editor、play mode、AI-assisted sprite generator、AI level designer、导出和分享等能力。这让输出比 solo run 更接近完整产品。
4.4 输出结构要稳定
为了让下游 Generator 和 Evaluator 能稳定引用，Planner 的输出最好固定格式，例如：
1. Product Overview
2. Target Users
3. Core Workflows
4. Feature Modules
5. High-level Architecture
6. Conceptual Data Model
7. AI Features
8. Acceptance Criteria
9. Non-goals / Constraints
稳定结构可以减少 downstream agents 的理解成本，也方便后续用文件传递上下文。
5. Generator：按规格和 sprint contract 实现
Generator 负责真正写代码，但它不应该在没有边界的情况下自由扩展。它的工作方式应围绕 spec、当前 sprint 目标和验收标准展开。
5.1 Generator 的基本原则
- 按 spec 工作，不自行发明无关功能。
- 一次只做一个 feature 或 sprint。
- 每轮明确目标、实现范围和验收标准。
- 完成后自我检查，但不能只依赖自我检查。
- 提交前确保应用能运行。
- 使用 git 保存稳定状态。
- 把结果交给
Evaluator测试。
5.2 文件化状态管理
可以用文件记录跨阶段上下文：
| 文件 | 作用 |
|---|---|
PRODUCT_SPEC.md |
说明产品总目标、功能范围、用户流程和验收标准 |
PROJECT_STATE.md |
记录当前实现进度、已完成内容、未完成内容和下一步 |
SPRINT_CONTRACT.md |
定义当前 sprint 的具体交付物和 done criteria |
CONTRACT_REVIEW.md |
由 Evaluator 审查 sprint contract 是否可测、是否符合 spec |
QA_REPORT.md |
记录 Evaluator 的测试结果、失败项和修复建议 |
文件沟通的好处是上下文更稳定，也更容易在 agent 之间交接。
6. Evaluator：用真实交互和硬阈值做 QA
Evaluator 的核心任务不是礼貌点评，而是像 QA 和 code reviewer 一样发现问题。它需要实际运行应用，通过 Playwright MCP 操作 UI，并验证 API、数据库状态和持久化行为。
6.1 评分维度和 hard threshold
每个评分维度都应有 hard threshold。示例：
Product depth >= 7
Functionality >= 8
Visual design >= 7
Code quality >= 7
只要有一项低于阈值，这个 sprint 就失败。hard threshold 的价值在于防止模型把严重问题包装成“小瑕疵”后仍然给出 pass。
6.2 Evaluator 要测试什么
Evaluator 需要测试：
- 核心用户流程是否真实可用。
- UI 操作是否符合预期。
- API 是否返回正确结果。
- 数据库状态是否随操作变化。
- 刷新页面后持久化是否成立。
- 错误输入和边界情况是否被处理。
- spec 和 sprint contract 中的 acceptance criteria 是否逐条满足。
可复用要求：
必须测试边界情况。
必须测试刷新后的持久化。
必须测试错误输入。
必须验证 API 和数据库状态。
文章中的例子显示，Evaluator 能发现非常具体的实现问题，例如 rectangle fill tool 没有正确触发、删除 entity spawn point 的条件判断错误、FastAPI route 顺序导致 /frames/reorder 被错误解析等。这类问题如果只靠代码自评或表面 UI 检查，很容易漏掉。
6.3 Evaluator 也需要被调教
默认状态下，Claude 并不是天然严格的 QA agent。文章观察到早期 Evaluator 会识别出真实问题，却又说服自己这些问题不严重并批准实现；它也容易测试太浅，从而漏掉隐蔽 bug。
因此，Evaluator prompt 需要不断迭代，让它更明确地执行 fail policy。
7. Sprint contract：在实现前定义完成标准
sprint contract 是 Generator 和 Evaluator 在每个 sprint 开始前达成的“完成定义”。它存在的原因是：product spec 往往故意保持高层，不能直接等同于可测试的实现标准。
7.1 工作流程
常见流程：
Generator 写 SPRINT_CONTRACT.md
Evaluator 写 CONTRACT_REVIEW.md
Generator 修改 SPRINT_CONTRACT.md
Evaluator 标记 Approved
Generator 开始实现
这个流程让 Generator 在写代码前先明确本轮要交付什么，Evaluator 也能提前指出“这个 done criteria 不够具体”“这个验收标准无法测试”“这个 sprint 偏离 spec”等问题。
7.2 好的 sprint contract 应具备什么
好的 sprint contract 应该足够具体，使实现者和评估者不需要额外调查就能行动。它应包括：
- 本 sprint 的用户可见目标。
- 明确的 in-scope 和 out-of-scope。
- 需要完成的核心行为。
- 需要验证的 UI、API、数据状态。
- 失败时应判定为 fail 的条件。
- 与产品 spec 的对应关系。
注意：sprint contract 应该把高层用户故事落到可测试行为，但仍不应过度指定文件名、函数名或数据库字段，除非这些细节本身就是产品或兼容性要求。
8. 迭代与调参：让 Evaluator 变得更严格
文章中的 tuning loop 类似调测试策略：
读取 Evaluator 日志
↓
找出它判断不符合作者标准的地方
↓
修改 QA prompt
↓
重新跑
↓
继续观察日志
如果发现 Evaluator 太宽容，可以加入规则：
如果核心功能缺失，不允许 Pass。
如果发现 bug，不要自我淡化。
任何违反 acceptance criteria 的行为都必须记录为 FAIL。
如果发现它测试太浅，可以加入规则：
不要只测试 happy path。
必须主动寻找边界情况、错误输入和持久化问题。
必须通过真实 UI 操作验证核心流程，而不是只读代码。
这说明 Evaluator prompt 本身是一种可迭代资产。它不是一次写完的标准答案，而要通过日志、失败案例和人工偏好持续校准。
9. Harness 复杂度：组件不是越多越好
一个 harness 里的每个设计，其实都隐含一个判断：
模型自己做不好某件事，所以我要加一个组件帮它。
例如：
| Harness 组件 | 隐含假设 |
|---|---|
Planner |
模型直接从短 prompt 开发会 under-scope |
Evaluator |
模型无法可靠自我评估 |
Sprint |
模型无法一次处理完整大任务 |
Context reset |
模型在长上下文里会跑偏或提前收尾 |
Playwright QA |
只读代码无法发现运行时 bug |
所以组件不是越多越好。每增加一个组件，都要问：
这个假设现在还成立吗？
当前模型还需要这个脚手架吗？
它带来的质量提升是否超过成本？
9.1 最简单可行方案原则
文章强调的基本原则是：
先找最简单可行方案，只在必要时增加复杂度。
放到 agent harness 里，就是：
能用单 Agent 解决，就不要上多 Agent。
能用一次 QA 解决，就不要每个 sprint 都 QA。
能用 prompt 约束解决，就不要加复杂 orchestration。
能用模型原生能力解决，就不要保留旧脚手架。
复杂度必须有明确收益，否则会带来额外的成本、延迟、token 消耗和维护负担。
10. 模型升级后的 Harness 简化
文章对比了不同模型能力下 harness 的变化。早期使用 Claude Sonnet 4.5 时，context reset 对长任务很重要，因为模型容易表现出 context anxiety。后来使用 Opus 4.5 构建三 agent 架构，再到 Opus 4.6 时，模型长任务能力、代码审查和调试能力提高，部分脚手架可以被重新评估。
10.1 Removing the sprint construct
作者后来尝试移除 sprint construct，让 builder 在更长连续会话中完成任务，并把 Evaluator 从每个 sprint 后检查改成更少轮次的整体 QA。原因是新模型已经能更好地维持长任务连贯性。
这并不说明 Evaluator 没用了，而是说明它的价值取决于任务是否超出当前模型可靠单独完成的边界：
- 对模型已经能稳定完成的任务，
Evaluator可能变成 overhead。 - 对模型仍处在能力边界附近的复杂任务，
Evaluator仍然能捕捉 last-mile gaps。
文章中的 DAW 例子显示，即使更新后的 harness 更简单，QA 仍然发现了真实问题，例如部分核心交互只是 display-only、音频录制还只是 stub、clip resize 和 split 未实现、效果器可视化不足等。
10.2 Harness 不是固定答案
随着模型能力提升，harness 的组件组合会移动，而不是消失。AI engineer 的工作不是永久保存某个架构，而是不断识别下一组有价值的组合：
- 哪些能力现在可以交给模型原生完成？
- 哪些能力仍需要外部 evaluator 或 specialized agents？
- 哪些新能力因为模型变强才变得可行？
11. 实践启发
这篇文章对构建 long-running coding agent 有几个直接启发。
第一，先观察模型真实 traces，再设计 harness。不要凭想象增加组件，而要从模型在哪些地方失败、失败是否稳定、成本是否值得入手。
第二，把主观标准转成可评估 criteria。无论是视觉质量、产品完整度还是代码质量，越能被清晰描述，越能被 Evaluator 稳定执行，也越能反向约束 Generator。
第三，分离“生成”和“评价”。自我评价天然容易偏乐观，独立 Evaluator 更容易被调成严格 QA。
第四，验收标准要可操作。Acceptance Criteria 和 sprint contract 应该能直接指导测试，而不是停留在“好用”“完整”“美观”这类抽象词。
第五，定期删除不再 load-bearing 的组件。模型升级后，旧 harness 的某些部分可能不再提供足够收益；保留它们会增加复杂度和成本。
12. 可复用模板汇总
12.1 Planner 输出结构模板
1. Product Overview
2. Target Users
3. Core Workflows
4. Feature Modules
5. High-level Architecture
6. Conceptual Data Model
7. AI Features
8. Acceptance Criteria
9. Non-goals / Constraints
12.2 Sprint contract 文件流
Generator 写 SPRINT_CONTRACT.md
Evaluator 写 CONTRACT_REVIEW.md
Generator 修改 SPRINT_CONTRACT.md
Evaluator 标记 Approved
Generator 开始实现
12.3 Evaluator hard threshold 示例
Product depth >= 7
Functionality >= 8
Visual design >= 7
Code quality >= 7
12.4 QA prompt 强化规则
如果核心功能缺失，不允许 Pass。
如果发现 bug，不要自我淡化。
任何违反 acceptance criteria 的行为都必须记录为 FAIL。
不要只测试 happy path。
必须主动寻找边界情况、错误输入和持久化问题。
必须通过真实 UI 操作验证核心流程，而不是只读代码。