企业官网建设流程全解析

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 Record）

The 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 优化。请保持本文件简短，将其用作进入记录系统文档的路由层，而非巨型指令转储。）

它的结构体现了"路由"的三层设计：

1. Startup Workflow（启动工作流）：按序给出 7 步启动路径——pwd确认根目录 → 读ARCHITECTURE.md→ 读docs/QUALITY_SCORE.md→ 读docs/PLANS.md与活动计划 → 读相关产品规格 → 运行引导与验证 → 基线失败先修基线。
2. 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），每条带一句职责说明。
3. 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 we're at it）：Agent 在核心功能通过验证前就展开重构、性能优化与风格调整，模糊了已验证与未验证代码的边界，反而可能破坏原本隐式正确的路径。该讲稿提出的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 that's not in the repository simply does not exist.）因此，任何"理论上正确但 Agent 找不到"的事实——无论存在于人脑、Slack 还是外部文档——都必须被当作不可用来对待。

这一标准直接转化为可操作的工程动作：

1. 用 Fresh Session Test 检验（Lecture 03 练习 1）：全新会话 + 仅仓库内容 + 五个问题，记录答不出的项并改进仓库直至全答。
2. 量化知识缺口（练习 2）：把项目重要决策逐项标记为"仓库内 / 仓库外"，计算可见性缺口并制定计划将其压到 10% 以下。
3. 按 encode-knowledge-into-repo.md 的触发信号行动：Agent 反复询问系统如何工作、人类说"我们在 Slack 里决定过"、评审引用了仓库中不存在的规则、新会话重复做已解决的探索——这四种信号都意味着存在"运维上不可用"的知识。

Lecture 09 从验证侧补上了同一枚硬币的另一面：不仅知识要可发现，完成状态也要可发现——运行时信号（应用能否启动并到达就绪态、关键路径是否执行成功、副作用是否正确、临时资源是否清理）必须作为 harness 判断完成质量的客观依据写入仓库，而非依赖 Agent 的自我评估。

如何将这 7 条信念落地到自己的项目

OpenAI Advanced Pack 提供了一条从信念到实践的完整路径，可在自己的仓库中按以下步骤操作：

1. 从最小 harness 起步：仓库还小时不必套用完整模板，先建立AGENTS.md入口与基础验证命令。
2. 复制 repo-template：当仓库需要更强结构时，把模板文件复制进自己的仓库。模板布局见 index.md：根目录AGENTS.md+ARCHITECTURE.md，docs/下分设design-docs/、exec-plans/（active / completed / tech-debt-tracker）、generated/、product-specs/、references/，以及 DESIGN、FRONTEND、PLANS、PRODUCT_SENSE、QUALITY_SCORE、RELIABILITY、SECURITY 等策略文件。
3. 保持AGENTS.md简短：作为路由器而非百科全书，只回答"是什么 / 怎么跑 / 怎么验证"。
4. 把质量、可靠性与计划文档的更新视为日常工作：而不是某个专门的"清理日"。
5. 显式管理生成产物与外部参考：生成物放docs/generated/，外部参考放docs/references/，让 Agent 不依赖聊天历史即可找到它们。
6. 按瓶颈选择 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