harness-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Multi-Agent Harness Design

多Agent框架设计

Источники:

Anthropic Engineering — "Harness design for long-running apps"
OpenClaw-RL paper (arxiv 2603.10165) — personal agent verification
DenisSergeevitch/repo-task-proof-loop — execution protocol with durable proof

См. также:

references/proof-loop-research.md

— детали paper + repo mapping

来源:

Anthropic Engineering — 《面向长期运行应用的框架设计》
OpenClaw-RL论文（arxiv 2603.10165）—— 个人Agent验证
DenisSergeevitch/repo-task-proof-loop — 带有持久化验证的执行协议

另请参阅：

references/proof-loop-research.md

— 论文细节与仓库映射

Когда нужен harness, а когда хватит solo agent

何时需要框架，何时单Agent足够

Сигнал	Solo agent	Harness
Scope	Одна фича, bug fix, refactor	Full-stack app, multi-feature product
Длительность	< 30 мин	1-6+ часов
Качество	Baseline достаточно	Нужен polish, originality, craft
Стоимость	~$5-15	~$100-200+
Проверка	Manual review	Automated evaluation + Playwright

Правило: Evaluator оправдан когда задача за пределами reliable solo performance. Не фиксированное yes/no — зависит от complexity tier.

信号	单Agent	框架
范围	单个功能、Bug修复、重构	全栈应用、多功能产品
时长	<30分钟	1-6+小时
质量	基础水平即可	需要打磨、原创性、工艺性
成本	~$5-15	~$100-200+
验证	人工审核	自动化评估 + Playwright

规则： 当任务超出单Agent可靠性能范围时，评估器的存在才合理。没有固定的是非标准——取决于复杂度层级。

Архитектура: Three-Agent System

架构：三Agent系统

1. Planner (Планировщик)

1. 规划器（Planner）

Расширяет 1-4 предложения пользователя в детальную спецификацию
Амбициозный scope — находит возможности для AI-фич
НЕ over-specify реализацию — только what, не how
Вписывает AI features в продукт органично

将用户的1-4句话扩展为详细规格说明
目标宏大的范围——挖掘AI功能的落地可能性
不要过度指定实现细节——只定义做什么，不定义怎么做
将AI功能有机融入产品

2. Generator (Генератор)

2. 生成器（Generator）

Реализует фичи итеративно
Включает self-evaluation перед handoff (но она ненадёжна — см. ниже)
Работает в рамках Sprint Contract

迭代式实现功能
在交付前包含自我评估（但可靠性不足——详见下文）
在Sprint契约的约束下工作

3. Evaluator (Оценщик)

3. 评估器（Evaluator）

Независимый от генератора — отдельный контекст, отдельный промпт
Валидирует через Playwright MCP — скриншоты, навигация, тесты
Откалиброван через few-shot примеры
Ловит то, что self-evaluation пропускает

与生成器相互独立——拥有独立上下文和独立提示词
通过Playwright MCP进行验证——截图、导航、测试
通过少量示例完成校准
捕捉自我评估遗漏的问题

Sprint Contract Pattern

Sprint契约模式

Перед каждой итерацией:

1. Planner определяет фичу и user story
2. Generator и Evaluator ДОГОВАРИВАЮТСЯ о:
   - Что значит "done" для этой фичи
   - Конкретные testable success criteria
   - Что НЕ входит в scope
3. Generator реализует
4. Evaluator валидирует по контракту
5. Если не пройдено → конкретный feedback → повтор с п.3

Контракт = мост между user stories и implementation. Без него evaluator судит по своим критериям, generator не знает что проверять.

每次迭代前：

1. 规划器确定功能和用户故事
2. 生成器与评估器就以下内容达成一致：
   - 该功能的“完成”标准是什么
   - 具体可测试的成功准则
   - 哪些内容不属于当前范围
3. 生成器实现功能
4. 评估器根据契约进行验证
5. 若未通过→给出具体反馈→回到步骤3重复

