【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本文基于 learn-harness-engineering 仓库中 OpenAI 风格 Agent 优先文档模板的 docs/ja/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md 展开。该文档以「最小 Harness」为起点面向需要长期运行编码 Agentcoding agent的仓库解决一个核心痛点产品判断无法从代码中可靠推断。读完本文你将掌握 PRODUCT_SENSE.md 的结构设计意图、四个核心字段与四条产品规则的填写方法、与产品规格/计划/设计文档的分工边界以及如何在仓库中把它变成 Agent 可检索、可引用的「产品判断系统记录」。一、这份文档要解决什么问题任何由 Agent 长期维护的代码仓库都会遇到三类「代码回答不了」的问题产品判断不在代码里为什么这个功能是A而非B为什么这个报错必须对用户可见、而不是静默吞掉这些判断散落在产品经理的聊天记录、PR 评论或某位工程师的脑子里唯独不在代码里。会话记忆不持久一次会话的上下文窗口再大也无法跨会话、跨 Agent 传递判断。新会话的 Agent 面对同样的代码会重新做出不同甚至相反的猜测。推测被误当成授权当规格存在缺口时Agent 倾向于「按最合理的推测继续写代码」。PRODUCT_SENSE.md 的核心立场是模糊不是推测的许可而是规格的缺口。PRODUCT_SENSE.md 的存在意义正是用一句话概括的——「エージェントがコードだけからは確実に推測できない、永続的なプロダクト判断を記録します」记录 Agent 仅凭代码无法可靠推断的、持久的产品判断。它把「判断」这一隐性知识显式化为仓库中的一等公民让 Agent 在动手前就能读到而不是在写完后被人类纠正。二、在 Agent 优先文档体系中的定位在 repo-template/index.md 中这套模板被定义为「最小限のハーネスだけでなく、OpenAIスタイルのエージェントファーストなドキュメントサーフェス」不只是最小 Harness而是 OpenAI 风格的 Agent 优先文档表面。它优化的目标包括持久化的仓库本地上下文persistent repository-local context、渐进式披露progressive disclosure而非巨型单一指令文件、明确的计划生命周期、随时间推移的质量追踪以及「Agent 与人类都可读」的边界。模板的复制顺序揭示了 PRODUCT_SENSE.md 的优先级将AGENTS.md与ARCHITECTURE.md复制到仓库根目录复制整个docs/目录树首先填写docs/PRODUCT_SENSE.md、docs/QUALITY_SCORE.md、docs/RELIABILITY.md在docs/exec-plans/active/中添加第一个激活计划入口文件保持简短把细节引导到链接的文档中。之所以「先填写 PRODUCT_SENSE.md」是因为它是下游所有文档的对齐基准产品规格product-specs描述具体流程执行计划exec-plans描述怎么改而 PRODUCT_SENSE.md 回答的是「这个产品到底为什么存在、优先级是什么、什么绝对不能做」。方向错了后面的执行越精细越浪费。同时它在文档路由体系中扮演「横向层」。仓库根目录的 AGENTS.md 明确把自身定义为「ルーティング層」路由层而非「百科事典」encyclopedia——这正是 design-docs/core-beliefs.md 中「AGENTS.md 是路由器不是百科全书」这一核心信念的实现。启动工作流中Agent 依次阅读ARCHITECTURE.md→QUALITY_SCORE.md→PLANS.md→ 相关产品规格 → 执行标准引导与验证路径。而 PRODUCT_SENSE.md 则作为横切的产品优先级文档供 Agent 在「需要产品判断」的任何时刻查阅而不是塞进某个单一指令文件里。三、PRODUCT_SENSE.md 的完整结构与字段解析原文档虽然只有三个小节但每个小节都对应一种「产品判断的颗粒度」。下面逐段展开。3.1 头部文件目的声明文档第一句定义了本文件的边界このファイルは、エージェントがコードだけからは確実に推測できない、永続的なプロダクト判断を記録します。这句话同时设定了三条隐含规则「確実に推測できない」是收录门槛凡是能直接从代码、类型、命名中读出的信息不该写进本文件「永続的な」是时间尺度本文件记录的是跨会话、跨迭代仍然成立的判断不是某次 PR 的临时决定「プロダクト判断」是内容类型这里是产品优先级不是实现方案。3.2 プロダクトコア产品核心四个必填字段原文档要求用四个字段钉死产品的基本盘每个字段都是[置き換え]占位符需替换为真实内容字段原文回答的问题填写要点主要用户プライマリユーザー为谁做写具体角色/画像不要写「所有用户」。角色决定了后续一切取舍要完成的任务達成すべきジョブ帮用户达成什么写「完成某个结果」而不是「使用某个功能」。例如「保存一次可复现的实验」优于「点击导出按钮」要消除的主要痛点取り除くべき主な不満在替代什么写用户当前最痛的点它是功能优先级的判据验收质量标准受け入れのための品質基準什么算「好」把定性表述转化为可观察、可验证的信号见 4.3 节这四个字段的粒度很讲究前三个是「方向」字段最后一个是「度量」字段。方向字段帮助 Agent 在做取舍时判断「这个改动是让用户更接近目标还是更远」度量字段则直接对接验收避免「做完但没人知道好不好」。3.3 プロダクトルール产品规则四条规则的逐条拆解原文档给出了四条产品规则它们是本文件中最具操作性的内容规则 1功能数量优先让位于用户可见的可靠性機能数よりもユーザーに見える信頼性を優先する。这是对「功能清单越长越好」这一 Agent 常见倾向的明确纠偏。它意味着当新增功能会削弱已验证路径的稳定性时选择保住可靠性。仓库中 project-06 的 solution 里同时存在 quality-document.md 与 evaluator-rubric.md正是把「可靠性可度量」落地的配套实践——产品规则负责定调质量文档负责给「可靠」下可评分的定义。规则 2模糊是规格缺口不是推测许可曖昧な動作を推測の許可ではなく、仕様のギャップとして扱う。这是全文件最重要的一条工程纪律。Agent 的默认行为是在歧义处「选一个最合理的继续写」。这条规则把歧义重新定性为待修复的规格缺口遇到歧义正确动作是停下、澄清、补齐规格写入 product-specs而不是在 PRODUCT_SENSE.md 里给出一个猜测。这也呼应了 AGENTS.md 工作契约中「代码检查本身不算完成必须有可执行证据」的要求——猜测产出的代码不构成证据。规则 3实现改变用户所见/所信时同步更新规格実装がユーザーが見るものや信頼するものを変更した場合、対応する仕様を更新する。实现与规格必须保持双向同步。当 Agent 在实现过程中发现必须改变用户可见行为文案、报错、交互、数据展示时不能「先改了再说」而是在同一会话内更新对应规格。这条规则与 AGENTS.md 的「ワーキングコントラクト」工作契约完全一致「動作を変更した場合、同じセッションで対応するプロダクト、プラン、または信頼性の文書を更新する」改变行为时在同一会话更新对应的产品、计划或可靠性文档。规则 4具体流程交给产品规格本文件只放横切优先级具体的なフローにはプロダクト仕様を使用し、このファイルは横断的なプロダクト優先事項に使用する。这是文档边界的最终裁定PRODUCT_SENSE.md 不是需求文档。具体的用户流程、分步行为、验收条件应写入 docs/product-specs/例如模板自带的 new-user-onboarding.md其中定义了目标、开始条件、用户流程、验收标准、故障状态五个小节。本文件只承载跨功能、跨模块的优先级判断。一旦某个规则只适用于单一流程它就「毕业」到 product-specs 中。3.4 不可パターン禁止模式四条红线原文档用四个「反模式」划出底线任何实现触碰其中一条即视为违反产品判断禁止模式原文解读隐藏的破坏性操作隠された破壊的アクション删除数据、覆盖文件、变更状态等破坏性动作必须有明确的前置确认与可见反馈禁止静默执行无用户反馈的静默失败ユーザーフィードバックのないサイレントな失敗失败必须产生用户可见的错误状态。这与 RELIABILITY.md 要求的「回復可能な障害のユーザーに見えるエラー状態」完全同构——可靠性文档要求运行时信号产品规则要求这些信号抵达用户显示状态的可信来源不明确表示状態の信頼できる情報源が不明確界面显示的任何状态都必须有唯一、明确的可信来源single source of truth禁止「多个地方各存一份状态」无法用一句话解释的功能一文で説明できない機能这是最锋利的一条验收尺子如果一个功能无法用一句话说清它的价值它就不该存在。可作为任何新功能提案的第一道筛子值得注意第三条「表示状態の信頼できる情報源が不明確」与 ARCHITECTURE.md 中的严格依赖规则形成呼应——架构层用「UI 不得绕过 Runtime/Service 契约」「数据访问必须经 Repository 或等价适配器」来机械保证状态来源唯一产品层则把它列为不可妥协的用户可见原则。四、填写实操从占位符到可用的 PRODUCT_SENSE.md4.1 步骤一访谈式收集而非头脑风暴四个核心字段的内容应当来自对真实用户、真实使用场景的观察而不是会议室里「我们应该做……」。每个字段给出一个具体可检验的描述。以下是示意性的替换示例仅为展示写法具体内容需按各自项目实际填写## プロダクトコア - プライマリユーザー: 独立开发者 / 需要长期维护多个项目仓库的工程师 - 達成すべきジョブ: 在不重写架构的前提下让 Agent 能跨会话地理解并推进项目 - 取り除くべき主な不満: Agent 每次会话都要重新摸索项目约定导致重复劳动与不一致 - 受け入れのための品質基準: 新会话的 Agent 在无人工提示的情况下能按仓库文档定位到正确的模块并遵循既有约定4.2 步骤二用「一句话测试」校验每条规则对每一条产品规则问三个问题这条规则能否被一个具体功能/改动违反不能违反的规则没有约束力违反它是否会导致用户可见的伤害否则它属于实现偏好不是产品规则它是否横跨多个功能只适用于单一流程的移入 product-specs原文档的四条规则都通过了这三问规则 1 可被「堆功能砍可靠性」违反规则 2 可被「在歧义处擅自实现」违反规则 3 可被「改行为不更文档」违反规则 4 可被「把本文件写成需求文档」违反。4.3 步骤三把质量标准转成可观察信号「品質基準」最忌写成「体验良好」「性能优秀」这类无法验证的措辞。正确写法是给出可观察、可测量、可被 Agent 检查的信号。这一点在 learn-harness-engineering 的配套模板中有成熟范式skills/harness-creator/templates/ 下的 quality-document.md 与 evaluator-rubric.md以及 AGENTS.md 都强调「以可执行证据run 过、验证过、可复现替代主观断言」。例如「用户可见的可靠性」可操作化为基线验证路径在干净环境下可复现通过、所有失败路径都有用户可见错误提示、核心路径的清理动作在会话结束后可验证。4.4 步骤四双向交叉链接填写完成后让文档之间互相可达AGENTS.md 的路由表中明确指向各文档入口产品规格product-specs中的每个流程在涉及优先级取舍时回链到本文件对应规则执行计划PLANS.md中「未決定事項」open decisions一节引用本文件中「待澄清的规格缺口」。五、与周边文档的分工边界PRODUCT_SENSE.md 的正确使用依赖对整套文档表面documentation surface分工的准确理解。下表汇总了模板中与之相邻的文档各自负责什么文档负责回答更新时机PRODUCT_SENSE.md横切的产品优先级、不可违反的产品规则产品方向或优先级变化时docs/product-specs/具体流程的行为、接受标准、故障状态用户可见行为变化时规则 3DESIGN.md 与 design-docs/持久的系统设计决策与核心信念设计哲学或既定决策变化时QUALITY_SCORE.md各领域/层级的健康度随时间的变化AD 评分每个会话结束或重大改动后RELIABILITY.md系统「健康且可重启」如何被证明标准路径或运行时信号变化时PLANS.md 与 exec-plans执行计划的创建、更新、完成、归档计划生命周期各阶段其中最容易混淆的是「PRODUCT_SENSE vs product-specs」。判据就是原文档规则 4流程细节归 product-specs优先级判断归 PRODUCT_SENSE。举例product-spec 写「新用户注册后进入引导页步骤为 1/2/3」PRODUCT_SENSE 写「可靠性优先于功能数量」——前者描述怎么做后者裁决冲突时听谁的。另一个容易混淆的是「PRODUCT_SENSE vs design-docs/core-beliefs」。core-beliefs如「仓库是 Agent 的系统记录」「AGENTS.md 是路由器不是百科全书」「验证证据比信心更重要」是工程哲学适用于仓库的任何改动PRODUCT_SENSE 则是产品取向适用于产品行为的取舍。前者回答「这个仓库怎么被 Agent 协作」后者回答「这个产品为用户坚持什么」。六、维护契约何时更新、由谁更新PRODUCT_SENSE.md 不是一次填完就束之高阁的静态文件。仓库模板给出了一套明确的维护契约触发更新的条件来自规则 3 AGENTS.md 工作契约实现改变了用户看到的内容或用户信任的东西报错文案、数据展示、交互流程一次评审中反复出现同类型的反馈——此时不是「再解释一遍」而是按 AGENTS.md 的契约「把重复反馈升级为机械规则、检查或 lint」产品方向、目标用户、质量标准发生变化。完成定义Definition of Done的约束来自 AGENTS.md一项变更只有在满足以下全部条件时才视为完成目标行为已实现、必要验证实际执行过、证据已链接到相关计划或质量文档、受影响的文档保持最新、仓库能从标准启动路径干净重启。这意味着「改了代码但没更新 PRODUCT_SENSE 对应的产品判断」在模板语境下就是未完成。会话结束清单来自 AGENTS.md 的「セッションの終了」更新激活中的执行计划领域或层级发生有意义变化时更新 QUALITY_SCORE.md推迟的债务记入 tech-debt-tracker.md适时把完成的计划移入docs/exec-plans/completed/让仓库停留在「下一步动作明确、可重启」的状态。七、在 learn-harness-engineering 仓库中的实践印证PRODUCT_SENSE.md 的理念并非孤立存在。在 learn-harness-engineering 的既有工程实践中可以找到多组同构的「把隐性判断显式化」的证据feature_list.json——把产品能力显式化为清单各项目 solution如 project-06/solution/feature_list.json用结构化 JSON 声明功能清单让 Agent 能精确知道「有哪些功能、是否完成」这与 PRODUCT_SENSE 的「产品判断可检索」目标一致quality-document.md / evaluator-rubric.md——把质量标准变成可评分项project-06/solution/evaluator-rubric.md 给出评分维度对应 PRODUCT_SENSE「受け入れのための品質基準」的可验证化要求skills/harness-creator/templates/ 中的同名模板则把这一实践标准化clean-state-checklist.md——把「可靠」落成可执行清单project-06/solution/clean-state-checklist.md 将「会话结束状态干净」从口号变为逐项可勾选的清单对应 PRODUCT_SENSE 规则 1 中「用户可见可靠性」与 RELIABILITY.md 中「清理是可靠性的一部分」session-handoff.md / claude-progress.md——会话间连续性这些文件如 project-06/solution/session-handoff.md承载跨会话上下文与 PRODUCT_SENSE「永续产品判断」互补前者记录「进行到哪」后者记录「为什么这么做」。从源码结构看整个仓库的 Harness 设计见 skills/harness-creator/SKILL.md 及其 references/lifecycle-bootstrap-pattern.md都围绕同一原则信息放在仓库里Agent 才拿得到判断写进文档里Agent 才靠得住。PRODUCT_SENSE.md 正是把这一原则从「工程状态」延伸到「产品判断」的关键一块。八、自检清单与常见误区填写完成后的自检清单四个核心字段均已替换占位符且每个字段只写「代码推断不出」的内容每条产品规则都能被某个具体行为违反且违反会造成用户可见伤害质量标准全部是可观察信号没有「体验好」「性能佳」这类空洞措辞具体流程细节已迁移到 product-specs本文件只保留横切优先级规则 3 的联动已生效最近一次改变用户可见行为的改动其对应规格已同步更新新会话的 Agent 仅凭本文件 路由文档能对「冲突时听谁的」给出唯一答案。常见误区把本文件写成需求文档堆砌流程、步骤、字段级描述——违反规则 4把实现细节混入产品规则如「必须使用 Redis」是架构决定应进设计文档而非本文件规则与实现互相矛盾规则说「禁止静默失败」代码里却catch后不留痕——规则 3 要求立刻修复或更新规格用「推测」填补歧义遇到模糊点直接写一条「大概如此」的规则——违反规则 2正确动作是标记规格缺口并澄清。最后回到模板 index.md 的收尾提醒模板中所有文件都应视为起点占位符、示例与示例命令必须替换为真实项目细节后再投入使用。PRODUCT_SENSE.md 的价值不在于文件本身而在于它把「产品判断」从不可检索的隐性知识变成了 Agent 与人类都能引用、检查和质疑的仓库事实——这恰恰是「仓库即系统记录」repository as the system of record在产品维度的最终落点。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐PRODUCT_SENSE.md 产品判断文档在 Agent 化仓库中固化代码无法推断的产品决策PRODUCT_SENSE.md 产品判断文档在 Agent 化仓库中固化代码无法推断的产品决策 output_article用 PRODUCT_SENSE.md 固化产品判断learn-harness-engineering 中 Agent 可检索的产品感文档设计用 PRODUCT_SENSE.md 固化产品判断learn harness engineering 中 Agent 可检索的产品感文档设计 本篇技术指南聚焦PRODUCT_SENSE.md 产品感知文档如何在 Harness 工程中把「不可见的判断」编码为仓库的持久事实PRODUCT_SENSE.md 产品感知文档如何在 Harness 工程中把「不可见的判断」编码为仓库的持久事实 导读 本文深入讲解 learn harne创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考