【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本篇指南基于 learn-harness-engineering 仓库中 Project 01 的课程设计讲解如何通过两次运行对比实验量化验证一个核心论断让能力强大的 AI Agent 完成任务难点往往不在任务本身而在于缺少约束与验收规则的引导。第一次运行只给 Agent 一段裸提示词第二次运行让仓库中预置AGENTS.md、init.sh、feature_list.json组成的最小 harness最后对比两次的表现差异。读完本文你将掌握最小 harness 的完整结构、每条规则背后的设计意图、以及如何用源码与验收证据判断 Agent 是否真正完成了任务。实验要回答的问题本实验对应的课程背景是两讲关键内容为什么能力强的 Agent 仍然会失败 与 harness 到底是什么。实验要构建的最小 Electron 知识库应用本身并不复杂一个窗口、左侧文档列表、右侧问答面板、一个本地数据目录。真正的难点在于——让 Agent 在没有外部约束的情况下稳定、完整、可验证地交付这些功能。实验通过同一个 Agent、同一个任务、两种环境的对照设计来揭示差异运行环境准备观察重点第一次仅提供任务提示词裸 prompt无任何额外结构Agent 在没有规则约束时能完成多少、偏离任务有多远第二次仓库中预置最小 harnessAGENTS.mdinit.shfeature_list.json规则与验收清单如何让同一任务变得具体、可验证需要注意的是本课程场景将两次运行之间的重新研究/准备间隔设定得较短作为教学示例而不是作为固定测量结果——对比的目的是观察 harness 带来的行为差异而非产出可复现的基准数据。实验工具清单运行本实验需要以下工具Claude Code 或 Codex二选一即可但两次运行必须使用同一个工具保证对照变量只有 harness 有无Git用分支隔离两次实验便于事后用git diff对比两次产出Node.js Electron项目技术栈需提前安装依赖计时器分别记录两次运行的耗时作为对比的辅助维度。使用仓库中已准备好的项目仓库中已经为本次实验准备好了完整素材路径为 projects/project-01/分为starter/与solution/两个目录目录内容用途 / 对比要点starter/弱 harness 起点只有 task-prompt.md 作为任务描述没有AGENTS.md、feature_list.json把提示词交给 Agent测量它在没有额外结构时能完成什么solution/同一产品切面但带显式 harness 产物AGENTS.md、CLAUDE.md、init.sh、feature_list.json、claude-progress.md对比规则与验收检查如何让同一任务变得具体、可验证两边的src/目录结构一致均包含 Electron 主进程、preload 桥接层、React 渲染层与 service 业务逻辑层且都带有示例文档数据 data/sample-documents/。区别只在 harness 产物本身。第一次运行裸提示词环境进入starter/目录将 task-prompt.md 交给 Agent。这份提示词的完整内容只有一句话# Task Build an Electron app that can show documents and answer questions.这段描述蕴含了三个典型问题正是本实验想暴露的验收标准缺失show documents and answer questions 没有定义什么叫完成Agent 可能做到一半就自行宣布胜利边界约束缺失没有说明 Electron 分层、安全配置、数据目录位置Agent 可能自由发挥把逻辑写进渲染进程、关闭contextIsolation或把数据存在任意位置任务范围缺失没有列出具体的 feature 清单Agent 可能遗漏功能比如不做本地数据目录也可能过度发挥引入无关依赖或功能。启动后给 Agent 计时观察它产出的代码、运行结果与耗时记录在分支baseline上作为对照组。第二次运行最小 harness 环境切回主分支或新分支harness这次使用 solution/ 作为工作目录。该目录已预置了最小 harness其核心由三件套组成最小 harness AGENTS.mdinit.shfeature_list.jsonAGENTS.md把规则写进 Agent 的启动上下文AGENTS.md 是 Agent 每次会话首先读取的规则文件。它定义了五个层次的内容启动规则Startup Rules要求 Agent 在写任何代码之前按顺序完成完整阅读本文件阅读 docs/ARCHITECTURE.md 理解 Electron 分层结构阅读 docs/PRODUCT.md 理解功能需求运行bash init.sh验证项目可干净构建失败则先修复构建错误阅读feature_list.json查看所有功能当前状态。Electron 分层边界Layer Boundaries明确规定主进程、preload、渲染层、service 四层各自的权利与禁忌。例如渲染层绝不导入 Node.js 模块fs、path、electronpreload 是主进程与渲染层之间唯一的桥梁所有文件系统访问必须经由 service 层发生在主进程。约定Conventions启用 TypeScript 严格模式、使用命名导出、IPC 通道名统一在 src/shared/types.ts 的IPC_CHANNELS中定义一次、渲染层禁止同步 I/O。完成定义Definition of Done一个 feature 完成需要同时满足npm run check编译零错误、npm run dev能启动并看到窗口、该 feature 在feature_list.json中状态为pass并附有证据、代码遵守分层边界、正常运行无控制台错误。功能清单协作方式feature_list.json是项目进度的唯一事实来源source of truth每个 feature 有pass/fail/not-started三种状态实现后更新状态并附证据阻塞时置fail并写明原因且永远不允许从清单中删除 feature。此外 solution/ 中还提供了 CLAUDE.mdClaude Code 专用规则入口与 claude-progress.md会话进度记录作为对AGENTS.md的补充保证多轮会话间的连续性。init.sh把环境可用变成可执行命令init.sh 是一个带set -euo pipefail的 bash 脚本克隆仓库或恢复工作时运行依次执行三步echo [1/3] Installing dependencies... npm install echo [2/3] Running type checks... npm run check echo [3/3] Building project... npm run build三步全部通过后输出 Init complete并提示npm run dev启动应用。它的价值在于把项目能不能跑从 Agent 的自由判断变成一条确定性命令——AGENTS.md的启动规则第 4 条强制 Agent 先执行它任何构建问题都会在写业务代码之前暴露。feature_list.json把验收变成机器可读的证据feature_list.json 定义了本项目的四个具体 feature以及每条对应的预期验收证据feature id名称描述预期证据evidencewindow-launchWindow LaunchElectron 打开具有正确尺寸与 preload 脚本的 BrowserWindownpm run dev启动 1200x800 窗口contextIsolationtrue且nodeIntegrationfalsedocument-listDocument List Panel左侧边栏展示已导入文档含空状态提示DocumentList 组件在无文档时渲染空状态有数据时渲染文档卡片question-panelQuestion Panel底部输入条接收问题并通过 IPC 提交QuestionPanel 渲染文本输入与 Ask 按钮回车或点击时提交到window.knowledgeBase.qa.askdata-directoryData DirectoryPersistenceService 创建并管理userData/knowledge-base-data目录PersistenceService 构造函数调用ensureDirectories()创建 data、documents、index 三个子目录这四条 feature 恰好覆盖了裸提示词中那句 show documents and answer questions 的全部隐性要求——窗口能启动、文档能展示、问题能提交、数据有落盘位置。源码佐证feature 与验收证据的落地实现feature_list.json中的每条证据都可以在源码中找到对应实现这正是它可验证的原因。window-launch对应 src/main/main.ts 的createWindow()窗口以width: 1200, height: 800最小 800x600创建webPreferences明确设置contextIsolation: true、nodeIntegration: false并挂载preload/preload.js——与证据描述逐字对应。data-directory对应 src/services/persistence-service.ts构造函数接收app.getPath(userData)/knowledge-base-data作为数据目录见main.ts的initializeServices()并在构造时调用ensureDirectories()用fs.mkdirSync(..., { recursive: true })递归创建data、documents、index三个子目录。该服务同时提供原子化 JSON 写入writeJson先建目录再写文件、文本读写、文件拷贝与删除等能力是 docs/ARCHITECTURE.md 中数据存储方案documents-meta.json、content/、chunks/、index/、qa-history.json的底层实现。document-list 与 question-panel对应渲染层组件src/renderer/components/DocumentList.tsx 与 src/renderer/components/QuestionPanel.tsx它们不直接访问 Node.js而是通过 preload 暴露的window.knowledgeBase类型化 APIdocuments、indexing、qa与主进程通信——这正是AGENTS.md分层边界在代码层面的落实。完整的分层与数据流说明见 docs/ARCHITECTURE.md渲染层 → preloadcontextBridge.exposeInMainWorld→ipcRenderer.invoke(IPC_CHANNELS.*)→ 主进程registerIpcHandlers()→ service 层DocumentService / IndexingService / QaService / PersistenceService→ 返回渲染层更新状态。功能需求与产品约束三栏布局、仅支持.txt/.md、单文件上限 10 MB、本地 mock QA 无 LLM 集成见 docs/PRODUCT.md。对比维度与预期差异两次运行结束后用git diff对比两个分支的产出并从以下维度分析任务具体性裸 prompt 环境中Agent 需要自行推断文档列表问答面板数据目录这些概念harness 环境中四个 feature 与证据描述直接写死Agent 无需猜测完成可验证性裸 prompt 环境只能依赖 Agent 的自我声明判断完成harness 环境中feature_list.json要求每条 feature 附带可核对的证据并可用npm run check/npm run dev客观验证越界行为AGENTS.md的四层边界直接约束 Agent 的代码组织减少渲染层导入 Node 模块关闭安全隔离这类常见越界遗漏与过度发挥feature 清单防止 Agent 漏掉data-directory这类看不见的隐性需求同时也把范围锁死避免无关扩展耗时与返工用计时器数据对比两次运行的总时长与中途返工次数构建失败、反复修改——这也是本实验设定较短重新研究/准备间隔作为示例的原因差异体现在行为模式而非精确的基准数字。实验注意事项控制变量两次运行必须使用同一个 Agent 工具分支隔离 git diff保证可回溯harness 需在运行前就位第二次运行的AGENTS.md、init.sh、feature_list.json应预先提交在仓库中而不是由你在运行中临时创建否则就违背了环境 vs 提示词的对照设计验收以证据为准不要轻信 Agent 的已完成声明逐一核对feature_list.json中四条 feature 的证据是否能在源码与运行结果中复现本实验的边界这是教学性对比实验两次运行间隔较短结果用于理解 harness 的作用机制而非作为性能或成功率基准。通过亲手跑完两次实验你会直观理解同样的 Agent、同样的任务有 harness 与没有 harness 的差别不在于模型能力而在于任务是否被转化成一套可执行、可验证、有边界的工程契约——这正是后续项目中逐步升级 harness多会话连续性、增量索引、运行时可观测性等的起点。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐从只给提示词到最小 Harness在 learn-harness-engineering 中复现 Project 01 的对照实验从只给提示词到最小 Harness在 learn harness engineering 中复现 Project 01 的对照实验 本指南完整讲解 lLearn Harness Engineering 实战项目 01仅 Prompt 与规则先行Minimal Harness到底差多少Learn Harness Engineering 实战项目 01仅 Prompt 与规则先行Minimal Harness到底差多少 本篇技术指南围绕从 prompt 到 harnesslearn-harness-engineering 五子系统模型与实战落地从 prompt 到 harnesslearn harness engineering 五子系统模型与实战落地 导读 harness驾驭/夹具一词在上一篇解锁黑苹果配置新高度OCAT如何让OpenCore管理变得简单高效下一篇如何用OBS计时器提升直播效果5个实用技巧分享创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考