契约 = 用户故事与实现之间的桥梁。没有契约的话，评估器会按自身标准判断，生成器则不清楚需要验证什么。

Generator-Evaluator: Почему раздельно

生成器-评估器：为何要分离

Self-evaluation bias

自我评估偏差

Модели уверенно хвалят свою работу — даже когда качество посредственное. Это не баг модели, а свойство: генератор оптимизирован на producing, не на judging.

模型会自信地夸赞自己的工作——即使质量平庸。这不是模型的缺陷，而是固有属性：生成器的优化目标是产出内容，而非评判内容。

Решение: Independent evaluator

解决方案：独立评估器

Другой system prompt с calibrated skepticism
Few-shot примеры с детальными score breakdowns
Тестирует через browser, не через чтение кода
Конкретные failure criteria, а не общие "looks good"

带有校准后怀疑态度的独立系统提示词
包含详细分数拆解的少量示例
通过浏览器而非代码阅读进行测试
明确的失败准则，而非模糊的“看起来不错”

Калибровка оценщика (QA Tuning Loop)

评估器校准（QA调优循环）

1. Evaluator выдаёт оценку
2. Ты проверяешь: согласен ли с оценкой?
3. Расхождение → обновляешь QA промпт
4. Типичные проблемы:
   - Superficial testing, пропускает edge cases
   - Premature approval посредственной работы
   - Слишком строгие критерии → бесконечные итерации
5. Повторяешь пока evaluator judgment ≈ твой judgment

1. 评估器给出评分
2. 你检查：是否同意该评分？
3. 若存在分歧→更新QA提示词
4. 典型问题：
   - 表面化测试，遗漏边缘场景
   - 过早批准质量平庸的工作
   - 标准过于严格→无限循环迭代
5. 重复直到评估器的判断≈你的判断

Quality Criteria Framework (для фронтенда)

质量标准框架（面向前端）

4 измерения, каждое 0-10:

4个维度，每个维度0-10分：

1. Design Quality — Целостность

Дизайн ощущается как единое целое, а не коллекция частей?

Интеграция color, typography, layout, imagery
Consistent visual language

2. Originality — Уникальность

Штраф за:

Template layouts, library defaults
AI slop patterns: purple gradients over white cards
"Telltale signs of AI generation"
Cookie-cutter структуры

3. Craft — Техническое мастерство

Typography hierarchy
Spacing consistency
Color harmony, contrast ratios
Pixel-perfect alignment

4. Functionality — Работоспособность

Пользователь завершает задачу без угадывания?

Все интерактивные элементы работают
Нет stub features
Error states обработаны

1. 设计质量 — 整体性

设计是否给人浑然一体的感觉，而非零散组件的集合？

颜色、排版、布局、图像的整合
一致的视觉语言

2. 原创性 — 独特性

以下情况会被扣分：

模板化布局、库默认样式
AI生成的刻板模式：白色卡片上的紫色渐变
“AI生成的明显痕迹”
千篇一律的结构

3. 工艺性 — 技术熟练度

排版层级
间距一致性
色彩和谐度、对比度
像素级精准对齐

4. 功能性 — 可用性

用户无需猜测即可完成任务？

所有交互元素正常工作
没有占位功能（stub features）
错误状态已处理

Влияние формулировок на генерацию

标准表述对生成结果的影响

Фразы в criteria прямо влияют на вывод генератора:

"museum quality" → visual convergence к одному стилю
"best designs" → перфекционизм за счёт creativity
Тестируй формулировки — они стируют модель ДО оценки

标准中的表述会直接影响生成器的输出：

“博物馆级质量”→视觉风格趋向统一
“最佳设计”→为追求完美牺牲创意
测试表述方式——它们会在评估前引导模型的方向

Контекст-менеджмент

上下文管理

Context Degradation

上下文退化

Модели теряют coherence по мере заполнения context window.

Context reset > Compaction:

