实验背景AI Agent 写代码越来越强但强不等于可靠。同样的模型、同样的提示词为什么有时候一次就过有时候反复翻车答案往往不在模型本身而在你给它的规则和约束。这个实验用 Electron 搭建一个知识库应用壳子跑两次弱 Harness只给一段提示词什么都不准备强 Harness提前准备好 AGENTS.md、feature_list.json、claude-progress.md用结构化方式告诉 Agent 该干什么、怎么验证、什么时候算做完任务定义用 Electron 做一个知识库应用包含四个核心功能编号功能要求kb-001窗口启动npm start后 Electron 窗口正常打开kb-002左侧文档列表左侧面板显示文档列表区域kb-003右侧问答面板右侧面板包含输入框和对话区域kb-004本地数据目录应用启动时创建数据目录包含 documents/、qa/ 子目录Harness 是什么Harness 不是代码是一套告诉 Agent 怎么干活、怎么验证、什么时候算做完的规则文件。这个实验用的 Harness 核心包含三个文件实际仓库中还会配合 init.sh 等辅助脚本AGENTS.md定义 Agent 的核心行为规则- 一次只做一个功能 - 实现后必须运行 npm start 验证 - 不要因为代码已经写了就把功能标记为完成 - 验证证据记录在 feature_list.json 或 claude-progress.md - 一个功能只有在目标行为已实现、npm start 成功、证据已记录才算完成feature_list.json每个功能的唯一事实来源包含验收标准、证据槽位{id:kb-001,title:窗口启动,status:not_started,verification:[运行 npm start,确认 Electron 窗口成功打开,确认窗口标题显示应用名称],evidence:[]}claude-progress.md会话进度日志记录当前状态、已完成功能、已知风险、下一步动作。第一次实验弱 Harness分支p01-baseline提示词用 Electron 做一个知识库应用窗口左边是文档列表区域右边是问答面板区域应用需要创建并使用本地数据目录。仓库状态空的 package.json没有 AGENTS.md没有 feature_list.json过程Agent 自由发挥一次性完成了所有四个功能。代码质量很好UI 布局清晰IPC 通信正确。结果功能状态备注kb-001 窗口启动✅ 完成一次通过kb-002 文档列表✅ 完成左侧 300px 面板kb-003 问答面板✅ 完成右侧 flex 面板kb-004 数据目录✅ 完成目录结构正确应用截图弱 Harness 的问题虽然任务完成了但存在以下问题没有验证证据功能完成了但没有记录怎么验证的、“验证结果是什么”没有风险记录遇到 EPERM 权限问题但没有记录到任何地方没有可接续性下一轮会话必须重新理解代码无法从上次中断的地方继续没有完成定义Agent 不知道什么时候算做完全靠自己判断第二次实验强 Harness分支p01-improved提示词完全相同仓库状态AGENTS.md、CLAUDE.md、init.sh、feature_list.json、claude-progress.md 已就位过程Agent 严格按照 AGENTS.md 的流程执行读取 claude-progress.md→ 确认 kb-001 为最高优先级读取 feature_list.json→ 获取 4 个功能的验收标准发现状态不一致→ feature_list.json 中功能标为 passing但代码已清空先修复基础状态逐功能实现→ 每完成一个功能运行验证记录证据遇到 Blocker→ Windows EPERM 阻止在 userData 目录创建子目录按规则在窄范围修复更新 Harness 文件→ 所有功能标记为 passing记录风险强 Harness 的行为差异以下是 Agent 在关键决策点上的行为重构示意非原始逐字日志# Agent 读到的不一致状态时的反应 feature_list.json 中所有功能标为 passing但 main.js 不存在。 这违反了 AGENTS.md 规则。先修复基础状态。 # 遇到 Blocker 时的反应 EPERM 权限错误。 AGENTS.md 规则窄范围修复不扩大到其他功能。 将数据目录路径改为项目根目录功能行为不变。 # 完成后的动作 更新 feature_list.json - status → passing - evidence 字段填入验证证据 更新 claude-progress.md - 记录风险EPERM - 记录下一步动作结果功能状态证据kb-001 窗口启动✅ passingBrowserWindow 创建index.html 加载kb-002 文档列表✅ passing#left-panel 300pxborder-right 边界kb-003 问答面板✅ passing#right-panel flex:1含输入交互kb-004 数据目录✅ passingdata/documents/ data/qa/ 已创建应用截图对比分析核心指标指标弱 Harness强 Harness备注首次成功启动一次通过三次强 Harness 因主动发现并修复 EPERM 权限问题而多次重启非代码质量问题遗漏项无无过早停止否否验证证据无feature_list.json 结构化证据风险记录无claude-progress.md 记录 EPERM可接续性需重新理解代码读 claude-progress.md 即可状态一致性检查无主动发现并修复不一致深层差异这个实验里两个版本最终都完成了任务UI 效果完全一样。但这不代表 Harness 没用——恰恰相反简单的任务看不出 Harness 的价值复杂的任务看不出 Harness 的边界。真正体现差异的地方1. 状态一致性检查强 Harness 下Agent 发现 feature_list.json 中功能标记为 “passing” 但代码不存在时主动停下来修复基础状态。弱 Harness 下Agent 不会注意到这种不一致会在坏的起点上继续叠加代码。2. Blocker 处理策略强 Harness 下遇到 EPERM 权限错误时AGENTS.md 的窄范围修复规则防止了 Agent 去修改其他无关代码。弱 Harness 下Agent 可能过度修改也可能直接放弃。3. 证据链强 Harness 下feature_list.json 每个功能都有 evidence 字段记录了验证证据。claude-progress.md 记录了风险和下一步动作。下一轮会话直接读这两个文件就能接续不需要重新理解代码。4. 完成定义强 Harness 有明确的完成定义目标行为实现 npm start 成功 证据记录在案。弱 Harness 下Agent 自己判断差不多完成了没有外部验证标准。关键结论1. 简单任务中Harness 的价值是防御性的这次实验任务简单两个版本都完成了。但 Harness 的价值在于防止意外——状态不一致、权限错误、风险遗漏这些在简单任务中可能不致命但在复杂任务中会累积成灾难。2. Harness 解决的是接续问题不是完成问题Agent 的单次执行能力很强但多轮会话之间的接续是短板。Harness 通过 feature_list.json状态和 claude-progress.md上下文让下一轮会话能无缝接续。3. 规则的价值在于约束行为不在于提升质量Harness 不会让 Agent 写出更好的代码但会让 Agent 的行为更可预测、更规范。feature_list.json 的验收标准不是为了让代码更好而是为了让完成有一个客观的判断标准。4. 好的 Harness 是最小可行约束Harness 不是越多越好。AGENTS.md 的核心规则只有几条一次一个功能、必须验证、证据必须记录。过多的规则会让 Agent 过度遵循流程反而降低效率。