name: to-prd description: "把当前对话整理成 PRD 并发布到项目 issue 跟踪器；不访谈，只综合已经讨论的内容。" disable-model-invocation: true
第 38 课 / to-prd
历史对照：从产品需求文档到规格
这是已不在当前目录中的历史文件。本课保留对应提交的原文，帮助你理解旧文章和旧提示词。
历史文件，不在当前目录
本课使用下方注明的历史提交原文，帮助理解旧文章和旧提示词。请勿据此认定当前版本仍能直接调用该名称。
还不清楚 Skill、Agent、安装和调用？先读 从零开始的6节入门课。
一 / 读这一课之前
先把必要的概念讲清楚
这是 to-spec 对应的历史名称，产物称 PRD，即产品需求文档。这里沿用历史原文讲解规格如何形成，不把旧命令假定为当前可用入口。业务现状、统一词汇和测试接入点的理解同样适用。
下面是老师补充的入门说明；原作者的要求保留在中英对照正文中。所有例子均为帮助理解而构造的教学情境。
repo / repository｜项目代码仓库
保存项目源代码、配置、测试和文档，并通常用 Git 记录修改历史的地方。把它理解为“可追溯的项目工作档案”。探索仓库就是查看现有系统，不等于开始改代码。例如新增课程收藏前，应先看已有课程数据、用户身份和保存接口，避免另造一套。
spec / specification｜规格说明
把要解决的问题、预期行为、约束和验收依据写明确的文档。它比“做个好用的学习网站”具体：例如登录用户能收藏课程，刷新后仍保留，重复收藏不会多出记录。它不必规定每个内部函数怎么写，但应让实现者和验收者对同一结果达成一致。
domain glossary｜业务领域术语表
规定项目的重要概念叫什么、指什么。domain 在这里是业务领域，不是互联网域名。课程是一组课时，课时是一份学习内容；混用会把“收藏课程”实现成“收藏某一课时”。统一语言不仅统一拼写，还统一概念边界。
ADR｜架构决策记录
Architecture Decision Record 的缩写，记录一个重要技术决定、当时为什么选择它，以及接受了什么代价。例如规定所有写入经过后端权限检查。遵循相关 ADR，是在适用范围内延续已确认决定；新需求与之冲突时，应说明冲突和修改理由，而不是默默绕过。
seam｜测试接入点
作者在测试语境中指测试进入系统、触发行为并观察结果的公共边界。例如调用“收藏课程”接口，再通过“我的收藏”接口检查结果。入口可以是模块公开函数、服务接口或页面，并非一定是浏览器。选择高层稳定入口能覆盖内部多个步骤；入口少不等于测试场景少。
interface / API｜接口
使用者与一项能力交互时遵循的约定，包括可调用什么、传入什么、得到什么、失败怎样表示。接口可以是程序函数，也可以是网络请求。创建收藏接口接收用户和课程信息、返回收藏结果；它不需要向调用者暴露数据库表结构。这里的接口通常不是指页面外观。 本教材涉及更广义的“接口”时，还包括错误、调用顺序和约束等使用约定；不能把接口一概等同于网络 API。
schema｜数据结构与约束
描述数据有哪些字段、类型、关系和限制。例如收藏包含用户 ID、课程 ID、创建时间，并要求同一用户与课程组合唯一。改 schema 可能影响存储、接口和旧数据，因此它是工程决定，不只是给变量换名字。
acceptance criteria｜验收条件
明确规定结果满足什么才算完成，应尽量可观察、可检验。例如“收藏后刷新页面仍可见，重复点击只保留一条”。“体验很好”“代码完善”没有明确边界，难以判断。验收条件关注结果，不是把实现步骤换个标题列出来。
二 / 中英全文对照与精讲
读原文，理解每一步为什么这样做
左右内容按小节对应；窄屏先中文、后英文。两种语言均完整展示，对应讲解紧接在小节之后。译文传达原文要求；老师讲解补充概念、原因、例子与适用边界。
中文译文English · 英文原文
name: to-prd description: Turn the current conversation into a PRD and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed. disable-model-invocation: true
本技能根据当前对话，以及已经掌握的代码库情况，整理出一份产品需求文档（PRD）。不要重新启动需求访谈，而应把已经讨论清楚的内容归纳成文。
你应该已经获得项目使用的工单系统，以及分诊标签的对应说明。如果没有，就运行 /setup-matt-pocock-skills。
This skill takes the current conversation context and codebase understanding and produces a PRD. Do NOT interview the user — just synthesize what you already know.
The issue tracker and triage label vocabulary should have been provided to you — run /setup-matt-pocock-skills if not.
老师讲解 · 对应上方原文 · 含教学举例
历史用词与当前用词怎样对照
PRD 强调产品需求文档，spec 更广泛指规格说明。这份历史正文仍然写问题、方案、用户故事、实现和测试决定，所以不能只根据名称判断两者在此仓库必然有完全不同模板。
历史版本写缺配置时运行 setup；当前版本在相关位置改为告诉用户运行。翻译必须保留这种调用行为差异，不能为统一教材把两个版本悄悄改成一样。
你可以把本课用于读旧文章和旧提示词。准备实际执行时，仍需先辨认当前安装的名称和宿主支持。
执行过程
-
如果还没有查看过项目仓库，就先探索仓库，了解代码库的当前状态。整份产品需求文档（PRD）都应使用项目业务术语表中约定的名称，并遵循本次涉及部分的架构决策记录（ADR）。
-
大致说明准备从哪些测试接入点验证这个功能。优先复用已有接入点，而不是新建。尽可能选择较高层、能够验证完整行为的入口。如果确实需要增加，也应提议把它放在尽可能高的层次。作者希望整个代码库中的这类接入点尽量少，理想情况下只有一个。
与用户核对：这些测试接入点是否符合其预期。
- 使用下面模板编写 PRD，再发布到项目的工单系统。添加
ready-for-agent分诊标签，表示已具备交给 Agent 执行的条件，不需要再经过一轮分诊。
<spec-template>
Process
-
Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the PRD, and respect any ADRs in the area you're touching.
-
Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better - the ideal number is one.
Check with the user that these seams match their expectations.
- Write the PRD using the template below, then publish it to the project issue tracker. Apply the
ready-for-agenttriage label - no need for additional triage.
<prd-template>
老师讲解 · 对应上方原文 · 含教学举例
第一步：了解现状、统一用词、遵循已有决定
这句话包含三个连续动作。repo 是代码仓库；explore 在这里是先查看、调查和理解。AI 要知道哪些功能已经存在、哪些数据和接口可以复用，才能写出接得上现有系统的规格。它不意味着开始修改代码。
以“收藏课程”为例。 AI 应先检查课程与课时如何区分、用户身份怎样确定、是否已有收藏或类似列表、有哪些接口和测试。假如已有“加入稍后学习”，就要先澄清它与收藏是否同一概念，不能直接建立第二套几乎重复的能力。
“使用领域术语表”要求名称和定义一致。若课程指一组课时，规格就不能一会儿把课程写成整套内容，一会儿写成单节内容。没有正式术语表时，参考已有文档和代码、标出歧义，是教师补充的处理建议，不是原句已经提供了答案。
ADR 是已记录的架构决定。 假设相关 ADR 规定所有修改数据的操作经过后端权限检查，收藏功能就应遵循。若新需求要求改变该决定，先说清冲突与理由。respect 译为“遵循”比“尊重”更能表达这里的工程约束，但也不是说架构决定永远不能修改。
第二步：从哪里进入系统，才能证明功能正确
seam 的字面意思是接缝，但这里应理解为测试接入点：测试从哪里进入系统，触发功能并检查结果的边界。sketch out 要求先大致说明测试安排，不是立刻写出完整测试代码。
例如收藏功能可以从三个位置检验：在页面点收藏；调用收藏接口；单独调用内部的去重函数。它们覆盖的范围不同。只测去重函数，即使通过，也不能证明当前用户的身份正确传入、记录成功保存或页面显示正确。
“尽可能高”指尽量通过稳定的公开入口验证完整行为。 调用收藏接口，再查询该用户收藏列表，能串起权限、去重和保存。这比把测试分别绑定到多个私有函数更能抵抗内部拆分和改名。页面上的按钮状态本身有问题时，仍需要页面层验证；不能机械理解成所有测试一律调用接口或一律用浏览器。
原文说 Existing seams should be preferred to new ones，即“优先使用已有接入点，而不是新增”。这是偏好，不是禁止新增。确需新入口时，应说明理由，并尽量放在较高、稳定的行为边界。
“理想数量是一个”谈的是接入点，不是测试用例数量。 同一收藏入口可以检查正常收藏、重复收藏、未登录、课程不存在等多个场景。这是作者强调减少内部耦合的设计偏好，不是任何系统都只能留一种测试入口的定律。
从哪里测试，为什么要在写规格时说清楚？
这段解决的是“将来凭什么证明功能做对了”。 规格不只写愿望，还要使实现者和验收者对验证方式形成共同认识。
以学习网站的课程收藏为例，可以从页面点击收藏，也可以直接调用创建收藏接口，还可以只调用内部保存函数。这些是不同层级的测试接入点。选择入口，会决定一次测试能够验证到哪一段完整行为。
较高层是什么意思？ 假设接口内部先识别用户、检查重复，再保存记录。通过创建收藏接口测试，就能把这些步骤一起验证。例如：“同一用户收藏同一课程两次，最终只保留一条记录。”以后内部函数拆开、合并或改名，只要对外行为符合约定，这条测试仍有意义。
但较高层不等于一律打开浏览器。接口能够完整而稳定地验证的行为，可以从接口测；按钮交互本身是否正常，仍需要覆盖页面这一层。
为什么优先复用？ 如果项目已有稳定的收藏入口，就不必为了测试另造一套仅供测试走的路径。两套路径可能行为不同，测试通过却不能证明用户实际使用的路径正确。
“理想数量是一个”表达作者偏好，是尽量集中于稳定使用面的设计方向。它说的是接入位置，不是全项目只写一个测试，也不是所有项目都只能有一个入口。同一入口可以覆盖正常收藏、重复收藏、未登录等许多场景。
前一句关于仓库、术语表和 ADR 也同样重要：先确认项目已有收藏没有；分清课程与课时；再遵循例如“写入必须经后端权限检查”的既有决定。规格应建立在项目已经存在的事实、语言和约束之上。
用户遇到的问题
从用户的角度，说明他目前遇到了什么问题。
Problem Statement
The problem that the user is facing, from the user's perspective.
老师讲解 · 对应上方原文 · 含教学举例
问题与方案：先说明用户受什么影响，再说明改好以后怎样
问题陈述写用户当前遇到的困难；解决方案写用户将获得的能力。二者回答不同问题。把“缺少收藏按钮”当问题，已经过早把解法固定成按钮；更贴近用户的问题是“看见想学的课程后无法保存，之后很难再找到”。
同一例子的两段写法。 问题：学习者暂时没时间读完课程，离开后无法继续找到它。方案：允许登录学习者将课程加入个人收藏，并在一个固定位置查看、取消收藏。这样实现者知道要完成哪条用户路径，而不只是绘制一个图标。
从用户视角写，不代表隐藏必要约束。若收藏只在登录后提供、离线时不能保存，就应在适当位置明确。老师判断规格质量时，会问“做出来后，哪个人的哪一步困难消失了”。
解决办法
从用户的角度，说明这个功能将怎样解决问题。
Solution
The solution to the problem, from the user's perspective.
用户故事
列出一份充分详细、带编号的用户故事清单。每一项采用以下形式：
- 作为一位 <使用者或参与者>，我希望 <获得某项功能>，这样就能 <得到某种好处>。
<user-story-example>
- 作为手机银行客户，我希望查看各账户的余额，这样就能在安排支出时作出更有依据的决定。 </user-story-example>
清单应尽可能完整，覆盖这个功能已经讨论到的各个方面。
User Stories
A LONG, numbered list of user stories. Each user story should be in the format of:
- As an <actor>, I want a <feature>, so that <benefit>
<user-story-example>
- As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending </user-story-example>
This list of user stories should be extremely extensive and cover all aspects of the feature.
老师讲解 · 对应上方原文 · 含教学举例
用户故事：把角色、能力、收益连接起来
用户故事是“谁，希望做什么，以便得到什么”。它帮助你发现看起来同一功能其实包含不同角色和情境。它不是用户访谈的逐字稿，也不是某个函数的实现步骤。
例如：“作为学习者，我想查看已收藏课程，以便安排今天学习。”“作为学习者，我想取消不再需要的收藏，以便列表保持有用。”“作为未登录访问者，我想在尝试收藏时知道如何登录，以便理解为什么没有保存。”这些故事指向不同可验证行为。
原文要求清单非常广泛。应理解为认真覆盖功能各方面，而不以凑数量代替清楚。仍未讨论的访客权限、跨设备同步等需求，不能因为模板需要长列表就由 AI 自行确定。
已确定的实现决定
列出已经做出的实现决定，可以包括：
- 将创建或修改哪些模块。
- 这些模块的哪些对外使用接口将变化。
- 开发者已经澄清的技术问题。
- 架构方面的决定。
- 数据结构的变化。
- API 的输入、输出和行为约定。
- 具体交互方式。
不要写入具体代码文件路径或代码片段，因为这些细节可能很快随着代码调整而过时。
有一个例外：如果原型产生了一段代码，而且它比文字更准确地表达了某个决定，例如状态机、状态归约函数、数据结构或类型结构，就把关键片段直接放在对应决定下面，并注明来自原型。只保留承载决定的部分，不要把整份可运行演示搬进来。
Implementation Decisions
A list of implementation decisions that were made. This can include:
- The modules that will be built/modified
- The interfaces of those modules that will be modified
- Technical clarifications from the developer
- Architectural decisions
- Schema changes
- API contracts
- Specific interactions
Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
老师讲解 · 对应上方原文 · 含教学举例
实现决定：记录需要长期遵循的约定
模块、接口、schema 和 API 契约在这里是实现者必须共享的决定。schema 规定保存什么数据以及约束；API 契约规定请求、返回和失败语义。例如同一用户对同一课程只能有一条收藏，重复操作如何返回，应明确而一致。
原文通常不写具体文件路径，是因为移动文件并不改变业务要求。写“通过收藏服务保存且保证唯一性”通常比“改某目录第几行”耐久。它并没有禁止实施工单引用定位线索，而是强调规格要记录决定。
原型代码例外用来精确表达文字容易模糊的决定。例如状态转换表或类型结构可以少量内嵌。reducer 可理解为根据当前状态与事件计算下一状态的函数。保留决策核心，不应把未经完善的整套原型当作正式实现。
已确定的测试安排
列出讨论中已经确定的测试决定，包括：
- 什么才是好的测试：验证外部行为，不绑定内部实现细节。
- 准备测试哪些模块。
- 项目中有哪些类似测试，可以作为已有做法的参考。
Testing Decisions
A list of testing decisions that were made. Include:
- A description of what makes a good test (only test external behavior, not implementation details)
- Which modules will be tested
- Prior art for the tests (i.e. similar types of tests in the codebase)
老师讲解 · 对应上方原文 · 含教学举例
测试、范围与发布：让规格成为可接手的工作依据
测试决定应说明哪些对外行为会被验证、从哪个入口验证、可借鉴什么已有测试。验收时要能回答：在给定输入下，观察到什么才算对。写“增加测试”还不足以表达这个决定。
例如收藏测试通过公开接口创建，再通过查询接口确认只有当前用户看得见。不要只验证内部 save 方法被调用一次；那只能证明调用发生，不能证明真实收藏行为正确。
Out of Scope 划定本轮暂不做的内容，例如“本轮不做收藏夹分组和分享”，避免 AI 把合理但未经同意的想法全部实现。发布工单并加 ready-for-agent 标签表示按作者流程可以领取，不代表代码已经实现。这里的“不访谈”也不能抹掉前文明确要求的测试入口确认：不重开整轮需求访谈，与确认一个关键决定可以同时成立。
不在本次范围内的内容
明确说明哪些事情不属于这份 PRD要实现的范围。
Out of Scope
A description of the things that are out of scope for this PRD.
补充说明
记录与这个功能有关的其他说明。
</spec-template>
Further Notes
Any further notes about the feature.
</prd-template>
三 / 你问我答
先作答，再看参考思路
Q1 · 理解
用自己的话说明：它解决什么问题，完成后会留下什么？
请各用一句话回答。若它只做规划或解释，不要把“已开发”“已部署”写成产物。
Q2 · 判断
改名为 spec 后，你应该比较哪些内容，而不只是比较名称？
我已思考，查看参考思路
输入、输出模板、确认点、测试入口和外部写入行为。只有职责与约束吻合，才适合迁移旧流程。
Q3 · 追问
原文中哪条要求在你的环境下可能不成立？
说出具体一句及其前提，例如工具不可用、资料缺失、已有项目约定冲突，或它只是作者偏好。把你的答案带回课堂，我们据此继续讨论。
课堂回传格式：第 38 课 / 我的理解 / Q2 回答 / 仍不理解的原句。这里是阅读教材；实时问答在我们的对话中进行。
四 / 应用场景讨论
把方法放进一个具体情境
教学案例：旧交接要求“执行 to-prd”，当前环境找不到该名称。应先比较原文任务职责，再判断 to-spec 是否适合承接，不能凭名称相似直接替换所有旧规则。
边界与容易误读的地方
这是历史教学，不是当前安装推荐。历史规格中的未决问题不能因为模板完整而自动变为已确认。
讨论后再实践：先判断上述情境是否适用，再选择真实任务。现在无需安装、运行命令或修改现有项目。