Compaction сохраняет continuity, но не даёт чистый лист
Reset + structured handoff artifact = лучший баланс
Handoff artifact = документ с state, decisions, progress

随着上下文窗口被填满，模型会失去连贯性。

上下文重置 > 压缩：

压缩能保持连续性，但无法提供“空白画布”
重置+结构化交付工件=最佳平衡
交付工件=包含状态、决策、进度的文档

Context Anxiety

上下文焦虑

Модели (особенно Sonnet) начинают сворачивать работу раньше времени — думают что контекст кончается.

Решение: clean context resets
Opus 4.6: проблема значительно уменьшена

模型（尤其是Sonnet）会提前结束工作——它们认为上下文即将耗尽。

解决方案：干净的上下文重置
Opus 4.6：该问题已显著缓解

Structured Handoff

结构化交付

При context reset передавать:

- Что уже сделано (с конкретными файлами/строками)
- Какие решения приняты и почему
- Что осталось сделать
- Текущие проблемы и blockers
- Sprint contract для текущей итерации

上下文重置时需传递：

- 已完成的工作（含具体文件/代码行）
- 已做出的决策及原因
- 剩余待完成任务
- 当前存在的问题与阻塞点
- 当前迭代的Sprint契约

Assumption Testing

假设测试

"Every component in a harness encodes an assumption about what the model can't do on its own"

“框架中的每个组件都隐含着一个假设：模型无法独立完成某件事”

Принцип: предположения устаревают

原则：假设会过时

Модели улучшаются → scaffolding requirements снижаются
Sprint decomposition нужно было для Sonnet → Opus 4.6 может без него
Стратегия: убирать компоненты по одному, измерять влияние

模型不断改进→对脚手架的需求降低
Sonnet曾需要Sprint拆分→Opus 4.6无需此步骤
策略：逐个移除组件，衡量影响

Simplification Loop

简化循环

1. Текущий harness работает? Да →
2. Убери один компонент (напр. sprint decomposition)
3. Качество упало? Да → верни. Нет →
4. Повтори с другим компонентом
5. Остановись на минимальном harness для текущей задачи

1. 当前框架是否正常工作？是→
2. 移除一个组件（例如Sprint拆分）
3. 质量下降了？是→恢复组件。否→
4. 对其他组件重复此操作
5. 保留当前任务所需的最小框架

