Harness
从 0 到可验收

为什么工具齐了，AI 还是会错？

装好宿主、写好规则、接上 MCP，只能说明 Agent 拥有了更多输入和动作。它还不等于知道什么不能做，也不等于做完以后有人独立检查。

Harness 的四层结构

不要把 Harness 理解成一份配置文件。它至少包含引导、控制、证据和交付四层，每一层解决不同的失败。

从 0 开始：先做一个能闭环的版本

小白不需要第一天接十个工具。先规定边界，再做一个能执行、能失败、能复查的小循环。

# 最小项目结构
my-harness/
├── CLAUDE.md
├── .agents/skills/
├── .harness/scripts/verify.sh
├── .harness/hooks/
├── .harness/contracts/
├── .harness/tests/fixtures/
└── .harness/failures.md

把 CLAUDE.md 从愿望清单写成规则系统

规则要能被执行、被检查、被更新。真正有用的规则写清触发条件、动作、边界和完成证据。

# 项目工作规则

## 工作范围
- 只修改当前仓库内的源码和配置。
- 生成物放入临时目录，截图验收后删除中间 HTML。

## 危险动作
- 删除、强制推送、覆盖外部平台内容前必须先询问。
- 不使用 `--no-verify` 绕过检查。

## 完成标准
- 运行对应的验证命令并保留退出码。
- 报告修改文件、验证命令、结果和人工边界。

Hook：把关键红线放到模型外

CLAUDE.md 告诉 Agent 规则是什么；Hook 在工具动作真正发生前执行规则。对不可逆动作，只让模型“记住不要做”是不够的。

Subagent 与 Evaluator：不要让执行者给自己打分

主 Agent 负责执行，独立角色负责检查，人负责真实宿主、视觉、事实和外部副作用。独立检查者不接受“我已经完成了”作为证据。

---
name: reviewer
description: 独立检查 Agent 产物，不修改目标文件
---

1. 不接受主 Agent 的“已完成”作为证据。
2. 至少提出 3 个潜在问题，或明确检查范围。
3. 自动化检查给出命令和退出码。
4. 缺证据时返回 partial 或 blocked，不猜测通过。

长任务的高级 Harness

长任务的问题不是模型不会写，而是上下文会增长、状态会丢失、完成标准会变模糊。高级 Harness 用结构化状态替代对一段聊天的依赖。

# 一个 Sprint 的完成门
Sprint N
├── 输入：上一个 checkpoint + 当前目标
├── 动作：限定范围内的实现
├── 检查：正例、反例、Evaluator
├── 输出：产物 + 证据 + 未决风险
└── checkpoint：可恢复状态

失败台账：把失败变成下一次的防护

`failures.md` 不是抱怨区，而是 Harness 的训练数据和回归入口。每条失败都要完成一次“现象到护栏”的转换。

## 2026-08-17 [误删草稿目录]

### 现象
Agent 把“清理旧版本”解释成删除整个 drafts/。

### 根因
- 规则没有写精确删除范围；
- 没有路径边界反例；
- Hook 没有拦截危险删除。

### 防再犯规则
- 删除前先列出目标并逐项确认；
- 递归删除默认 deny；
- 保留一个应阻断、一个应放行的 fixture。

从初级到高级的成熟度路线

分数是摘要，不是质量的替身。升级的本质是增加可以被别人复核的证据。

一条适合小白的实践顺序

每一步都留下一个能失败的例子，再进入下一步。这样你搭的是工程，而不是配置收藏夹。