AI 入门 8：使用 AI 编写产品文档

人工制作的文档

根据通话原始转写整理的行文。本课程仅使用了与产品文档、Markdown、Codex、转写和 Neuronet 相关的片段。

有些人已经在使用一种更适合 AI 的 Markdown 格式写作：这样他们就拥有了一个超强能力，可以在自己的 Codex 或 Claude Code 中，为产品的每个方向建立知识库，让 AI 模型能够很好地读取这个知识库、搜索文档并将其用作上下文。

还有一种更偏产品化的方法：Confluence，其中的文档首先是为人而写的，是为了让人来阅读文档。也就是说，Confluence 长期以来一直被用作人类知识库，而 Markdown 正逐步成为适合 AI Native 工作的格式。

这里需要理解的是，此前我们实际上已经尝试过几乎所有产品文档格式：MS Office、BaseCamp、Notion、Google Docs、Confluence、带图片的文档、在截图上用箭头标注的文档、视频、Loom 等等。在某个时刻，Loom 成为了进化的顶点：你不只是写文本，而是一边讲述，一边在屏幕上展示正在发生什么。用 Loom 格式制作产品演示、记录想法、解释任务和编写说明最为方便。

但 Loom 和 Google Meet 有一个共同问题：人们聊完后，有人看了录像，有人没看；有人理解了，有人没理解或忘记了；愉快地度过一段时间后，大家就各自散去了。对于高效的产品工作而言，这种方式并不够。对话本身不会转化为可持续的知识，供所有团队成员在任何时刻重复使用。

与此同时，AI 出现了，人们学会了生成文档。这带来了另一个问题：AI slop。生成了几公里长的文本，却没有人想读。即使以前，让人们阅读普通的、由人写成的大型文档就已经很难；现在情况更糟：一个人看到 AI slop 文本，从第一段就明白这是模型生成的，不想读，也不想为此花时间。于是，AI 会生成文本，但产品工作并不会因此自动变得更好。

真正的问题在于：如何正确地给 AI 投喂文档，让它确实能够帮助推进产品工作。文档依然是必要的。但它们必须以这样的方式组织：AI 模型能够在其中搜索、回答问题、收集上下文，并帮助新人快速进入项目。

我的简单经验是：产品工作以 Product 文件夹的形式存在于 Codex 中。一个非常重要的原则是：Codex 中的项目必须绑定到本地磁盘上的真实文件夹。也就是说，我会在本地创建一个 Codex 文件夹，在其中创建 Product 文件夹，然后通过 existing folder 在 Codex 中创建项目，并指定这个本地文件夹。这样就形成了简单的绑定关系：Codex 中的项目等于本地磁盘上的文件夹。

下一步，为了在团队内同步彼此的本地文件夹，你们需要在 Product 项目中建立 Git 结构，并在每次工作会话后将更新推送到团队的 Github。其他团队成员会在开始工作前更新自己的本地文件夹，并在创建更新或新文档时向共享 Github 提交 commit。开发者在更新代码时的工作方式大致也是如此。

接下来，魔法从按不同聊天组织 Product 文件夹开始，这些聊天也被称为 agent。你们会在 Product 文件夹中，针对工作所需的每个产品主题创建许多聊天。这里没有规则：你可以把与利益相关者的 kickoff、与团队的同步会，或与其他团队的同步会作为主题。例如，我们有一份 PRD 文档。我会为 PRD 创建一个单独的聊天（agent），并开始将所有与 PRD 产品工作相关的源材料放进去。这样，你就将所有源信息上传到这个聊天中，而 AI Codex 现在已经了解完成 PRD 文档工作所需的一切上下文。

而我们在开始时最常有哪些源材料？首先是 Google Meet，也就是工作会议中的对话。Shurick 来了，主持了一次 kickoff，布置了任务。之后我们与团队讨论任务，于是就有了几场 Google Meet，作为第一手来源。它们是高质量的信息，因为它们来自当事人之口。

