mattpocock/skills 系列(2):把模糊需求问清楚,留下共用词汇
拆解 grill-me 与 grill-with-docs 的访谈流程,说明如何按照问题的先后关系厘清需求,并把确认过的词汇与少数重要决策写回项目。
你准备替订阅服务加入按席位计费功能。会议记录里同时出现“成员”“用户”和“席位”,却没有人确认三个词是否代表同一件事。在讨论禁用成员是否仍要收费前,团队得先说清楚计费对象到底是人、账号,还是一份可以分配的资格。
这篇提到的 skill,我会先把它理解成告诉 AI 编程助手如何完成特定工作的操作说明。mattpocock/skills 把厘清需求的工作拆成访谈、词汇整理与重新说明。这篇说明五个相关 skill 的分工,以及访谈结束后哪些内容会留在项目里。
mattpocock/skills 系列|第 2 篇
- 上一篇(第 1 篇):先设置项目规则,再用 ask-matt 找下一步
- 下一篇(第 3 篇):先找出缺口,再决定要写规格还是拆工作单
- 系列导读:这套 skill 是什么、六篇该怎么读
这篇我以
1.2.3版为准。
2026-10-04 发布的
1.3.0改了本文词汇表的文件名(2026-10-19 核实):
CONTEXT.md改为GLOSSARY.md。CONTEXT-MAP.md改为GLOSSARY-MAP.md。今后
grill-with-docs、domain-modeling、wait-what只会读写新文件名。所以按本文操作时,请把文中的CONTEXT.md换成GLOSSARY.md;已有旧文件的项目,用下面这条命令改名:
1git mv CONTEXT.md GLOSSARY.md我核实时,本文介绍的五个 skill 在最新的
1.3.1中都还在。我之后会按新版全面更新这个系列。
五个 skill:三个入口,两个内部流程
这五个 skill 不是一套必须依次跑完的步骤。你只要选一个符合目前状况的起点,其余工作会由内部流程接手。
| 角色 | skill | 直接用途 |
|---|---|---|
| 由你启动 | grill-me | 还没有项目文件夹时,通过访谈厘清想法 |
| 由你启动 | grill-with-docs | 已有项目时,一边访谈,一边整理文档 |
| 内部流程 | grilling | 按照问题的先后关系安排每一轮提问 |
| 内部流程 | domain-modeling | 统一项目用语,必要时留下重要决策 |
| 由你启动 | wait-what | 请 AI 补上背景并改用较直接的说法 |
grill-me、grill-with-docs 与 wait-what 都要由你点名启动,AI 不会自行使用。grilling 与 domain-modeling 则可以由 AI 自行采用,也能被其他 skill 调用。这项差异记录在启动规则。
两个起点区别在于是否留下文档
两个起点使用同一套访谈方式,差别在于访谈期间是否同时整理项目文档。
grill-me只负责开始访谈。它适合还没有项目文件夹的情况,例如讨论一个尚未成形的想法。它不会创建词汇表,对话结束后也不会在电脑里留下文档。
grill-with-docs会同时启动两个内部流程:grilling 负责访谈,domain-modeling 负责整理词汇与决策。项目文件夹已经存在时,ask-matt 会优先建议这个起点,详细条件可查看它的选择规则。
grilling 先问不能跳过的问题
grilling 会先找出问题的先后关系,原始规则称这种结构为“决策树”。如果某个问题必须根据前面问题的答案才能回答,AI 就会把它留到下一轮。
例如“禁用的成员要不要计费”,必须等计费席位的定义确认后才能回答。定义尚未确定时,AI 不应先猜禁用规则。每一轮的流程如下:
flowchart TD
A[找出问题的先后关系] --> B[列出当下所有能决定的问题]
B --> C[逐一编号,附建议答案]
C --> D[你回复]
D --> E{问题都处理完了?}
E -->|否| B
E -->|是| F[你确认双方理解一致]
F --> G[访谈结束]
grilling 的规则也说明谁负责回答。能从文档、代码或工具查到的事实,由 AI 调查;需要在不同做法之间取舍时,则由你决定。
AI 查资料时,不会让整轮提问停下来。只有需要那项资料的问题要等结果,其他问题照常先问。
domain-modeling 会创建项目词汇表
domain-modeling 里的 domain,指项目所处理的事物与规则。以本文的例子来说,就是工作区、成员、席位与计费方式。这个 skill 会把确认过的名称写进 CONTEXT.md,我把这个文件看成项目专用的词汇表。
如果只是读取词汇表并沿用现有名称,不必特别启动 domain-modeling。只有在旧定义可能有问题、名称不够清楚,或需要记录重要决定时,才需要它介入。
讨论名词时,AI 要做这几件事:
- 你使用的词和现有定义冲突时,立即指出差异。
- 遇到一词多义的名称,提出较精确的正式用词。
- 讨论名词之间的关系时,自己设想边界情况来测试定义,例如“成员被禁用后又重新激活,原本的席位还在吗?”,让双方把概念之间的界线说清楚。
- 你描述现有行为时,查阅代码。
若代码与你的说法不同,决定要沿用现状或改变行为的人仍是你。
确认词汇后,domain-modeling 会立即更新 CONTEXT.md,而不是等访谈结束再整理。这个文件只保存名称与定义,不放代码怎么写等细节。
由多个子项目组成的大型项目,可能每个子项目各有一份词汇表。这时放在项目根目录的 CONTEXT-MAP.md 就像索引,指出每份词汇表的位置。domain-modeling 的文档规则定义了这些界线。
重要的技术选择则可能写成 ADR,也就是 Architecture Decision Record,中文常译为“架构决策记录”。它是一份短文档,交代做了什么选择以及原因。原始格式允许 ADR 只写一段话,不要求为了填满模板增加内容。
只有下面三项条件都成立时,AI 才会提议创建 ADR,而且要你同意后才会写入:
- 这项决定日后很难修改。
- 没有背景就不容易理解。
- 当初确实比较过不同做法。
三项条件与格式可在 ADR-FORMAT.md核对。
wait-what 只处理刚才没听懂的内容
wait-what 是中途使用的修正入口。当 AI 的上一段说明跳得太快或缺少背景时,由你明确启动它。
它要求 AI 重新说明刚才的内容,并补上理解所需的背景。内容要沿用 CONTEXT.md 里已确认的词汇;若项目使用多份词汇文档,它会先从 CONTEXT-MAP.md 找到正确位置。
消息中的英文措辞要符合 ASD-STE100,这是一套限制技术英文用词与句型的规范。读者不需要先学会这套规范,它在这里的作用,是让 AI 使用较短的句子与固定用词。
完整指令只有一段,可在 wait-what/SKILL.md核对。它只要求重讲上一条消息,不会重新进行整场访谈。如果问题不只是一段话没听懂,而是整体需求仍然模糊,我建议回到 grill-with-docs 继续访谈。
访谈结果不会全部写进同一份文档
grill-with-docs 会写文档,不代表它会把所有答案都塞进 CONTEXT.md。访谈内容有三个去处:
| 内容 | 去处 | 例子 |
|---|---|---|
| 项目特有的正式名词与短定义 | CONTEXT.md | “计费席位”和“成员”各自代表什么 |
| 变更成本高、容易让后人困惑,且经过取舍的决定 | 经你同意后创建 ADR | 为何由负责计费的程序保存席位分配记录 |
| 其他功能行为、例外、默认值与完成标准 | 先留在对话,之后交给 to-spec | 禁用成员何时停止计费 |
CONTEXT.md 是词汇表,不是需求文档;ADR 也不是每项答案的流水账。大部分答案会先留在对话中。等你另外启动 to-spec后,这个 skill 才会把已确认的需求整理成一份供后续开发使用的功能规格。
访谈没有固定题数
两个起点没有各自的题库,它们都把访谈交给 grilling,而 grilling 也没有固定轮数或题数。所以访谈时间取决于有多少事情尚未决定,而不是你用了哪个 skill。
比起计算 AI 问了几题,我会检查三件事:
- 哪些问题已经有答案。
- 哪些问题还在等前面的答案。
- 词汇和 ADR 有没有写到正确的位置。
grill-with-docs 会修改项目文档,所以我认为团队仍要审查添加的词汇是否适合沿用,以及 ADR 是否符合三项条件。尚未谈妥的定义不该提早写入,否则下次接手的人或 AI 读到的只会是另一个含糊定义。
先看手上有没有项目,再选起点
我会先判断手上是否已有存放代码与文档的项目文件夹,再看卡住的是需求、词汇还是上一段说明。
| 目前状况 | 选择 | 不该期待它做什么 |
|---|---|---|
| 还没有项目文件夹,只想检查一个想法 | grill-me | 不会把结果写进项目文档 |
| 已在项目内,需要同时留下词汇或决策 | grill-with-docs | 不会直接产生供后续开发使用的完整需求文档 |
| 只想使用分轮提问的方法 | grilling | 不会自行维护词汇文档 |
| 只需要整理项目用语或重要决策 | domain-modeling | 不会收录所有需求答案 |
| 上一段说明没有听懂 | wait-what | 不会重新进行整场访谈 |
这张表是用来选择起点,不是执行顺序。
grill-with-docs 适合用一次对话就能厘清全貌的需求。如果需求大到无法在一次对话中厘清,ask-matt 的选择规则会改为建议 wayfinder。wayfinder 是另一个 skill,用来先探索大型工作,找出可以从哪里开始。
模拟场景:把席位问到能写规格
以下内容依原始规则推演。场景是你已完成上一篇的项目设置,现在要在订阅服务的项目文件夹内处理按席位计费。整段对话的走向如下:
sequenceDiagram
participant U as 你
participant A as AI
participant P as 项目
U->>A: 启动 grill-with-docs
A->>P: 读词汇、ADR 与代码
A->>U: 第一轮:不需其他答案的问题
U->>A: 确认席位的定义
A->>P: 立即写入 CONTEXT.md
A->>U: 第二轮:依定义追问
A->>U: 提议创建 ADR
U->>A: 同意
A->>P: 写入 ADR
U->>A: 启动 wait-what 要求重讲
以 Codex 这套 AI 编程助手为例,先输入需求并明确启动 grill-with-docs:
1
2
3
$grill-with-docs
我们要替现有订阅服务加入按席位计费。请帮我把需求问清楚。
AI 读取项目时,像“目前系统是不是依活跃成员人数向支付平台收费”这种能从项目里查到的事实,应由 AI 调查,不该丢回给你。
第一轮先处理不需要参考其他答案的问题。例如,收费依据究竟是已购买席位、已分配席位,还是活跃成员数?订阅又属于工作区,还是单一付款人?
假设团队最后确认,工作区拥有一批已购买的席位,成员获得席位后才可使用付费功能。domain-modeling 可以立即把词汇写成:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
**工作区**:
由多位成员组成,并共用一份订阅的空间。
_Avoid_: 账号、组织
**计费席位**:
工作区已购买、可分配给一位成员的付费资格。
_Avoid_: 用户、人数
**席位分配**:
在一段时间内,把一个计费席位分配给一位成员的记录。
_Avoid_: 成员资格、订阅项目
**成员**:
已加入工作区的人。成为成员与取得计费席位是两件事。
_Avoid_: 用户、席位
这段是我依 CONTEXT-FORMAT.md整理的示意内容。每个 _Avoid_ 都列出容易混用、往后应避免的名称。
有了这些定义,第二轮才能追问:
- 邀请尚未接受时,是否先保留席位。
- 成员禁用后,如何处理分配。
- 增减席位何时影响价格。
若现有代码直接以活跃成员数量计费,AI 也要指出新定义与现状不同,请你确认是否要改变行为。
假设团队进一步决定,由负责计费的程序保存每次席位分配的开始与结束时间,而不是拿现在的成员清单倒推过去的数量。这个做法方便日后查询历史记录,代价是每次成员变动时都要同步更新计费数据。
这项选择可能符合 ADR 的三项条件,所以 domain-modeling 应先提议创建 ADR,取得同意后才写入。
假设 AI 接着用一大段文字解释席位变动,但你没有弄懂“席位变动”和“席位分配”的关系。这时才启动 wait-what,要求它沿用刚写下的词汇重讲。
完成这段流程后,需求还没整理成完整规格。成果包括:
- 对话中已确认的答案。
CONTEXT.md里的词汇。- 少数经你同意创建的 ADR。
若这项功能要分好几次对话才做得完,下一步是在同一段对话中启动 to-spec,让它把需求整理成规格。
最值得留下的是可沿用的词汇
到这里,我谈到的启动方式与文档保存规则都有原始资料可查。但这些规则本身,无法证明共用词汇一定会改善团队合作。
我仍认为,厘清需求后最值得留下的,是下一个人能直接沿用的词汇,以及少数不容易从代码看懂的决策。问答会留在对话里,确认过的定义则能进入项目。
这项判断只适用于多人维护,或要分好几次对话才做得完的项目。一次性的想法讨论不需要为每个名词创建文档,使用 grill-me 完成访谈即可。
先让同一个词代表同一件事
要试这套流程,先找出需求中最容易产生歧义的一个词,例如“席位”。在项目内启动 grill-with-docs,先确认它和“成员”的关系,再讨论邀请成员时是否占用席位,以及禁用后何时停止收费。
访谈的目标不是累积问题,而是让后续规格里的同一个词始终代表同一件事。下一篇我会说明如何用 to-spec 整理规格,再用 to-tickets 把规格拆成一张张可以直接开工的工作单。
延伸阅读
grill-me:确认它只负责启动访谈流程。grill-with-docs:查看它同时启动哪两个内部流程。grilling:理解决策树、分轮提问与停止条件。domain-modeling:核对词汇文档与 ADR 的使用边界。wait-what:查看它要求 AI 如何重讲上一段内容。to-spec:确认访谈内容如何进入正式规格。



