name: to-spec description: "把当前对话转成规格并发布到项目工单系统：不重新访谈，只综合已经讨论的内容。" disable-model-invocation: true
第 10 课 / to-spec
把已经讨论清楚的内容写成规格
它收拢已知内容，说明用户问题、解决办法、行为、实现决定、测试与范围外事项。
还不清楚 Skill、Agent、安装和调用？先读 从零开始的6节入门课。
一 / 读这一课之前
先把必要的概念讲清楚
这一课训练你把已经讨论清楚的想法写成别人能够实现、你能够验收的规格说明。先理解“系统已有的事实、用词和决定”，再理解“准备从哪里证明功能正确”。不要把模板填写完整误认为需求已经想清楚。
下面是老师补充的入门说明；原作者的要求保留在中英对照正文中。所有例子均为帮助理解而构造的教学情境。
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-spec description: "Turn the current conversation into a spec and publish it to the project issue tracker: no interview, just synthesis of what you've already discussed." disable-model-invocation: true
本技能根据当前对话，以及已经掌握的代码库情况，整理出一份规格说明。不要重新启动需求访谈，而应把已经讨论清楚的内容归纳成文。
你应该已经获得项目使用的工单系统，以及分诊标签的对应说明。如果没有，就告诉用户先运行 /setup-matt-pocock-skills。
This skill takes the current conversation context and codebase understanding and produces a spec. Do NOT interview the user; just synthesize what you already know.
The issue tracker and triage label vocabulary should have been provided to you. If not, tell the user to run /setup-matt-pocock-skills.
执行过程
Process
- 如果还没有查看过项目仓库，就先探索仓库，了解代码库的当前状态。整份规格说明都应使用项目业务术语表中约定的名称，并遵循本次涉及部分的架构决策记录（ADR）。
- 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 spec, and respect any ADRs in the area you're touching.
老师讲解 · 对应上方原文 · 含教学举例
第一步：了解现状、统一用词、遵循已有决定
这句话包含三个连续动作。repo 是代码仓库；explore 在这里是先查看、调查和理解。AI 要知道哪些功能已经存在、哪些数据和接口可以复用，才能写出接得上现有系统的规格。它不意味着开始修改代码。
以“收藏课程”为例。 AI 应先检查课程与课时如何区分、用户身份怎样确定、是否已有收藏或类似列表、有哪些接口和测试。假如已有“加入稍后学习”，就要先澄清它与收藏是否同一概念，不能直接建立第二套几乎重复的能力。
“使用领域术语表”要求名称和定义一致。若课程指一组课时，规格就不能一会儿把课程写成整套内容，一会儿写成单节内容。没有正式术语表时，参考已有文档和代码、标出歧义，是教师补充的处理建议，不是原句已经提供了答案。
ADR 是已记录的架构决定。 假设相关 ADR 规定所有修改数据的操作经过后端权限检查，收藏功能就应遵循。若新需求要求改变该决定，先说清冲突与理由。respect 译为“遵循”比“尊重”更能表达这里的工程约束，但也不是说架构决定永远不能修改。
- 大致说明准备从哪些测试接入点验证这个功能。优先复用已有接入点，而不是新建。尽可能选择层级最高的测试接入点。如果确实需要增加，也应提议把它放在尽可能高的层次。作者希望整个代码库中的这类接入点尽量少，理想情况下只有一个。
与用户核对：这些测试接入点是否符合其预期。
- 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.
老师讲解 · 对应上方原文 · 含教学举例
第二步：从哪里进入系统，才能证明功能正确
这段在解决什么问题？ 在写规格时，先说清楚将来从哪里验证功能，才能让实现者和验收者对“怎样算做对”有共同认识。这里并不是要求立刻写好全部测试。
1. seam 在这里是什么意思？
seam 字面上是“接缝”。在本段测试语境中，可以理解为：测试从哪里进入系统，触发功能并检查结果的边界。因此，译为“测试接入点”更容易把握它的用途。
例如，验证课程收藏功能，可以选择不同入口：
- 从页面进入：点击“收藏”，检查按钮和收藏列表发生了什么变化。
- 从接口进入：调用“创建收藏”接口，再查询记录是否保存。
- 从内部函数进入：单独调用一个去重函数，检查它返回什么结果。
这三种测试观察的范围不同。仅仅证明去重函数正确，还不能证明用户身份传对了、数据真的保存了、页面也显示正确了。
2. “最高层”是什么意思？
意思是尽量靠近功能对外提供的完整行为，让一次测试验证内部多个步骤。假设收藏接口内部依次识别用户、检查重复、保存记录，从这个接口开始测试，就可以把这些步骤连起来检验。
一个具体用例是：“同一用户收藏同一课程两次，最终只保留一条记录。”以后即使 AI 把内部函数拆开、合并或改名，只要公开约定没有改变，这条测试仍然有意义。
但是，“最高层”不能机械理解为所有测试都必须打开浏览器。接口已经能够完整、稳定地验证的行为，可以从接口检查；按钮能否点击、页面状态是否正确等交互问题，则还需要覆盖页面。
3. 为什么优先复用已有接入点？
项目已经有稳定的功能入口时，从它进行验证，更容易检验用户实际会经过的路径。每次为了测试另造新入口，可能使测试走的路与真实功能走的路逐渐分开。
原文说“优先已有入口”，并没有禁止新增。确实需要新入口时，应说明理由，并讨论能否把它放在较高、稳定的行为边界。
4. “理想数量是一个”，难道整个项目只写一个测试？
不是。作者这里说的是接入点数量，不是测试用例数量。同一收藏入口可以检查正常收藏、重复收藏、未登录、课程不存在等许多情形。
这表达了作者尽量减少测试对内部结构依赖的设计偏好，不是所有系统都只能保留一种测试入口的定律。你可以把整段要求理解为：先明确准备从哪个稳定的对外入口证明功能正确，优先复用现有入口，尽量验证完整行为。
- 使用下面模板编写规格，再发布到项目的工单系统。添加
ready-for-agent分诊标签，表示已具备交给 Agent 执行的条件，不需要再经过一轮分诊。
<spec-template>
- Write the spec using the template below, then publish it to the project issue tracker. Apply the
ready-for-agenttriage label - no need for additional triage.
<spec-template>
用户遇到的问题
从用户的角度，说明他目前遇到了什么问题。
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 标签表示按作者流程可以领取，不代表代码已经实现。这里的“不访谈”也不能抹掉前文明确要求的测试入口确认：不重开整轮需求访谈，与确认一个关键决定可以同时成立。
不在本次范围内的内容
明确说明哪些事情不属于这份规格要实现的范围。
Out of Scope
A description of the things that are out of scope for this spec.
补充说明
记录与这个功能有关的其他说明。
</spec-template>
Further Notes
Any further notes about the feature.
</spec-template>
三 / 你问我答
先作答，再看参考思路
Q1 · 理解
用自己的话说明：它解决什么问题，完成后会留下什么？
请各用一句话回答。若它只做规划或解释，不要把“已开发”“已部署”写成产物。
Q2 · 判断
为何原文“不再访谈”与“确认测试入口”并非完全同一件事？
我已思考，查看参考思路
不再访谈是避免重做需求发现；测试入口是局部验证约定。执行时应利用已确认信息，不借此重启整轮需求讨论。
Q3 · 追问
原文中哪条要求在你的环境下可能不成立？
说出具体一句及其前提，例如工具不可用、资料缺失、已有项目约定冲突，或它只是作者偏好。把你的答案带回课堂，我们据此继续讨论。
课堂回传格式：第 10 课 / 我的理解 / Q2 回答 / 仍不理解的原句。这里是阅读教材；实时问答在我们的对话中进行。
四 / 应用场景讨论
把方法放进一个具体情境
教学案例：教材网站的规格必须保留“先讲解、原文对照、再问答、应用后置”。若它生成“第一天立即部署代码”，即使文档齐全，也背离了已确认目标。
边界与容易误读的地方
详尽的用户故事不意味着允许扩大范围；就绪标签也不能替代检查。尚未决定的关键内容要显式暴露。
讨论后再实践：先判断上述情境是否适用，再选择真实任务。现在无需安装、运行命令或修改现有项目。