如果出现一个新主题，例如 PlayCanvas，我会在 Product 文件夹中创建新的聊天（agent），并直接写道：我们将在这里完成所有与 PlayCanvas 相关的产品工作。创建后一定要正确且简短地重命名这个聊天，以便清楚知道其中正在开展什么工作。重要的不只是将 MD 文件存放在 Codex 中，而是要创建一个正常的工作空间，让 Codex 理解我们当前正在处理哪个主题。

对于 Google Meet 的转写，我使用一个名为 Command Center 的迷你应用。在 Xsolla，有使用迷你应用和设计原型的文化：你可以通过 Neuronet 用 vibe coding 为自己的内部流程制作自动化。Command Center 正是我用来将 Google Meet 转换为符合我所需格式的转写文本的工具。

以前的工作方式不同：需要录制 kickoff，然后自己重新看一遍，仔细研读，提取重要内容，再整理成文档。对于 Shurick 的重要 kickoff，我至今仍手动处理，因为优先级很高；但对于每周几十场通话，处理流程本身已经改变。现在可以拿到一场一小时会议的 Markdown 格式转写，将它上传到所需的 Codex 项目和聊天中，给本地 agent 提供上下文，并请求：只针对我需要的主题给出摘要。如果会议讨论了很多内容，而我只关心其中一个部分，agent 能帮助快速提取恰好相关的部分。这节省了大量时间。整个过程只需三次点击：完成转写，将 MD-file 添加到 Codex，口述一分钟的上下文和处理任务，在 MD 文件中获得完成的结果，或者通过 Skill 直接发送到 Confluence。

为此，我在 Command Center 中接入了 Google Calendar。我可以获取会议，对其进行转写，转换成 Markdown，然后分发给 Product 项目的 Codex 文件夹中相关的 agent。这些 MD 文件成为信息的源层：不是为了文档而做的漂亮文档，而是可以上传到相关 Codex agent 聊天中、获取处理后的 MD 文件并进一步投入使用的材料——传给 Neuronet、用于形成 PRD、架构决策、answers 和其他产品工件。

这里的重要目标不是简单地制作一堆时髦的 Markdown 文件。目标是让整个团队使用相同的信息。不只是团队，整个公司也是如此；公司内部有许多人可以向 Neuronet 询问有关 Metasites 的事情。如果我们选取最好的 answers、PRD、架构决策、转写文本，并对 Neuronet 说：加载并更新有关 Metasites 的全部信息，那么它就会记住这一信息层，并能在此基础上回答问题。

因此，我们会拥有一个清晰的信息知识库：文档、架构决策、PRD、问卷、answers、额外的 PRD 和其他材料。这很重要，因为利益相关者、高层管理人员、合作伙伴、游戏开发者和其他流程参与者都会向 Neuronet 提问。如果有人需要了解什么，他不必私信某一位产品人员，而可以在公司共享的 AI 知识库中询问 Neuronet。

这样，我们实现了一个宏大的目标：全部 1600 人都能获得相同的信息。在 AI 出现之前，这类流程常常像传话游戏：七个人交谈、做出了一些决定，但其他人并不知情。在大型团队中，这是一个典型问题。信息传递链条越长，构思产品的人与之后必须使用它的人之间的鸿沟就越大。

Markdown 文件、Codex 和 Neuronet 有助于创建一个所有人都可访问的源信息层。更进一步，任何人都可以将这组 MD 文件作为 Source of Truth，加载到自己的 Codex 或 Claude Code 中，并完全处于与核心产品团队相同的上下文中。这对项目的新成员尤其重要：一个人可以安装 Codex，创建项目，将材料加载进去，然后开始提问：发生了什么，已经做出了哪些决定，North Star 在哪里，有哪些 PRD，kickoff 上讨论了什么。

