sawzhang Harness 方法论工具箱
基于 Anthropic Harness 研究的多 Agent 编排方法论。根据用户请求路由到对应模式：
| 用户说 | 模式 |
|---|---|
| "harness build"、"用harness构建"、"长任务构建" | → 构建模式 |
| "harness qa"、"独立评估"、"评估一下"、"qa check" | → QA 模式 |
| "harness plan"、"规划一下"、"分解为sprint" | → 规划模式 |
| "harness"（无子命令） | → 展示此路由表，询问用户需求 |
核心理念：生成者不能可靠评估自己的工作。分离 Generator 和 Evaluator 角色是质量保证的关键。
构建模式
完整的 Planner→Generator→Evaluator 三阶段循环。适用于多文件、多模块的复杂构建任务。
| 维度 | 直接构建 | Harness 构建 |
|---|---|---|
| 规划 | 边做边想 | Planner 先输出完整规格 |
| 评估 | 自己判断"做完了" | 独立 Evaluator 逐条验证 |
| Context | 一个窗口塞满 | 每个 Sprint 独立 context |
| 失败处理 | 发现问题才修 | 每轮迭代自动检测+反馈 |
Step 1 — 理解需求
用户输入: $ARGUMENTS
阅读构建请求，信息不足则追问：
- 要构建什么？
- 技术栈偏好？（已有项目则读代码判断）
- 什么算"完成"？
Step 2 — Planner 阶段
以项目规划师身份展开请求为完整规格：
- 输出项目概要（1 段话）
- 分解为 Sprint 列表，每个含：标题、描述、验收标准、复杂度
- Sprint 按依赖排序
- 每个 Sprint 在一个聚焦会话内可完成
规划原则：
- 重产品上下文，轻技术细节（避免过度规格化导致级联错误）
- 每个 Sprint 只关注一个特性
- 验收标准必须具体可测试
- 主动寻找可织入 AI 功能的机会
Step 3 — Sprint 循环
对每个 Sprint 执行以下循环（最多 3 轮精炼）：
3a. Generator 阶段
以实现者身份工作：
- 聚焦当前 Sprint 验收标准
- 使用工具实际编写代码
- 完成后总结每个标准如何满足
Context Reset: 每个 Sprint 只携带之前的摘要，不是完整对话：
## 已完成工作
### Sprint 1: 用户认证 [PASSED]
实现了 JWT 登录、注册、密码重置。数据库用 SQLite。
### Sprint 2: REST API [PASSED]
实现了 /users CRUD、/posts CRUD。添加了权限中间件。
3b. Evaluator 阶段
切换为独立 QA 评估者：
- 逐条检查验收标准
- 使用工具验证（运行测试、检查文件、执行命令）
- 严格: 不给部分实现打分
输出结构化评估：
Sprint 2 评估:
- ✅ GET /users 返回 200 → 通过
- ❌ DELETE /users/:id 返回 404 → 路由未实现
总分: 2/4 (0.50) — 未通过
反馈: DELETE 路由缺失；权限中间件需在 app.py 中注册。
3c. 决策
- 通过 → 进入下一个 Sprint
- 未通过 → 将反馈注入下一轮 Generator
- 达到最大轮次 → 记录未通过项，继续下一个 Sprint
Step 4 — 最终报告
## 构建报告
| Sprint | 标题 | 状态 | 轮次 |
|--------|------|------|------|
| 1 | 用户认证 | ✅ PASSED | 1 |
| 2 | REST API | ✅ PASSED | 2 |
| 3 | 前端页面 | ⚠️ PARTIAL | 3 |
已完成: 2/3 Sprint 完全通过
QA 模式
独立 Evaluator，只评估不修复。适用于代码审查、验收测试、质量评估。
Step 1 — 确认验收标准
用户输入: $ARGUMENTS
如果用户提供了标准，直接使用。否则从以下来源推导：
- README / SPEC 文档
- 最近的 git commit
- 代码中的 TODO / FIXME
- 用户描述
输出标准列表，等用户确认后继续。
Step 2 — 逐条验证
对每个标准独立验证：
- 制定测试策略
- 执行验证（实际运行，不是仅看代码）
- 记录结果 + 证据
# 示例: 验证 "GET /users 返回 200"
curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/users
# 期望: 200，实际: 404 → ❌
Step 3 — 评估报告
## QA 评估报告
| # | 标准 | 状态 | 证据 |
|---|------|------|------|
| 1 | 用户可以注册 | ✅ | POST /register 返回 201 |
| 2 | 登录获取 JWT | ✅ | POST /login 返回 token |
| 3 | 未登录返回 401 | ❌ | GET /profile 返回 200（应为 401） |
总分: 2/3 (0.67)
未通过项详细反馈:
- 标准 3: middleware 在 app.py:42 注册但路由顺序有误
- 建议: 将 add_middleware() 移到路由注册之前
评估框架
前端/UI 项目:
| 维度 | 权重 | 说明 |
|---|---|---|
| 设计质量 | 30% | 颜色、排版、布局的整体协调 |
| 原创性 | 25% | 自主决策 vs 模板默认值 |
| 工艺 | 20% | 字体层级、间距、对比度 |
| 功能性 | 25% | 用户能否完成任务 |
后端/API 项目:
| 维度 | 权重 | 说明 |
|---|---|---|
| 正确性 | 40% | 功能按预期工作 |
| 健壮性 | 25% | 错误处理、边界情况 |
| 安全性 | 20% | 认证、授权、输入验证 |
| 性能 | 15% | 响应时间、资源使用 |
规划模式
将简短请求展开为 Sprint 合同列表。适用于复杂项目规划、大任务分解。
Step 1 — 理解上下文
用户输入: $ARGUMENTS
- 阅读请求
- 已有项目则读取
package.json/pyproject.toml/ README - 识别约束条件
Step 2 — 项目概要
一段话：要构建什么、目标用户、核心价值、技术栈。
Step 3 — Sprint 合同
每个合同：
### Sprint N: 标题
**描述**: 这个 Sprint 要做什么（1-3 句）
**验收标准**:
- [ ] 具体可测试的标准 1
- [ ] 标准 2
- [ ] 标准 3
**复杂度**: low / medium / high
**依赖**: Sprint X（如有）
Step 4 — 汇总
## 项目规划: {名称}
### Sprint 路线图
| Sprint | 标题 | 复杂度 | 依赖 | 标准数 |
|--------|------|--------|------|--------|
| 1 | ... | low | - | 3 |
| 2 | ... | medium | S1 | 4 |
### 详细合同
{...}
### 风险与注意事项
{...}
验收标准写法
好 ✅:
- "GET /api/users 返回 JSON 数组，含 id、name、email"
- "运行
pytest tests/全部通过，覆盖率 > 80%"
差 ❌:
- "API 设计合理"
- "界面美观"
Sprint 粒度
- 每个 Sprint 3-6 个标准
- 超过 6 个则拆分
- 排序：基础设施 → 核心功能 → 辅助功能 → 润色
QA 调优注意事项
Anthropic 研究发现 Claude 做 QA 天然很差：
- 发现问题后会说服自己"其实没问题"
- 测试浅表，遗漏边缘情况
- 嵌套深处的 bug 会漏过
对策：
- Evaluator 必须实际运行代码验证，不能仅看代码推断
- 每个标准独立检查，不能笼统通过
- 反馈必须具体可操作（"POST /users 返回 500，错误是 missing column"）
- 不要因代码看起来合理就给通过
通用注意事项
- Sprint 之间通过摘要传递上下文，不累积完整对话
- Generator 和 Evaluator 是独立角色，不混用
- 简单任务（单文件、单功能）不需要 Harness，直接做
- Generator 最多 50 个工具调用轮次，Evaluator 最多 10 个
- 规划阶段只做读取和分析，不修改代码