learn-harness-engineering 核心信念解读构建 Agent 优先仓库的 7 条操作准则【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering导读本文深入解读本仓库中 OpenAI Advanced Pack 模板的设计哲学骨架——core-beliefs.md所定义的 7 条核心信念。这些信念回答了一个根本问题当 AI 编程 Agent 成为长期协作伙伴时仓库应该如何被组织才能让 Agent 可靠、可验证、可持续地工作。读完本文你将理解每条信念背后的工程动机、它们在 repo-template 中的落地形态以及如何用本仓库的课程Lectures与 SOP 将其转化为可执行的日常实践。背景一份只有 7 条信念的设计文档在 docs/en/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.md 中整个 Agent 优先仓库的设计哲学被压缩成了 7 条短句。它属于 OpenAI Advanced Pack 中repo-template的docs/design-docs/目录——该目录通过 design-docs/index.md 作为设计历史可发现地图被维护其中core-beliefs.md被标记为Accepted已接受状态即Agent 优先的运作信念与持久项目规范。7 条信念虽短却不是空泛口号。本仓库的课程体系与 SOP 为每一条都提供了可操作的实现路径仓库即规范Lecture 03、验证优于信心Lecture 09、短入口文件路由AGENTS.md 模板、单一有界任务PLANS.md 执行计划策略、反馈规则化Working Contract以及清理即发布QUALITY_SCORE.md 简化日志。下文逐条展开。信念一仓库是 Agent 的权威记录系统System of RecordThe repository is the system of record for agents.这是整份信念清单的基石。其内涵在本仓库的 Lecture 03《Making the Repository the Single Source of Truth》 中被表述为repo as spec原则仓库本身就是最高权威的规格文档。Agent 只有三个输入来源——系统提示与任务描述、仓库文件内容、工具执行输出。Slack 记录、Jira 工单、Confluence 页面乃至工程师脑中的口头约定对 Agent 而言根本不存在。该讲稿定义了三个与本信念直接相关的核心概念Knowledge Visibility Gap知识可见性缺口未进入仓库的项目知识占比。缺口越大Agent 失败率越高。System of Record仓库作为项目决策、架构约束、执行状态与验证标准的权威来源——仓库说了算其他地方都不算。Fresh Session Test全新会话测试开一个全新 Agent 会话、只给它仓库内容看它能否回答五个基本问题这是什么系统如何组织如何运行如何验证当前进度如何对应 SOP 是 encode-knowledge-into-repo.md它给出了把看不见的知识Google Docs、聊天记录、工单、人脑编码进仓库的分步方法先盘点隐形知识来源再分类架构 →ARCHITECTURE.md、产品行为 →docs/product-specs/、设计理由 →docs/design-docs/、执行状态 →docs/exec-plans/、外部参考 →docs/references/、质量与可靠性期望 →docs/QUALITY_SCORE.md或docs/RELIABILITY.md最后替换含糊表述并淘汰过期副本。其Definition of Done是一个全新 Agent 无需询问人类即可发现相关规则。信念二AGENTS.md 是路由器不是百科全书AGENTS.mdis a router, not an encyclopedia.这是对仓库即记录系统在入口层的具体化知识全部入库 ≠ 全部塞进一个文件。repo-template 的 AGENTS.md 本身就是这条信念的活标本——全文仅 61 行开篇即声明This repository is optimized for long-running coding-agent work. Keep this file short. Use it as the routing layer into the system-of-record docs, not as a giant instruction dump.本仓库面向长期运行的编码 Agent 优化。请保持本文件简短将其用作进入记录系统文档的路由层而非巨型指令转储。它的结构体现了路由的三层设计Startup Workflow启动工作流按序给出 7 步启动路径——pwd确认根目录 → 读ARCHITECTURE.md→ 读docs/QUALITY_SCORE.md→ 读docs/PLANS.md与活动计划 → 读相关产品规格 → 运行引导与验证 → 基线失败先修基线。Routing Map路由地图用一行一条的清单把 Agent 导向 8 个深层文档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每条带一句职责说明。Working Contract / Definition of Done / End of Session把协作契约、完成定义与会话收尾动作直接写进入口文件。Lecture 03 对入口文件给出定量建议50–100 行足够它只需让 Agent 快速回答三个问题——这个项目是什么、如何运行、如何验证。OpenAI Advanced Pack 的 设计原则 也明确列出 Short entrypoint, deeper linked docs短入口、深层链接文档并告诫KeepAGENTS.mdshort. Treat it as a router into the deeper docs, not as an encyclopedia.信念三验证证据比信心更重要Verification evidence matters more than confidence.这条信念针对的是 Agent 最危险的失败模式之一——过早宣布胜利premature victory declaration。本仓库 Lecture 09《Preventing Agents from Declaring Victory Too Early》 从三个层面为这条信念提供了依据信心校准偏差Confidence Calibration Bias引用 Guo et al. 2017 年 ICML 论文的结论——现代神经网络系统性过度自信。Agent 声称的完成信心系统性高于实际完成质量。单元测试通过 ≠ 任务完成接口不匹配、状态传播错误、环境依赖三类问题恰恰是单元测试隔离 mock 依赖测不出来的。终止判定必须外化Externalize Termination Judgment完成判定不应由 Agent 自己做而应由 harness 独立执行终止验证以运行时信号而非 Agent 信心为输入。该讲稿给出了三层终止验证Three-Layer Termination Check第一层语法与静态分析、第二层运行时行为验证测试执行、启动检查、第三层系统级确认端到端、集成验证。这条信念在模板中的落地形态包括AGENTS.md 的 Definition of Done要求required verification actually ran且evidence is linked、Working Contract 中的 Do not mark work done from code inspection alone; runnable evidence is required仅凭代码检查不得判定完成必须有可运行证据。QUALITY_SCORE.md 的评分体系更是把验证和可读性作为独立维度A级定义为 verified, legible, stable, boundaries enforced已验证、清晰、稳定、边界受控其 Benchmark Snapshots 表要求记录每个 harness 变体的完成率、重试次数与评审前缺陷数——这些正是证据的量化载体。信念四一个有界任务优于多个半成品任务One bounded task is better than many half-finished tasks.这条信念直接对应 Lecture 09 所批评的 Agent 行为模式——顺手重构refactoring while were at itAgent 在核心功能通过验证前就展开重构、性能优化与风格调整模糊了已验证与未验证代码的边界反而可能破坏原本隐式正确的路径。该讲稿提出的Completion Priority Constraint完成优先级约束正是本信念的等价表述先验证功能正确性再处理性能最后处理风格核心功能验证通过之前不允许重构。在模板中的落地机制是计划纪律PLANS.md 规定执行计划的最小必需章节objective目标、scope and out-of-scope范围与范围外、verification path验证路径、risks and blockers风险与阻塞、progress log进度日志、open decisions未决决策。计划目录三分docs/exec-plans/active/当前驱动的计划、docs/exec-plans/completed/已完成计划保留供 Agent 日后取用上下文、docs/exec-plans/tech-debt-tracker.md延期工作与跟进项。运作规则要求一个活动计划应有一个明确归属的当前步骤且计划应随工作推进持续更新而非静态散文。AGENTS.md 的 Working Contract 同样写明 Work from one bounded plan or feature slice at a time一次只从一个有界计划或功能切片出发。这与 Lecture 03 的 ACID 类比 中的Atomicity原子性一致每个逻辑操作对应一次 git 提交失败则整体回滚——要么全做要么全不做杜绝做了一半。信念五重复出现的人类反馈应固化为可复用的 harness 规则Repeated human feedback should become reusable harness rules.这条信念针对的是知识编码的效率问题如果同一类评审意见反复出现说明问题不在某个具体提交而在 harness 缺乏对应规则。AGENTS.md 的 Working Contract 给出了机制化的表述If you see repeated review feedback, promote it into a mechanical rule, check, or linter instead of re-explaining it in chat.若发现重复的评审反馈应将其提升为机械化规则、检查或 linter而不是在聊天中反复解释。这与 Lecture 09 中 OpenAI Codex 实践所强调的可操作错误反馈一脉相承写给 Agent 的错误消息应包含修复指引——不要只说 Test failed而要说 Test failed: POST /api/reset-password returned 500. Check that the email service config exists in environment variables...。当这类反馈反复出现时下一步就是把它固化为检查脚本或守卫。SOP 库 的使用方式第 4 条进一步明确Convert repeated review comments into checks, scripts, or guardrails将重复的评审意见转化为检查、脚本或护栏。Lecture 03 也给出了配套原则——Principle 4: Update with code知识与代码同步更新把架构文档放在对应模块目录改代码时自然注意到文档CI 可在代码变更后提醒检查文档是否需要更新。这条信念的完整闭环是人类反馈 → 写入仓库encode-knowledge-into-repo→ 反复出现 → 固化为机械化规则。信念六清理与简化是发布的一部分而非事后补想Cleanup and simplification are part of shipping, not afterthoughts.这条信念把删代码、改结构、简化从可选的整理日活动提升为一等公民。OpenAI Advanced Pack 的设计原则 明确列出 Cleanup and simplification are first-class responsibilities清理与简化是一等职责并在采用指南中写道Update the quality, reliability, and plan docs as part of normal work, not as a separate cleanup day更新质量、可靠性与计划文档属于日常工作的一部分而非单独的清理日。它的量化载体在 QUALITY_SCORE.md 的Simplification Log简化日志表中每个被移除的组件记录Component Removed被移除组件、Outcome后果degraded / unchanged与Decision决策restore / keep removed。这使简化成为可追踪、可回滚的工程决策而非无痕迹的随手删除。而 Lecture 03 的知识衰减Knowledge Decay Rate概念 同样呼应本信念过期的文档比没有文档更危险——它把 Agent 引向错误方向而 Agent 还以为自己走对了。清理陈旧文档本身就是发布的一部分。信念七仓库中不可发现的事实视为运维上不可用If an agent cannot discover a fact in-repo, treat that fact as operationally unavailable.这是对信念一的最终检验标准。Lecture 03 开篇的表述最为直白对于 AI Agent 而言不在仓库中的信息就是不存在。For an AI agent, information thats not in the repository simply does not exist.因此任何理论上正确但 Agent 找不到的事实——无论存在于人脑、Slack 还是外部文档——都必须被当作不可用来对待。这一标准直接转化为可操作的工程动作用 Fresh Session Test 检验Lecture 03 练习 1全新会话 仅仓库内容 五个问题记录答不出的项并改进仓库直至全答。量化知识缺口练习 2把项目重要决策逐项标记为仓库内 / 仓库外计算可见性缺口并制定计划将其压到 10% 以下。按 encode-knowledge-into-repo.md 的触发信号行动Agent 反复询问系统如何工作、人类说我们在 Slack 里决定过、评审引用了仓库中不存在的规则、新会话重复做已解决的探索——这四种信号都意味着存在运维上不可用的知识。Lecture 09 从验证侧补上了同一枚硬币的另一面不仅知识要可发现完成状态也要可发现——运行时信号应用能否启动并到达就绪态、关键路径是否执行成功、副作用是否正确、临时资源是否清理必须作为 harness 判断完成质量的客观依据写入仓库而非依赖 Agent 的自我评估。如何将这 7 条信念落地到自己的项目OpenAI Advanced Pack 提供了一条从信念到实践的完整路径可在自己的仓库中按以下步骤操作从最小 harness 起步仓库还小时不必套用完整模板先建立AGENTS.md入口与基础验证命令。复制 repo-template当仓库需要更强结构时把模板文件复制进自己的仓库。模板布局见 index.md根目录AGENTS.mdARCHITECTURE.mddocs/下分设design-docs/、exec-plans/active / completed / tech-debt-tracker、generated/、product-specs/、references/以及 DESIGN、FRONTEND、PLANS、PRODUCT_SENSE、QUALITY_SCORE、RELIABILITY、SECURITY 等策略文件。保持AGENTS.md简短作为路由器而非百科全书只回答是什么 / 怎么跑 / 怎么验证。把质量、可靠性与计划文档的更新视为日常工作而不是某个专门的清理日。显式管理生成产物与外部参考生成物放docs/generated/外部参考放docs/references/让 Agent 不依赖聊天历史即可找到它们。按瓶颈选择 SOP分层领域架构、知识入库、可观测性反馈回路、Chrome DevTools 验证回路——四份 SOP 各自配有清单用于补齐缺失的工件或工具并把产生的规则编码回你复制的模板文档中。小结7 条核心信念构成一个自洽的闭环仓库是唯一权威信念一→ 入口要短、路由要清晰信念二→ 完成与否以证据为准信念三→ 任务必须有界信念四→ 反馈要沉淀为规则信念五→ 简化是常态职责信念六→ 不可发现即不可用信念七。它们共同回答了长期运行 Agent 场景下仓库应该长什么样的问题。本仓库的 Lecture 03 与 Lecture 09 提供了信念背后的失败模式分析repo-template 提供了可直接复制修改的落地文件而 sops 提供了把信念转化为日常流程的操作手册。需要提醒的是这份模板刻意持有观点intentionally opinionated应当根据自身项目情况调整而非盲目照搬。【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考