因此，我尽量把有关 Metasites 的全部信息保存在 Markdown 中。这不仅是产品经理需要的，开发人员也需要。开发人员对新的 AI 流程抵触更强，但即使是离产品最远的开发人员，也仍然必须理解项目的 North Star，并看到我们正在向哪里前进。不应只有三位产品人员知道我们的任务是什么、想出了哪些想法，而是整个团队都应能访问全局图景。

我也会上传这些 MD 文件并要求 Neuronet 记住它们。这样，我们解决自身的产品问题，同时也将其解决方案传播到整个公司。我们得到的不只是文档集合，而是一个共同的 AI-readable 层：人可以阅读它，可以将其加载到 Codex 中，可以在 Neuronet 中基于它提问，也可以从中整理 PRD 和其他工作文档。

AI 入门 8：产品文档——目标与答案

唯一事实来源

现在来看一个重要模块：当我们在所需的 Codex 聊天或 agent 中添加了文档名称，并上传了所有源材料之后，该做什么。源材料可以是 Markdown 文件、Confluence 文档、旧的 PRD、转写文本、讨论中的回复，以及与该主题相关的任何其他文档。仅仅上传它们还不够。之后需要设定目标。

最佳实践

目标的表述非常直接：请在 Confluence 中查找我们所需文档的 best practice。例如，如果我们想创建 PRD、架构文档、开发任务说明或其他产品工件，我们会请 Codex 专门查找这一类文档的公司 best practice。Codex 会查找有哪些要求、该文档在公司中通常如何制作、哪些部分是必需的、有哪些质量标准、已经有哪些示例。

之后，Codex 应该向我们解释，如何按照公司的要求正确制作这份文档。这是重要的一步，因为我们不希望 AI 只是凭空想出一个漂亮的结构。我们需要未来的文档以真实的公司格式、既定的 best practice 以及公司内部已经形成的此类文档写法为依据。

模板

下一步：我们为 AI 设定目标，并说，请创建一个尽可能符合 best practice 的、我们所需文档的模板。此时，Codex 已经知道我们需要哪种文档，看过了源材料，并研究了公司要求。因此，它可以创建的不是一个随机模板，而是目标文档最准确、最高质量的模板。

这个模板必须手动检查。需要看它是否适合你的任务：它是大还是小、太宽泛还是太狭窄、其中的章节是否足够、是否过载。如果你需要的是短文档，模板就需要缩短。可以直接说：让这个模板更紧凑，我们需要一份简短的工作文档。如果你需要一份尽可能详细的文档，例如用于向开发团队布置任务，那么反过来就需要请求扩展模板：增加更多章节、更多细节、更多完成标准、更多用于风险、依赖关系和待解决问题的空间。

在这一步中，你会根据自己的任务调整目标模板。这不是机械操作。产品人员需要在这里看一看、感受一下：这个模板真的能帮助整理所需的文档，还是会把事情带偏。Codex 可以提供良好的基础，但究竟需要什么程度的细节，由你决定。

问卷

当源信息已上传、best practice 和公司要求已研究、模板已形成并调整后，需要对 Codex 说最重要的一句话：现在请将此模板与全部源信息进行比较，并检查为了完整且尽可能高质量地填写模板，我们缺少哪些信息。

之后需要请求：请针对缺失的信息制作 questionnaire，也就是包含所需数量问题的问卷。Codex 应该拿到目标模板、拿到所有源材料，将二者进行比较，并理解哪里存在空白。哪些章节我们目前无法填写？哪些决策尚未记录？哪些 assumptions 不清楚？哪里缺少业务目标、用户场景、技术限制、指标、风险、依赖关系、acceptance criteria？

在这一步需要谨慎。Codex 可能会制作一份有 200 个问题的问卷，而这样的文档会极难使用。在我看来，对产品或文档进行良好梳理的最佳问题数量大约是 40-80 个。这足以深入思考并提取缺失信息，但不会把流程变成无休止的问卷。

