143 lines
5.9 KiB
Markdown
143 lines
5.9 KiB
Markdown
---
|
||
name: walkinglabs-harness
|
||
description: "Practical Harness Engineering patterns from the walkinglabs course. Implements the 5-subsystem model (Instruction, Tools, Environment, State, Feedback) with concrete templates: feature_list.json, claude-progress.md, init.sh, session-handoff.md, clean-state-checklist.md. Use when setting up project harness infrastructure, session continuity, or implementing the init phase pattern."
|
||
---
|
||
|
||
# WalkingLabs Harness — 实战模式
|
||
|
||
> 来源：[Learn Harness Engineering](https://walkinglabs.github.io/learn-harness-engineering/zh/)
|
||
|
||
## 🎯 核心概念
|
||
|
||
### 能力鸿沟（Capability Gap）
|
||
模型在基准测试上的表现 vs 真实任务上的表现之间的落差。SWE-bench Verified 50-60% 不意味着真实任务也能达到这个成功率。
|
||
|
||
### Harness 诱导失败
|
||
模型本身能力足够，但因为执行环境有结构性缺陷而失败。Anthropic 对照实验：同一个 prompt + 同一个模型，裸跑 20 分钟 $9 失败，带 harness 跑 6 小时 $200 成功。
|
||
|
||
### 验证缺口
|
||
Agent 对自己输出的信心评估和实际正确性之间的偏差。"做完了" ≠ 真的做完了。
|
||
|
||
### 上下文焦虑
|
||
当 Agent 感觉上下文快满了，会匆忙结束当前工作，跳过验证，选简单方案而非最优方案。
|
||
|
||
## 🔧 5 子系统模型
|
||
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ 指令（Instruction）— AGENTS.md / CLAUDE.md │
|
||
│ 工具（Tools）— shell / 文件 / 测试 │
|
||
│ 环境（Environment）— 依赖 / 服务 / 版本 │
|
||
│ 状态（State）— PROGRESS.md / 功能清单 │
|
||
│ 反馈（Feedback）— test / lint / build │
|
||
└─────────────────────────────────────────────┘
|
||
```
|
||
|
||
**量化价值的方法：** 控制变量排除法 — 保持模型不变，逐个移除子系统，看哪个移除后性能下降最多。
|
||
|
||
## 📋 标准工作循环
|
||
|
||
```
|
||
开始会话
|
||
├→ 1. Init（初始化）
|
||
│ ├── pwd 确认目录
|
||
│ ├── 读取 claude-progress.md / feature_list.json
|
||
│ ├── git log --oneline -5
|
||
│ └── 运行 ./init.sh
|
||
│
|
||
├→ 2. Select（选择功能）
|
||
│ └── 只选一个未完成功能
|
||
│
|
||
├→ 3. Implement（实现）
|
||
│ └── 一次只做一个功能，不扩大范围
|
||
│
|
||
├→ 4. Verify（验证）
|
||
│ ├── 运行验证命令
|
||
│ └── 有可运行证据才标记完成
|
||
│
|
||
└→ 5. Cleanup（清理）
|
||
├── 更新 claude-progress.md
|
||
├── 更新 feature_list.json
|
||
├── 运行 clean-state-checklist.md
|
||
├── git commit
|
||
└── 留下干净重启路径
|
||
```
|
||
|
||
## 📁 必需模板文件
|
||
|
||
| 文件 | 用途 | 必需 |
|
||
|---|---|---|
|
||
| `feature_list.json` | 功能状态唯一事实来源 | ✅ |
|
||
| `PROGRESS.md` | 会话进度和已验证状态 | ✅ |
|
||
| `init.sh` | 统一启动与验证入口 | ✅ |
|
||
| `session-handoff.md` | 跨会话交接摘要 | 可选 |
|
||
| `clean-state-checklist.md` | 结束时清洁检查 | ✅ |
|
||
| `evaluator-rubric.md` | 评审评分表 | 可选 |
|
||
| `quality-document.md` | 质量快照 | 可选 |
|
||
|
||
## 📐 约束设计
|
||
|
||
### DoD（完成定义）
|
||
一个功能只有在以下条件都满足时才算完成：
|
||
1. 目标行为已经实现
|
||
2. 要求的验证真的跑过
|
||
3. 证据记录在 feature_list.json 或 PROGRESS.md
|
||
4. 仓库仍能按标准启动路径重新开始工作
|
||
|
||
### 规则
|
||
- 一次只做一个功能
|
||
- 不要因为"代码已经写了"就把功能标记为完成
|
||
- 不要悄悄改弱验证规则
|
||
- 优先依赖仓库里的持久化文件，而不是聊天记录
|
||
|
||
## 🔄 会话交接
|
||
|
||
每次会话结束前必须运行 `clean-state-checklist.md`：
|
||
```
|
||
□ 标准启动路径仍然可用
|
||
□ 标准验证路径仍然可运行
|
||
□ 当前进度已记录到进度日志
|
||
□ 功能状态真实反映 passing 和未验证的边界
|
||
□ 无半成品步骤处于未记录状态
|
||
□ 下一轮会话无需人工修复即可继续
|
||
```
|
||
|
||
## 📊 评审评分表
|
||
|
||
| 维度 | 问题 | 0-2分 |
|
||
|---|---|---|
|
||
| 正确性 | 行为是否符合目标功能？ | |
|
||
| 验证 | 检查是否真的跑过并留下证据？ | |
|
||
| 范围纪律 | 是否基本保持在选定功能范围内？ | |
|
||
| 可靠性 | 结果能否在重启后继续工作？ | |
|
||
| 可维护性 | 代码和文档是否清楚到可交接？ | |
|
||
| 交接准备度 | 新会话能否只靠仓库内工件继续推进？ | |
|
||
|
||
## 📚 12 讲大纲速查
|
||
|
||
| 讲 | 标题 | 核心观点 |
|
||
|---|---|---|
|
||
| L01 | 模型强 ≠ 执行可靠 | 能力鸿沟、harness 诱导失败 |
|
||
| L02 | Harness 到底是什么 | 5 子系统模型 |
|
||
| L03 | 仓库即记录系统 | Agent 看不到的就不存在 |
|
||
| L04 | 一个大文件不行 | 100 行 AGENTS.md，更多放 docs/ |
|
||
| L05 | 跨会话连续性 | 缺少持久化，30 分钟+ 任务失败率激增 |
|
||
| L06 | Init 需要独立阶段 | 启动检查标准化 |
|
||
| L07 | Agent 越界/半途而废 | 显式范围边界 + 完成定义 |
|
||
| L08 | 功能清单是原语 | feature_list.json 机器可读 |
|
||
| L09 | Agent 过早宣告胜利 | 自评 ≠ 验证，分开"干活"和"检查" |
|
||
| L10 | 端到端测试改变结果 | 集成测试发现单元测试漏掉的问题 |
|
||
| L11 | 可观测性属于 Harness | 日志、追踪、指标在 Harness 内 |
|
||
| L12 | 每次会话留下干净状态 | 技术债持续还，不攒到爆雷 |
|
||
|
||
## ⚠️ 常见陷阱
|
||
|
||
| 陷阱 | 表现 | 解决 |
|
||
|---|---|---|
|
||
| 无 Init 阶段 | Agent 直接开工，不知道环境状态 | 强制运行 init.sh |
|
||
| 无功能清单 | Agent 凭记忆工作 | 维护 feature_list.json |
|
||
| 无进度文件 | 跨会话从头探索 | 维护 PROGRESS.md |
|
||
| 不跑验证 | Agent 自己说了算 | 验证命令写在 AGENTS.md 里 |
|
||
| 不清理 | 技术债指数级累积 | 每次结束运行 clean-state-checklist |
|
||
| 同时做多个功能 | 上下文混乱，范围蔓延 | 一次做一个 |
|