企业官网建设流程全解析

本文基于 learn-harness-engineering 仓库中 OpenAI 风格 Agent 优先文档模板的 docs/ja/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md 展开。该文档以「最小 Harness」为起点，面向需要长期运行编码 Agent（coding agent）的仓库，解决一个核心痛点：产品判断无法从代码中可靠推断。读完本文，你将掌握 PRODUCT_SENSE.md 的结构设计意图、四个核心字段与四条产品规则的填写方法、与产品规格/计划/设计文档的分工边界，以及如何在仓库中把它变成 Agent 可检索、可引用的「产品判断系统记录」。

一、这份文档要解决什么问题

任何由 Agent 长期维护的代码仓库，都会遇到三类「代码回答不了」的问题：

1. 产品判断不在代码里：为什么这个功能是A而非B？为什么这个报错必须对用户可见、而不是静默吞掉？这些判断散落在产品经理的聊天记录、PR 评论或某位工程师的脑子里，唯独不在代码里。
2. 会话记忆不持久：一次会话的上下文窗口再大，也无法跨会话、跨 Agent 传递判断。新会话的 Agent 面对同样的代码，会重新做出不同（甚至相反）的猜测。
3. 推测被误当成授权：当规格存在缺口时，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 的优先级：

1. 将AGENTS.md与ARCHITECTURE.md复制到仓库根目录；
2. 复制整个docs/目录树；
3. 首先填写docs/PRODUCT_SENSE.md、docs/QUALITY_SCORE.md、docs/RELIABILITY.md；
4. 在docs/exec-plans/active/中添加第一个激活计划；
5. 入口文件保持简短，把细节引导到链接的文档中。

之所以「先填写 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 プロダクトコア（产品核心）：四个必填字段

原文档要求用四个字段钉死产品的基本盘，每个字段都是[置き換え]（占位符，需替换为真实内容）：

这四个字段的粒度很讲究：前三个是「方向」字段，最后一个是「度量」字段。方向字段帮助 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 不可パターン（禁止模式）：四条红线

原文档用四个「反模式」划出底线，任何实现触碰其中一条即视为违反产品判断：

值得注意，第三条「表示状態の信頼できる情報源が不明確」与 ARCHITECTURE.md 中的严格依赖规则形成呼应——架构层用「UI 不得绕过 Runtime/Service 契约」「数据访问必须经 Repository 或等价适配器」来机械保证状态来源唯一，产品层则把它列为不可妥协的用户可见原则。

四、填写实操：从占位符到可用的 PRODUCT_SENSE.md

4.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 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 的「セッションの終了」）：

1. 更新激活中的执行计划；
2. 领域或层级发生有意义变化时更新 QUALITY_SCORE.md；
3. 推迟的债务记入 tech-debt-tracker.md；
4. 适时把完成的计划移入docs/exec-plans/completed/；
5. 让仓库停留在「下一步动作明确、可重启」的状态。

七、在 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 仅凭本文件 + 路由文档，能对「冲突时听谁的」给出唯一答案。

常见误区：

1. 把本文件写成需求文档：堆砌流程、步骤、字段级描述——违反规则 4；
2. 把实现细节混入产品规则：如「必须使用 Redis」是架构决定，应进设计文档而非本文件；
3. 规则与实现互相矛盾：规则说「禁止静默失败」，代码里却catch后不留痕——规则 3 要求立刻修复或更新规格；
4. 用「推测」填补歧义：遇到模糊点直接写一条「大概如此」的规则——违反规则 2，正确动作是标记规格缺口并澄清。

最后回到模板 index.md 的收尾提醒：模板中所有文件都应视为起点，占位符、示例与示例命令必须替换为真实项目细节后再投入使用。PRODUCT_SENSE.md 的价值不在于文件本身，而在于它把「产品判断」从不可检索的隐性知识，变成了 Agent 与人类都能引用、检查和质疑的仓库事实——这恰恰是「仓库即系统记录」（repository as the system of record）在产品维度的最终落点。