最终，Codex 会创建一个包含问题的独立 MD 文件。这不只是好奇问题的清单。这是一份为了实现目标——即基于具体源信息填写具体模板——它所缺少的信息清单。这样的 questionnaire 成为原始来源与高质量最终文档之间的桥梁。

答案

下一步：我们将这个包含 questionnaire 的 MD 文件放入 Codex，并说：现在请根据这份问卷逐个向我提问，并将结果写入 answers 文件。这里便开始了产品工作中最有价值的部分。

首先，产品工作变成了语音式的。Codex 问第 1 个问题，你用语音回答。然后是第 2 个问题，你回答。接着第 3 个问题，你回答。可以一个人回答，也可以和团队一起完成问卷。无需一开始就坐下来写出完美的文档。你只需回答自己对问卷所提出问题的想法。

其次，产品工作会变得更加精确。这不再是 AI-slop，不是一长串生成的文本，而是来自第一手来源的产品信息：来自产品团队、方向负责人、真正理解现状的人。Codex 不会替你凭空构思产品。它帮助你正确地提问、收集并结构化你所知道的内容。

这对产品工作来说是最大程度的 life change，因为你现在不需要再“从一张白纸”开始写文档——这一直都极其困难且耗费精力。你也不必生成与产品上下文无关的 AI slop。你亲自从第一手来源出发，基于自己的知识、想法和创意，用自己的声音创建内容。

在回答过程中，需要关注问题的质量。随着时间推移，你会开始感觉到问题是否足够好。如果问题重复、过于单调、过于抽象，或者无法帮助思考，也没关系。你可以立刻告诉 Codex：这些问题太单调了，请让问题更精确、更具产品性、更多样化，并围绕这个主题或另一个主题的本质。问卷可以在过程中调整，此后的问题会越来越准确。

最终，你会得到一个非常强大的 answers 文件。它本质上是有关产品信息的第一手来源。这是来自产品团队的第一手信息。这样的文件可以作为项目的 source of truth：上传到 Neuronet、交给新人、添加到 Codex 中、作为未来文档的基础。

只有在这之后，我们才进入最终文档阶段。最终命令是：基于我们的 answers 和全部源信息填写模板。现在 Codex 不再是在真空中工作。它拥有公司的 best practice、目标模板、源材料，以及产品团队对于填补信息缺口的问题所给出的回答。

正因如此，最终文档不再是 AI-slop，而是一份在实质上高质量的文档。它由真实信息组成，经过问题验证，按照正确模板进行结构化，并符合公司所需的格式。这与在一个空聊天中请求“写一份 PRD”相比，是完全不同层级的工作。

生成后，最终文档需要检查。需要应用 skill 或进行单独一轮检查来替换拼写错误，尤其是术语错误，因为产品文档中名称、内部术语、产品名称和技术表述经常出问题。然后需要亲自阅读文档。

当你学会熟练完成这一流程后，最终文档会非常准确，并且可以相当快地审阅。但在最初阶段，最好仔细校对。这样你会开始感觉到：在哪里 AI 没有足够高质量地传达你的想法和创意，在哪里它弱化了重要细节，在哪里错误解读了回答，在哪里需要修改用于创建或填写模板的 prompt。

我强烈建议使用这一机制。它帮助所有人保持一致。而且不仅是参与会议讨论产品的三位产品人员，而是整个项目团队和整个公司。我们获得了一种共同方式，用于将对话和分散来源转化为高质量文档、answers、source of truth 和关于产品的共享知识层。

AI 入门 8：产品文档——工作流

如果概括实际的 workflow，它是这样的。

首先，创建本地项目文件夹，并通过 existing folder 将其连接到 Codex。重要的是，Codex 项目应当与真实的文件结构相连，而不是抽象地存在于某个地方。

然后，在项目内部创建按主题划分的 agent——聊天：PRD、架构决策、answers、来源、kickoff、各个产品方向。名称必须清晰，因为这个结构将作为项目地图发挥作用。

