【免费下载链接】learn-harness-engineering
Harness engineering beginner tutorial, from 0 to 1
本文基于 Learn Harness Engineering 仓库中 PRODUCT_SENSE.md 模板文件展开。该文件是 OpenAI 风格“Advanced Repo Template”中最重要的一个系统记录文档：它把那些 Agent 无法仅凭代码可靠推断出来的耐久产品判断（主要用户、待完成工作、质量门槛、产品规则与禁止模式）固化进仓库，使每一轮新会话都能继承团队对“什么是对的产品”的共识，而不是靠猜测行事。读完本文，你将掌握 PRODUCT_SENSE.md 每个字段的填写方法与判断标准，理解它与 product-specs、design-docs 等文档的分工边界，并能在自己的仓库中按复制顺序与编码 SOP 落地这一机制。
为什么 Agent 需要一份“产品判断”文档
代码只能回答“系统现在做了什么”，无法回答“系统应该为什么人、解决什么痛点、在什么质量标准下被接受”。一个没有产品上下文的编码 Agent，会用自己的隐含默认值填补这些空白——通常表现为“代码没有明显语法错误就算完成”，这与产品意义上的“完成”往往相差甚远。
这正是 PRODUCT_SENSE.md 存在的理由：它捕获 Agent 无法仅从代码中可靠推断的耐久产品判断（durable product judgment）。文件开篇就点明了这一使命：这些判断是跨会话、跨 sprint、跨评审者记忆依然成立的长期资产，必须被显式写入仓库。
这一设计与本仓库的核心方法论一脉相承。在 Aula 03：让仓库成为唯一事实来源 中已经论证：对 Agent 而言，不在仓库里的信息就等于不存在——它只有三种输入：系统提示与任务描述、仓库文件内容、工具执行输出。Slack、Confluence、Jira 或某位工程师脑中的产品决策，Agent 一概看不见。所以“产品的本质是什么”这类判断，要么写进仓库，要么每次都由 Agent 猜测。
Product Core：四个必填字段
模板要求每个使用它的仓库必须回答四个问题，全部以占位符[substitua]（替换）形式给出，等待真实项目填入：
| 字段 | 模板占位符 | 含义 | 填写建议 |
|---|---|---|---|
| 主要用户（Primary user） | [substitua] | 系统为谁而建 | 用一句话描述目标角色的特征与场景，例如“独立开发者，正在维护 3 个以上长期运行的仓库” |
| 待完成工作（Job to be done） | [substitua] | 用户在什么情境下想达成什么结果 | 描述“雇用”产品的具体情境，而非功能清单，例如“在不重新解释项目状态的前提下，跨会话恢复编码工作” |
| 要消除的主要痛点（Main frustration to be removed） | [substitua] | 当前体验中最令人沮丧的部分 | 指向现状中反复出现的摩擦，例如“每次新会话都要重新发现初始化命令与未完成状态” |
| 验收质量门槛（Quality bar for acceptance） | [substitua] | 什么才算“足够好” | 写成可观察、可检验的陈述，例如“所有核心流程都有可重复执行的验证命令且全部通过” |
四个字段的价值在于强制团队在写代码之前先达成产品共识。结合 initializer-agent-playbook.md 的“新会话测试”，一个填写完整的 Product Core 能让全新会话仅凭仓库内容回答“这个仓库做什么、为谁做、怎样算好”。
Product Rules：四条产品规则的语义
模板给出了四条必须遵守的产品规则，它们是跨功能、跨模块的横向优先级（cross-cutting priorities），不依附于任何单一流程：
优先用户可见的可靠性，而非功能数量（Favor user-visible reliability over feature count）。 这是对“功能越多越好”的反拨。验收和排期应以“用户真正依赖的行为是否稳定”为基准，而不是以合并的功能条目数论英雄。
把模糊行为视为规范缺口，而非猜测的许可（Treat ambiguous behavior as a spec gap, not as permission to guess）。 当行为定义不清时，正确动作是补全规范，而不是让 Agent 自由发挥。这一点与 Aula 08：功能列表作为 harness 原语 中“行为描述缺失即视为条目不完整”的判断一致——模糊就是缺口，缺口必须显式修补。
如果实现改变了用户所见或所信，必须同步更新对应规范（If implementation changes what users see or trust, update the matching spec）。 这条规则在 product-specs/index.md 中得到了镜像落实：“若实现偏离规范，在同一会话内更新其中一方”。产品判断、产品规范与实现三者必须保持同频。
具体流程用产品规范（product specs），横向产品优先级用本文件（Use product specs for concrete flows, and use this file for cross-cutting product priorities）。 这是关键的分工声明：PRODUCT_SENSE.md 不负责描述任何具体用户流程——那是 new-user-onboarding.md 这类规范文件的职责；它只承载那些横切所有功能的判断准则。
No-Go Patterns：四种绝对禁止模式
模板明确列出四种一旦出现就应判定为不合格的模式，它们既是给 Agent 的禁令，也是给评审者的检查清单：
- 隐藏的破坏性动作（Hidden destructive actions）：删除数据、覆盖文件、执行不可逆操作却不让用户察觉。对应 SECURITY.md 中“破坏性或生产级命令默认禁止执行”的原则。
- 无反馈的静默失败（Silent failure without user feedback）：出错但不报错，用户无从知晓系统已偏离预期。这与 RELIABILITY.md 要求的“用户可见错误状态”“可诊断的运行时信号”直接呼应。
- 可见状态的模糊事实来源（Unclear source of truth for visible state）：用户看到的界面/进度/状态，找不到唯一权威的数据源。这正是 AGENTS.md 路由架构与“仓库作为系统记录”要消灭的反模式。
- 无法用一句话解释的功能（Features that cannot be explained in one sentence）：说明该功能缺乏清晰的价值主张，大概率是范围蔓延（scope sprawl）的产物，应当被砍掉或重构。
这四条模式的工程意义在于：它们把“好产品”的抽象标准翻译成了可机械检查的负面清单。在 evaluator-rubric.md 中，“正确性”“验证”“范围纪律”等评分维度正是这些模式的正面镜像——评审时逐条对照即可。
与周边文档的分工：一次完整的渐进披露
PRODUCT_SENSE.md 不是孤立文件，它处在一张精心设计的文档路由网中。根据 repo-template 的复制说明，采纳顺序是：先把AGENTS.md与ARCHITECTURE.md复制到仓库根目录，再复制整个docs/树，且要求首先填写PRODUCT_SENSE.md、QUALITY_SCORE.md与RELIABILITY.md——产品判断是所有后续文档的先行条件。
各文档的分工边界可以概括为：
| 文档 | 回答的问题 | 位置 |
|---|---|---|
AGENTS.md | 会话如何启动、先读什么 | 仓库根目录 |
ARCHITECTURE.md | 系统如何组织、依赖规则 | 仓库根目录 |
PRODUCT_SENSE.md | 产品本质判断与横向优先级 | docs/ |
product-specs/* | 具体用户流程与验收标准 | docs/product-specs/ |
design-docs/* | 设计决策与理由 | docs/design-docs/ |
QUALITY_SCORE.md | 质量随时间如何变化 | docs/ |
RELIABILITY.md | 如何证明系统健康与可重启 | docs/ |
在 core-beliefs.md 中，“AGENTS.md 是路由器而非百科全书”“仓库是 Agent 的事实来源”两条信念为这套分工提供了哲学依据：入口文件保持短小，细节下沉到被链接的文档；而 PRODUCT_SENSE.md 正是“产品事实”的权威落点之一。
落地流程：从填写到验证
第一步：按复制顺序搭建
按 repo-template/index.md 给出的顺序操作：复制AGENTS.md、ARCHITECTURE.md与整个docs/树后，第一优先填写PRODUCT_SENSE.md、QUALITY_SCORE.md、RELIABILITY.md，然后才创建第一个活动计划于docs/exec-plans/active/。
第二步：用编码 SOP 把“隐性产品知识”搬进文件
团队的产品判断通常散落在聊天记录、评审意见和少数人的脑中。可以套用 SOP：把仓库之外的知识编码进仓库 的流程：
- 列出所有不可见的知识来源：文档、聊天、团队不成文规则、口头决策。
- 对每条来源分类：是架构、产品行为、安全策略、可靠性期望、计划上下文还是参考资料？
- 产品行为的分类归入
docs/product-specs/，而“跨功能的横向产品优先级”写入 PRODUCT_SENSE.md。 - 把含糊表述替换为操作性可用的文字。
- 删除或废弃过时副本，确保单一可发现的事实。
该 SOP 还给出了触发信号：Agent 反复询问系统如何工作、人类说“我们在 Slack 里定过这事”、评审反复引用仓库中不存在的产品/安全规则——出现任一信号，就说明 PRODUCT_SENSE.md 还没写好或没被更新。
第三步：用“新会话测试”验证
仿照 initializer-agent-playbook.md 的成功标准：一个没有任何聊天上下文的新会话，应当仅凭仓库内容回答——“这个仓库为谁做什么”“什么算完成”“什么绝不允许做”。若 Agent 给出的产品判断与团队共识不符，说明 PRODUCT_SENSE.md 存在缺口，应回到第二步补全，而不是在对话里反复口头纠正。
维护与演化：让产品判断不腐化
PRODUCT_SENSE.md 必须随产品一起演化，否则就会落入“知识衰变”陷阱——Aula 03 明确指出，过时文档比没有文档更危险，它会让 Agent 在确信正确的情况下走向错误方向。维护要点：
- 与代码变更同会话更新：每当实现改变了用户所见或所信，立刻回到规则 3，同步 PRODUCT_SENSE.md 或对应规范，而不是留到“专门整理日”。
- 把反复出现的评审反馈提升为机械化检查：若“功能无法一句话解释”“静默失败”等反模式在评审中反复出现，就应将其固化为 lint 规则、脚本或 CI 检查，而不是在每次对话中重新解释——这正是 AGENTS.md 工作契约中的明确要求。
- 与质量跟踪联动：PRODUCT_SENSE.md 中的质量门槛应能映射到 QUALITY_SCORE.md 的评分维度（可验证性、Agent 可读性、测试稳定性），使“产品判断是否正确执行”成为可随时间追踪的指标，而非一次性评审结论。
总结
PRODUCT_SENSE.md 是 Learn Harness Engineering 提供的 OpenAI 风格高级仓库模板中，最容易被低估却最关键的文档之一。它以四个必填字段固化产品本质，以四条规则划定横向优先级，以四种禁止模式竖立红线，并通过与 product-specs、AGENTS.md、QUALITY_SCORE.md、RELIABILITY.md 的明确分工，构成了一套可复制、可验证、可持续演化的产品判断传导机制。把它与 编码知识 SOP 和 新会话测试 组合使用，就能让每一个新会话的 Agent 在动手前，先继承团队对“什么是对的产品”的全部共识。
【免费下载链接】learn-harness-engineering
Harness engineering beginner tutorial, from 0 to 1
相关推荐
用 PRODUCT_SENSE.md 固化 Agent 无法从代码推断的产品判断：learn-harness-engineering 仓库模板实战指南
用 PRODUCT_SENSE.md 固化 Agent 无法从代码推断的产品判断：learn harness engineering 仓库模板实战指南 导读 在
PRODUCT_SENSE.md 实战指南：在 Agent 优先仓库中记录「无法从代码推断的产品判断」
PRODUCT_SENSE.md 实战指南：在 Agent 优先仓库中记录「无法从代码推断的产品判断」 本文基于 learn harness engineeri
PRODUCT_SENSE.md 产品判断文档：在 Agent 化仓库中固化"代码无法推断的产品决策"
PRODUCT_SENSE.md 产品判断文档：在 Agent 化仓库中固化"代码无法推断的产品决策" <output_article
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
