从 Core Beliefs 到可落地的 Harness 工程：learn-harness-engineering 中的 Agent 优先设计信条

【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本篇技术指南以docs/ja/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.md中的七条核心信条为骨架结合仓库内的设计文档索引、repo-template 模板、系列讲座与实践项目源码逐条拆解每一条信条背后的工程原理、落地方案与验证手段。读完本文你将理解仓库即系统之记录AGENTS.md 是路由器而非百科全书验证证据胜过自信等信条如何在真实项目中转化为可执行的配置、检查清单与工作流并能直接用仓库中的模板与清单改造自己的 Agent 工作区。一、七条信条全景Agent 优先的工程世界观core-beliefs.md全文不足十行却是整个 repo-template 设计体系的价值锚点。它定义了Agent 优先agent-first的操作信条与持久化项目规范被 设计文档索引 列为唯一已验收Accepted的设计文档。七条信条如下#信条一句话解读对应讲座1仓库是 Agent 的系统之记录system of recordAgent 的一切事实来源只有仓库Lecture 032AGENTS.md是路由器不是百科全书入口文件只做路由不堆内容Lecture 043验证证据比自信更重要用可执行验证替代 Agent 的感觉Lecture 094一个受边界约束的任务胜过多个半成品WIP1一次只做一件事Lecture 075重复出现的人类反馈应沉淀为可复用的 harness 规则把口头批评固化为机制Lecture 126清理与简化是交付的一部分而非事后补丁干净状态是会话完成的必要条件Lecture 127Agent 在仓库中无法发现的事实视为操作上不可用没写进仓库 不存在Lecture 03这七条信条并非孤立的口号而是一条完整逻辑链信条 1 定义了事实的来源边界仓库信条 2 决定了事实的组织方式路由而非堆积信条 3 决定了事实的验证方式证据而非自信信条 4 决定了工作的推进方式单任务信条 5 决定了规则的进化方式反馈机制化信条 6 决定了状态的收尾方式干净交付信条 7 则是前六条的验收标准可发现性。二、信条一仓库是 Agent 的系统之记录The repository is the system of record for agents.Lecture 03 给出了这一信条的根本论证Agent 只有三个输入来源——系统提示与任务描述、仓库中的文件内容、工具执行输出。团队散落在 Slack、Confluence、Jira 里的架构决策或者某位资深工程师脑子里的隐性约束Agent 一律看不到。它不能去问同事也不能翻聊天记录。2.1 知识可见性缺口Knowledge Visibility Gap如果项目的知识总量中只有一部分落进了仓库两者之差就是知识可见性缺口。缺口越大Agent 失败率越高。Lecture 03 给出了一个可操作的估算方法列出项目中所有重要决策与约束逐项标记在仓库内 / 在仓库外仓库外条目所占比例就是你的可见性缺口。仓库内提供了现成的检测清单system-of-record-checklist.md 用七个问题检验一个全新 Agent 能否仅凭仓库就回答正在构建什么产品应用为用户做什么代码库如何组织应用如何启动健康检查如何做当前进行中的工作是什么什么质量标准最重要2.2 新鲜会话测试Fresh Session Test这是检验地图画得够不够好的标准方法打开一个全新的 Agent 会话只给它仓库内容看它能否回答五个基本问题——这是什么系统如何组织的如何运行如何验证我们现在进行到哪了回答不了的地方就是地图的空白区空白处 Agent 只能靠猜猜错的代价远高于最初画地图的成本。2.3 ACID 类比像管理数据库事务一样管理 Agent 状态Lecture 03 借用数据库事务四性为仓库即记录提供了落地的状态管理框架原子性Atomicity每个逻辑操作如新增端点并更新测试对应一次 git 提交中途失败用git stash回滚杜绝半成品。一致性Consistency定义一致状态的验证谓词全部测试通过、lint 零错误Agent 每次操作后必须验证不一致的中间态不得提交。隔离性Isolation多 Agent 并发时状态文件设计要避免竞态——最简单的方案是每个 Agent 用自己的进度文件或使用 git 分支隔离。持久性Durability跨会话必须存活的知识写入 git 跟踪的文件会话内存里的临时状态不算数脑子里记得不算数只有写下来才算数。三、信条二AGENTS.md是路由器不是百科全书AGENTS.mdis a router, not an encyclopedia.这条信条直接回应 Lecture 04 描述的巨型指令文件陷阱一个 600 行的AGENTS.md会带来五个连锁问题——上下文预算被吞噬、关键规则淹没在中间Lost in the Middle、硬约束与软建议优先级混淆、维护衰减、规则互相矛盾。3.1 路由器与百科全书的边界入口文件只做三件事项目概览一两句话说明这是什么常用命令make setup make test这类一运行就出结果的指令全局硬约束不超过 15 条不可协商的红线规则主题文档链接一行描述 适用条件。50–200 行足矣。更细的规则放进docs/目录下的主题文档每份 50–150 行Agent 按需加载reveal on demand。每条规则还应记录三要素来源为什么加这条规则、适用条件何时需要、过期条件什么情况下可以删。3.2 仓库中的路由器范例repo-template 自带的 AGENTS.md 就是这一信条的活体标本——全文第一段就写明本仓库为长时运行编码 Agent 优化。请保持此文件简短。把它当作进入 system-of-record 文档的路由层而不是巨型指令堆。随后用Routing Map一节以一行描述的粒度路由到八份文档- ARCHITECTURE.md: 领域地图、分层模型、依赖规则 - docs/design-docs/index.md: 设计决策与核心信条 - docs/product-specs/index.md: 产品行为与验收目标 - docs/PLANS.md: 计划生命周期与执行计划策略 - docs/QUALITY_SCORE.md: 产品领域与分层健康度 - docs/RELIABILITY.md: 运行时信号、基准与重启预期 - docs/SECURITY.md: 密钥、沙箱、数据与外部操作规则 - docs/FRONTEND.md: UI 约束、设计系统规则、可访问性检查同时它在Working Contract中明确优先添加小而新的文档而不是扩张本文件——这正是信条二路由器而非百科全书的可执行化。3.3 项目实例project-01 的 AGENTS.mdprojects/project-01/solution/AGENTS.md 展示了同样的路由结构如何落到一个 Electron 知识库应用上启动规则按顺序要求先读docs/ARCHITECTURE.md理解分层、读docs/PRODUCT.md理解需求、运行bash init.sh验证构建、再读feature_list.json了解特性状态随后用Electron 分层边界一节把主进程、preload、渲染器、服务层的不可违反约束各用三五行写清如渲染器永不导入fs、path、electron最后以Definition of Done收尾。整个文件控制在约 60 行是小而完整的实证。四、信条三验证证据比自信更重要Verification evidence matters more than confidence.Lecture 09 引用了 Guo et al. 的经典结论现代神经网络系统性地过度自信模型报告的置信度显著高于真实准确率。编码 Agent 同样如此——代码写完了和功能真正完成之间隔着整整一条验证链。4.1 三层终止验证Three-Layer Termination Check完成不再是 Agent 的主观判断而是 harness 的客观裁决必须逐层通过第一层语法与静态分析——成本最低、信息最少但必须通过第二层运行时行为验证——测试执行、应用启动检查、关键路径验证核心证据是不仅写出来了而且跑起来了第三层系统级确认——端到端测试、集成验证、用户场景模拟防线是不仅跑起来了而且是对的。4.2 Definition of Done把完成标准写进文件project-01 的 AGENTS.md 给出了可直接照抄的完成定义1. TypeScript 编译无错误npm run check 2. 应用可启动且窗口可见npm run dev 3. 特性出现在 feature_list.json 中状态为 pass 并附证据 4. 代码遵守上述 Electron 分层边界 5. 正常运行期间无控制台错误注意第 3 条附证据——feature_list.json 正是证据的外部化载体。看 feature_list.json 的实际条目每条特性都带evidence字段记录验证事实例如 window-launch 的 evidence 是npm run dev以 1200x800 启动窗口contextIsolationtrue、nodeIntegrationfalse。这就是验证证据比自信更重要的机器可读表达。4.3 错误信息要包含修复指令Lecture 09 强调写给 Agent 的错误信息不应只说测试失败了而应给出可执行路径例如POST /api/reset-password返回 500。检查环境变量中是否存在邮件服务配置。模板文件应在templates/reset-email.html。这种反馈让 Agent 无需人工介入即可自我纠正。4.4 分离工人与检查者同一模型既生成又评估天然倾向对自己宽松。因此完工判定必须外部化harness 独立执行终止验证输入是运行时信号日志、进程状态、健康检查而非 Agent 的自信。Lecture 09 引用的实验数据表明从单 Agent 裸跑改为规划者 生成者 评估者三方结构后同一模型Opus 4.5与同一提示词下功能从不可用变为完整可用。五、信条四一个受边界约束的任务胜过多个半成品One bounded task is better than many half-finished tasks.Lecture 07 用数学解释了这条信条假设上下文容量为 C同时激活 k 个任务每个任务平均只能分到 C/k 的推理资源当 C/k 低于完成单个任务所需的最小阈值时一个都完不成。Agent 自带顺手多做一点的冲动——要求加用户注册它可能顺手加上邮件服务、密码哈希、错误中间件重构和测试目录整理结果 12 个文件被改、800 行新代码却没有任何一个特性通过端到端验证。5.1 WIP1 工作流借鉴看板Kanban的 WIP 限制概念对 Agent 最安全的默认值是WIP1同一时刻只允许一个active状态的任务当前任务通过端到端验证并提交后才解锁下一个任务。Anthropic 的实验数据显示小步下一步策略等价于 WIP1相比宽泛提示词的任务完成率高出 37%而生成的代码行数与特性实际完成度呈弱负相关——写得越多完成得越少。在CLAUDE.md或AGENTS.md中可这样写## 工作规则 - 一次只做一个特性 - 当前特性通过端到端验证后才开始下一个 - 实现特性 A 时不要顺手重构特性 B5.2 过度扩张与完成不足是一枚硬币的两面过度扩张稀释注意力 → 注意力稀释导致完成不足 → 留下的半成品代码增加系统复杂度 → 复杂度又驱动下一轮过度扩张。这是一个正反馈恶性循环。用 Littles LawL λW看在制品 L 过高每项任务的交付周期 W 必然拉长。对 Agent 而言生成下一个想法几乎零成本所以 harness 必须通过 WIP 限制与完成证据要求施加完成压力。六、信条五重复出现的人类反馈应沉淀为可复用的 harness 规则Repeated human feedback should become reusable harness rules.这条信条的内核是不要在同一条反馈上反复人工解释而是把反馈转译成机械化的规则、检查项或 linter。repo-template 的 AGENTS.md 在Working Contract中明确写道如果你看到重复的评审反馈把它提升为机械规则、检查或 linter而不是在聊天中重新解释。6.1 三条转化路径把黄金规则编码进仓库如优先使用共享工具包而不是临时手写的辅助函数不要 YOLO 猜测数据结构校验边界或依赖类型化 SDK。这类规则具体、机械化、可自动检查。建立周期性清理工作流一组后台任务定期扫描偏离、更新质量评分、开出定向重构 PR多数可在 1 分钟内评审并自动合并。一次捕捉人类品味持续强制执行评审意见、重构 PR、用户反馈的 bug 全部转化为文档更新或工具化规则文档不够时把规则提升为代码。七、信条六清理与简化是交付的一部分Cleanup and simplification are part of shipping, not afterthoughts.Lecture 12 用熵增定律描述默认状态系统在持续变更中必然趋于复杂除非主动治理。OpenAI 在五个月的 Codex 实验中观察到Agent 会复制仓库中已有的模式即使这些模式不一致或次优——第一人放了个咖啡杯第二人觉得反正已经乱了再放一个一周后桌面被杯子淹没。7.1 干净状态的五条件干净状态不是代码能编译这么简单会话结束时必须同时满足五条构建通过——下一个会话不应先修构建错误测试通过——包括会话之前就存在的测试不许破坏既有功能且要在 CI 中验证而非我机器上能跑进度已记录——完成/进行中/未开始的子任务写入机器可读产物良好的进度记录可将会话启动诊断时间降低 60–80%无残留临时物——调试日志、临时文件、注释掉的代码、TODO 标记都要清理标准启动路径可用——环境初始化、代码加载、上下文获取、任务选择任何一个环节都不能断。7.2 会话完整性Session Integrity类比数据库事务要么完整提交并留下干净状态要么回滚到最后一个一致状态没有中间地带。repo-template 的 AGENTS.md 在End Of Session一节给出了强制收尾清单更新活动执行计划若任何领域或分层有实质变化更新docs/QUALITY_SCORE.md若推迟了债务在docs/exec-plans/tech-debt-tracker.md中记录完成计划移入docs/exec-plans/completed/让仓库处于可重启状态并留下清晰的下一步行动。7.3 幂等的清理操作清理操作必须幂等——无论运行多少次结果相同确保失败重试场景下清理依然安全。技术债是高息贷款持续小额偿还几乎总是优于一次性大额清算。八、信条七仓库中无法发现的事实视为操作上不可用If an agent cannot discover a fact in-repo, treat that fact as operationally unavailable.这是信条一的验收标准也是整套体系的自检锚点。判断标准很简单如果信息这条路封了只存在于某位同事的脑子里那么每次都必须去问那个人把它写进仓库就再也没人需要问。8.1 知识发现成本Discovery Cost信条七还隐含了对信息放置位置的量化要求Agent 为找到一条关键信息所消耗的上下文预算就是发现成本。信息藏得越深发现成本越高留给实际任务的预算越少。关键信息应放在 Agent 第一眼就能看到的位置而不是埋在十个目录之下。8.2 知识衰减率Knowledge Decay Rate信条七的另一个推论是知识衰减率——仓库中单位时间内变陈旧的知识条目比例。文档与代码脱节是最大的敌人过时文档比没有文档更危险因为它让 Agent 自认为走在正确的路上实际却朝错误方向前进。因此每条规则都要有来源、适用条件和过期条件并定期审计删除陈旧条目。8.3 把可发现性变成目录结构Lecture 03 给出的落地结构同时满足了信条一、二、七project/ ├── AGENTS.md # 入口项目概览、运行命令、硬约束 ├── src/ │ ├── api/ │ │ ├── ARCHITECTURE.md # API 层架构决策 │ │ └── ... │ ├── db/ │ │ ├── CONSTRAINTS.md # 数据库操作硬约束 │ │ └── ... │ └── ... ├── PROGRESS.md # 当前进度已完成 / 进行中 / 阻塞 └── Makefile # 标准化命令setup, test, lint, check关键原则是知识住在代码旁边knowledge lives next to code关于 API 认证的规则放在 API 代码旁边而不是埋进一个巨型全局文档。当 Agent 到达代码时也同时到达约束无需额外搜索。九、让信条可维护设计文档索引的治理规则设计文档索引 本身演示了如何让信条体系持续演进。它按 Accepted / Proposed / Deprecated 三态组织设计历史并给出四条维护规则每份设计文档应有负责人或更新触发器陈旧文档要么删除要么标记为 deprecated而不是任其漂移将活动的执行计划与其依赖的设计文档链接起来该索引本身是设计历史可发现的地图。这套机制让 core-beliefs.md 这类信条文档不至于沦为一纸空文——它有明确的演进路径Proposed → Accepted → Deprecated和生命周期管理正好呼应信条五反馈机制化与信条六清理是交付的一部分。十、实践项目映射从信条到练习本仓库的实践项目为每条信条提供了对应的动手训练场Project 01. Baseline vs Minimal Harness对比无 harness 与最小 harness直接检验信条三完成定义与 feature_list.json 证据与信条二入口文件路由。Project 02. Agent-Readable Workspace对应信条一与信条七让 Agent 读懂项目并从中断处继续。Project 03. Multi-Session Continuity对应信条六多会话连续性依赖干净的收尾状态。Project 04. Incremental Indexing用运行时反馈纠正 Agent 行为对应信条四的完成压力机制。Project 05. Grounded QA Verification让 Agent 验证自己的工作直接对应信条三。Project 06. Runtime Observability and Debugging构建完整 Agent 工作区综合检验信条五与信条六。每个项目都包含 starter起点与 solution解法两套目录solution 中的AGENTS.md、feature_list.json、clean-state-checklist.md等文件就是七条信条的具体物化可直接对照学习。结语信条是起点落地才是终点七条 Core Beliefs 的共同底色是同一个判断Agent 的能力边界由 harness 决定而 harness 的每一份输入都来自仓库。仓库承载事实信条一入口文件组织事实信条二验证判定事实信条三边界控制工作流信条四反馈进化规则信条五收尾保障状态信条六可发现性验收一切信条七。在本仓库中你可以顺着 core-beliefs.md → 设计文档索引 → AGENTS.md 模板 的路径建立自己的信条体系再通过 Lecture 03 到 Lecture 12 的系列讲座掌握每一信条的工程化手法最后用八个实践项目的 solution 目录对照验收。判断自己是否入门的标准只有一个让一个全新会话只读仓库看它能否独立回答这是什么、怎么组织、怎么运行、怎么验证、进行到哪——五问全过信条才算真正落地。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐Agent 优先的仓库设计learn-harness-engineering 七大核心信念Core Beliefs深度解析Agent 优先的仓库设计learn harness engineering 七大核心信念Core Beliefs深度解析 导读 本文围绕开源仓库 lelearn-harness-engineering 核心信念解读Agent 优先仓库的 7 条设计原则与工程化落地learn harness engineering 核心信念解读Agent 优先仓库的 7 条设计原则与工程化落地 本篇技术指南围绕开源仓库 learn haAgent 优先仓库的质量健康度追踪learn-harness-engineering 中 QUALITY_SCORE.md 的设计与落地实践Agent 优先仓库的质量健康度追踪learn harness engineering 中 QUALITY_SCORE.md 的设计与落地实践 导读本文围绕创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考