之后，收集第一手来源：kicoffs。Google Meet 转写、Loom、笔记、旧文档、Confluence 材料、链接、讨论中的回复。它们可以放入主题文件夹，也可以作为附件直接添加到正确的 Codex 聊天或 agent 中。在这一阶段，不需要试图立即做出完美的最终文档。重要的是收集完整的信息源层。

接着，将通话和会议转换为 Markdown。为此可以使用 Command Center 或其他用于转写的迷你应用。关键在于结果必须是文本形式，存放在项目文件夹中，并可供 Codex 访问。

然后，请 Codex 查找目标文档的公司 best practice：PRD、架构文档、任务说明、战略或任何其他格式。Codex 应该理解公司内部通常如何制作此类文档。

之后，请 Codex 根据找到的 best practice 创建目标文档模板。手动检查并调整模板：如果需要紧凑文档，就缩短；如果需要深入的任务说明，就使其更详细。

然后，请 Codex 将模板与全部源信息进行比较，并确定缺少哪些信息。基于这些空缺，Codex 制作 questionnaire——一个包含问题的独立 MD 文件。最好将问卷保持在大约 40-80 个问题的范围内，以使其足够深入，同时仍具可操作性。

接下来，请 Codex 根据 questionnaire 逐个提问，并将回答记录到 answers 中。在此阶段，我们通过语音或文本提供来自第一手来源的产品信息，而 Codex 将其仔细收集到一个结构化文件中。

之后，请 Codex 基于 answers 和全部源信息填写模板。这样便能得到最终文档，它基于真实来源、公司要求和团队回答，而非空泛生成。

最后，检查文档：校对、进行一轮拼写和术语检查、查看想法是否被正确传达。如果发现 AI 在某处没有足够准确地理解某个想法，就调整 prompt 或回到 answers。

最后，将经过筛选和规范化的信息层上传到 Neuronet 或其他共享 AI 知识库，以便不仅文档作者，而是整个团队都能从同一个事实来源提问并获得回答。

AI 入门 8：产品文档——Markdown

现在单独谈谈产品文档的存储结构。我们按照 AI-first 原则建立新的结构。所有文档源材料都应该使用 Markdown。这很重要，因为 Markdown 同样能被人、Codex、Claude Code、Neuronet 和其他 AI 工具良好读取。为了方便手动阅读 Markdown，可以使用 self-hosted Obsidian 或 Sublime Text。关键是让文档保持为简单的文本文件，可以存储在仓库中、提交 commit、阅读、搜索并加载到 AI 中。

为了使用这样的文档，每位参与者都可以在自己的 Codex 或 Claude Code 中创建项目，并与这个仓库同步。可以提交 commit，但有一条重要规则：不要在没有单独理由和约定的情况下修改已经完成的文档。如果需要新的产品文档，我们不重写旧文档，而是创建一个标明新版本的新文件。这能保留历史，使我们能够理解信息来自哪里，并避免破坏已经固定的工件。

文件夹结构按照文档角色组织。顶层将材料划分为 source of truth、secondary documents、calls，以及当前相关且正在准备的具体产品文档文件夹。也就是说，最有价值的第一手信息单独存放，次级材料单独存放，通话单独存放，而针对具体 PRD、ADR、战略、任务说明和其他文档的工作文件夹也单独存放。

在工作文件夹内部，有一条简单的语言规则：英文文件位于根目录，俄文文件位于 RU 文件夹中。这有助于避免混淆版本、更快找到所需文件，并避免在命名中制造混乱。如果文档同时以两种语言准备，结构应立即支持这种划分。

现在，所有文档都不再从白纸开始写。我们通过此前描述的流程形成它们：向 Codex 或 Claude Code 提供请求和源文档，询问所需文档的 best practice template，加载所有相关的 MD 文件，请求确定缺少哪些信息，并形成 questionnaire。如果 questionnaire 过大，例如有 100+ 个问题，就需要进行调整。通常大约 50 个问题就足够了；如果文档范围较广，有时是 40-80 个。