Реальные failure modes (пойманные evaluator'ом)

真实失败模式（被评估器捕获）

Rectangle fill tool ставит тайлы только на endpoints drag, вместо заполнения области
Delete key handler требует два условия, когда нужно одно
FastAPI route matching: "reorder" матчится как integer frame_id
Audio recording: stub без mic capture
Missing clip resize/split operations
Effect visualizations как числовые слайдеры вместо графики
Display-only features без интерактивности
Missing instrument panels
Unimplemented recording functionality

矩形填充工具仅在拖拽端点处放置 tiles，而非填充整个区域
删除按键处理器需要两个条件，实际只需一个
FastAPI路由匹配：“reorder”被匹配为整数类型的frame_id
音频录制：无麦克风捕获功能的占位实现
缺少剪辑调整大小/分割操作
效果可视化使用数值滑块而非图形
仅展示无交互功能的特性
缺少仪器面板
未实现录制功能

Инструментарий

工具集

Claude Agent SDK

Handles agent orchestration + compaction автоматически
Manages context growth across long sessions
Рекомендуемый стек для production harnesses

自动处理Agent编排与压缩
管理长会话中的上下文增长
生产级框架推荐技术栈

Playwright MCP

Evaluator навигирует запущенное приложение
Скриншоты перед grading
Тестирует UI features, API endpoints, database states

评估器导航至运行中的应用
评分前截图
测试UI功能、API端点、数据库状态

Gotchas

注意事项

Language shapes output: формулировки в criteria сдвигают генератор ДО обратной связи от оценщика. "Museum quality" → convergence, "experimental" → divergence
Creative leaps happen late: в итерации 9 — стандартный dark theme, в итерации 10 — CSS 3D perspective room. Не останавливай цикл слишком рано
Cost scales with iteration: каждый round ≈ $20-40. 5 rounds = $100-200. Budget accordingly
Evaluator needs tuning: первая версия QA промпта почти всегда слишком мягкая. Планируй 3-5 итераций калибровки
Self-evaluation is seductive: генератор БУДЕТ говорить "всё отлично" — не верь, проверяй через independent evaluator

语言表述影响输出：标准中的表述会在评估器反馈前引导生成器。“博物馆级质量”→风格趋同，“实验性”→风格发散
创意突破往往出现在后期：第9次迭代是标准深色主题，第10次迭代出现CSS 3D透视空间。不要过早终止循环
成本随迭代次数递增：每轮≈$20-40。5轮=$100-200。需合理规划预算
评估器需要调优：初始版本的QA提示词几乎总是过于宽松。需规划3-5次校准迭代
自我评估具有迷惑性：生成器会说“一切完美”——不要相信，通过独立评估器进行验证

Troubleshooting

故障排查

Симптом	Причина	Решение
Evaluator всё одобряет	Промпт слишком мягкий	Добавь few-shot с detailed score breakdowns, конкретные failure criteria
Generator не улучшается	Feedback слишком абстрактный	Evaluator должен давать конкретные файлы/строки/проблемы
Бесконечные итерации	Criteria невыполнимы	Пересмотри контракт, снизь планку или split задачу
Context degradation	Длинная сессия без reset	Structured handoff + clean context reset
Все итерации выглядят одинаково	Criteria слишком узкие	Расширь пространство, убери "museum quality" формулировки
Evaluator ловит мелочи, пропускает крупное	Wrong priority в промпте	Restructure: critical → high → medium → cosmetic

症状	原因	解决方案
评估器全部批准	提示词过于宽松	添加带有详细分数拆解的少量示例、明确的失败准则
生成器无改进	反馈过于抽象	评估器需给出具体的文件/代码行/问题
无限迭代	标准无法实现	重新审视契约，降低标准或拆分任务
上下文退化	长时间会话未重置	结构化交付+干净的上下文重置
所有迭代结果雷同	标准过于狭窄	扩展范围，移除“博物馆级质量”这类表述
评估器纠结细节，忽略重大问题	提示词优先级错误	重构优先级：关键→高→中→ cosmetic（ cosmetic保留英文）

harness-design

Original

Translation

Multi-Agent Harness Design

多Agent框架设计

Когда нужен harness, а когда хватит solo agent

何时需要框架，何时单Agent足够

Архитектура: Three-Agent System

架构：三Agent系统

1. Planner (Планировщик)

1. 规划器（Planner）

2. Generator (Генератор)

2. 生成器（Generator）

3. Evaluator (Оценщик)

3. 评估器（Evaluator）

Sprint Contract Pattern

Sprint契约模式

Generator-Evaluator: Почему раздельно

生成器-评估器：为何要分离

Self-evaluation bias

自我评估偏差

Решение: Independent evaluator

解决方案：独立评估器

Калибровка оценщика (QA Tuning Loop)

评估器校准（QA调优循环）

Quality Criteria Framework (для фронтенда)

质量标准框架（面向前端）

4 измерения, каждое 0-10:

4个维度，每个维度0-10分：

Влияние формулировок на генерацию

标准表述对生成结果的影响

Контекст-менеджмент

上下文管理

Context Degradation

上下文退化

Context Anxiety

上下文焦虑

Structured Handoff

结构化交付

Assumption Testing

假设测试

Принцип: предположения устаревают

原则：假设会过时

Simplification Loop

简化循环

Реальные failure modes (пойманные evaluator'ом)

真实失败模式（被评估器捕获）

Инструментарий

工具集

Claude Agent SDK

Claude Agent SDK

Playwright MCP

Playwright MCP

Рекомендуемый стек

推荐技术栈

Gotchas

注意事项

Troubleshooting

故障排查