然后，将 questionnaire 加载到 Claude Code 或 Codex 中，进入“提问——通过语音接收回答”模式。我们回答文档中的所有问题。如果我们自己不知道如何回答，可以将问卷发给知识负责人或产品团队。在我们的语境中，例如可以发给 @d.dolgov：这样甚至更好，因为回答来自第一手来源，而不是由模型补全。

在回答之后，我们发出命令，根据 best practice template、综合数据库和 answers 形成所需文档。这里的综合数据是指收集到的全部信息：源 MD、Confluence、转写文本、source of truth、secondary documents、answers 以及额外澄清。

如果得到的文档不令人满意，这很正常。例如，开发团队可能会查看 ADR，并说文档的格式或内容组成不合适。在这种情况下，不需要从零开始。可以使用来自 Narrative Leader 或其他第一手来源的现成 answers.md 重写文档格式或内容组成。Answers 是宝贵的基础，不应仅仅因为最终文档的第一个版本不成功就将其丢弃。

如果在重写过程中添加了新信息、澄清或决策，则应当保留单独的工件或 Markdown handoff。这个文件需要 commit 到 GitHub 上该文档的文件夹中。例如，如果是 ADR，这样的 handoff 应位于 ADR 文件夹中。这条规则保护我们免于丢失上下文：任何新的输入都必须保留在来源中，而不只是消融在最终文本中。

如果需要向产品团队提出澄清问题，也可以立即再以 Markdown 形式创建一份问卷。采用这种方法，回答会很快，因为人们回答具体问题比阅读大篇幅文档并自行寻找哪里需要澄清更容易。

还可以查看共享的 Source of Truth 文件夹，那里保存了关于产品的最有价值信息。在创建新文档之前，不仅可以将当前材料加载到 Codex 或 Claude Code 中，还可以加载之前的问卷和 answers。如果 Source of Truth 中已经有 80、120 或 200 个来自第一手来源、包含最精确事实信息的问题和回答，这是绝不能忽视的巨大上下文。

Source of Truth 中的所有文档还会被复制到 Confluence 的 Metas/Metasdev 空间，之后上传到 Neuronet 和 Slack。目前这可以手动完成，之后可以自动化这种同步。其意义在于，Markdown 仓库成为 AI-readable 来源和工作基础，而 Confluence 仍然是人们熟悉的阅读与导航场所。

如果连续执行这一顺序数次产品迭代，我们将获得一大块始终可访问、来自第一手来源的产品信息。这是没有传话失真的信息，整个团队在所有方向上都能访问。这本身就是非常强大的结果：我们不只是编写文档，而是在构建产品记忆，它可以被阅读、扩展、重复使用并加载到 AI 中。

核心原则是：Markdown 文档不是为了 Markdown 而做的。它们是为了把对话、会议和分散的决策转化为人和 AI 都能使用的共享知识层。Codex 在这个过程中是本地产品工作的工具：它读取文件夹，帮助结构化来源、整理文档、提取讨论中的相关部分，并维护项目上下文。

在这个体系中，Neuronet 则成为更广泛传播已准备信息的方式：面向公司、合作伙伴、开发人员、管理人员以及所有必须理解正在发生什么的人。如果正确完成这个流程，我们就能缩小构思产品的人与之后必须开发、销售、支持或解释它的人之间的差距。

正因如此，我们使用 MD 文件、Codex 和 Neuronet，不是把它们当作时髦玩具，而是当作产品记忆的基础设施。对话本身会消失。并不是所有人都会看 Loom。没有人会自行阅读大型 AI 文档。而在 Markdown 中组织良好的源信息层，可以被阅读、搜索、加载到 Codex、在 Neuronet 中更新，并作为产品工作的活基础使用。