Agent Skills 实战第二课：先别写规格，用 /grill-with-docs 把需求问到底

第一课完成安装和项目初始化后，Agent已经知道该从哪里读工单、标签怎么用、领域文档在哪儿找。接下来，终于可以谈需求了。

但别急着让它写规格，更别急着生成代码。

“给用户加一个取消订阅入口”“后台支持批量导出”“订单失败后自动重试”——这些话听起来都像需求，其实只说了一个方向。业务术语是什么？状态会怎么变？异常路径有哪些？验收边界在哪里？这些都没讲清楚。这时候Agent写得越快，往往只是把猜测更快地变成了代码。

第二课只解决一个问题：

/grill-with-docs 到底在做什么

这个skill不是普通的需求问卷，也不是帮你生成PRD。它把两种能力组合在一起：

复制代码/grilling          负责沿着决策树追问，一次只问一个问题
/domain-modeling   负责校准术语，并把结论写入 CONTEXT.md 或 ADR

前者让需求变得清楚，后者让共识不会随着对话窗口一起消失。

完整的工程链路是这样的：

复制代码grill-with-docs -> to-spec -> to-tickets -> implement -> code-review

/grill-with-docs 位于最前面，负责把模糊的需求问清楚；下一课的 /to-spec 才负责把已经谈清楚的内容整理成规格。顺序不能反过来，否则规格只是把模糊的表达排版得更正式。

哪些需求值得先 grill

不是每个改动都需要开一场长访谈。下面这几类需求最值得使用：

• 产品只给出了目标，没有说明状态变化和验收边界；
• 同一个词，在产品、运营和代码里含义不一致；
• 会改变多个业务对象、权限规则或上下游系统；
• 团队正在争论方案，但真正的分歧还没有被说出来；
• 需求里出现了“自动”“实时”“批量”“完成”“取消”“有效”这类容易被误解的词；
• 一个决定以后很难修改，或者会形成长期架构约束。

如果需求已经非常明确，只需要把当前对话整理成规格，直接用 /to-spec。如果只想把一个术语或ADR补进文档，用 /domain-modeling 更直接。如果只想接受追问，但不需要写项目文档，用 /grilling 即可。

开始前要准备什么

第一课生成的 docs/agents/domain.md 应该已经存在，它告诉skill当前项目采用单上下文还是多上下文，以及领域文档应该放在哪里。

然后，准备一个真实需求。最好是正在排期、团队还存在分歧的，不要拿“新增一个按钮”这种已经没有决策空间的例子。给Agent的初始材料不需要很长，一段背景、一个目标、几条已知限制就够了。

例如：

复制代码/grill-with-docs我们准备在账户页增加“取消订阅”。用户提交后不再续费，
客服后台也要看到取消状态。希望本周确认方案，下个迭代开发。

注意，这条命令是在Agent对话框里运行，不是在终端执行。运行后先让它读取仓库。代码、配置和现有文档能回答的事实，应该由Agent自己查，不应再抛回给人。

一次合格的追问，必须遵守四条规则

第一条：一次只问一个问题

很多Agent喜欢一次抛十几个问题，看起来覆盖很全，实际回答质量很差。范围、术语、状态和异常混在一起，人只能给出一串不完整的答案，后面还得重新对齐。

/grilling 的规则是一次只问一个，等用户回答后再进入下一步。因为后一个问题往往依赖前一个答案。

举个例子，连“取消订阅”是什么意思都没确认，就开始问退款通知发什么模板，这个顺序已经错了。

第二条：每个问题都要带推荐答案

Agent不能只做会议记录员。它应该根据代码、现有领域文档和常见风险，提出推荐答案，让人可以直接确认，也可以指出为什么不适用。

一个合格的问题应该接近这样：

复制代码这里的“取消订阅”，是关闭下个周期的自动续费，
还是立即终止当前权益？建议：默认关闭自动续费，权益保留到当前计费周期结束。
原因：这与现有 paid_until 字段和账单逻辑一致，也能减少退款分支。

推荐答案不是替业务拍板。事实由Agent从环境中查，决定仍然由需求负责人确认。

第三条：沿着依赖关系追问

高质量追问不是问题越多越好，而是先解决上游决定，再展开下游分支。一般可以按这个顺序推进：

复制代码目标和范围
   -> 核心术语
      -> 状态与状态迁移
         -> 权限和触发者
            -> 异常与边界场景
               -> 验收结果

这不是固定模板。重点是，不要在前提还没确定时，提前讨论依赖它的实现细节。

第四条：能查到的事实不要问人

如果Agent想知道项目有没有 Subscription 状态、取消接口目前放在哪个模块、是否已有退款流程，它应该先读代码和文档。

只有真正需要人做取舍的问题才值得问。把搜索仓库也伪装成“需求澄清”，只是在浪费产品和工程师的时间。

用“取消订阅”完整走一遍

初始需求只有一句：“给用户加一个取消订阅入口。”一次合理的grill不会马上讨论按钮颜色或接口路径，而会逐层推进。

第一个问题：先拆掉模糊术语

Agent发现 CONTEXT.md 里没有定义“取消”，代码中却同时存在 cancel_at_period_end 和 terminated_at。它应该先指出这个冲突：

复制代码你说的“取消”可能对应两个不同动作：
1. 停止下个周期续费，当前权益保留；
2. 立即终止订阅和当前权益。建议把前者统一叫“停止续订”，后者叫“立即终止”。
本次需求默认做“停止续订”，是否确认？

用户确认后，skill应立即更新 CONTEXT.md，而不是等会话结束再批量整理。

复制代码**停止续订**：
关闭订阅的自动续费，当前权益保留到已支付周期结束。
_A void_: 取消订阅、关闭账号**立即终止**：
在当前时刻结束订阅权益，通常伴随退款或人工处置。
_A void_: 停止续订

这里记录的是业务词汇，不是接口字段、数据库结构或实现方案。

第二个问题：确认适用范围

术语确定后，才能继续问：“停止续订是否同时适用于付费用户、试用用户和企业套餐？”

假设团队确认第一版只支持个人付费套餐，试用和企业套餐维持原流程，这就是明确的范围边界。它会进入后续规格，但通常不需要单独写ADR。

第三个问题：用具体场景压状态机

不要只问“还有异常情况吗”，这种问题几乎得不到有效答案。Agent应该制造具体场景：

复制代码用户在扣款请求已发出、支付结果尚未返回时点击“停止续订”，
本次扣款应该继续完成，还是尝试撤销？建议：本次已开始的扣款继续完成，停止续订从下个周期生效，
避免在支付处理中引入新的竞态。

具体场景会逼出状态边界，也能直接变成后续测试用例的来源。

第四个问题：判断是否值得建立 ADR

假设团队最终决定：Billing 是订阅状态的唯一所有者，Account 模块只能通过领域事件申请停止续订，不能同步修改状态。

这个决定难以逆转，未来读代码的人可能不理解为什么不用同步HTTP，而且它来自一致性与可用性的真实取舍。三个条件同时满足，这时候才值得建立ADR。

相反，“按钮放在设置页”“接口返回204”“变量名叫cancellationReason”都不应该建ADR。它们容易修改，也不需要未来团队反复理解当年的架构取舍。

CONTEXT.md 应该写什么，不应该写什么

CONTEXT.md 是领域词汇表，不是需求文档，也不是技术方案。

应该写：

• 项目特有的业务概念；
• 一个术语的一到两句精确定义；
• 团队确定不用的近义词，写在 _A void_ 中；
• 多个上下文中概念的归属和区别。

不应该写：

• API路径、表名、字段名和类名；
• 某次需求的验收条件；
• 通用编程概念，例如timeout、exception、cache；
• 尚未达成共识的猜测；
• 一大段会议纪要。

如果仓库没有 CONTEXT.md，它会在第一个术语真正确定时再创建。没有术语需要记录，就不应该为了“流程完整”生成一个空文件。

ADR 要少，理由要硬

/grill-with-docs 不追求每场讨论都生成ADR。一个决定只有同时满足下面三个条件，才值得记录：

1. 很难回滚，未来更改成本明显；
2. 如果没有背景，后来的人会觉得这个选择很奇怪；
3. 团队确实比较过不同方案，并基于取舍做了选择。

满足条件后，ADR也不需要写成论文。最小版本只要讲清楚背景、最终决定和为什么。项目已有 docs/adr/ 时继续编号；没有时，在第一份ADR真正需要落地时再创建。

怎么判断 Agent 的问题质量

课堂上不要统计“它问了多少题”。问题多不代表需求清楚。建议用下面这张检查表逐题评分：

检查项	合格表现	不合格表现
单问题	一次只要求确认一个决定	一次抛出十几个问题
有依据	先读代码和文档，再提出问题	把仓库里能查到的事实问给用户
有建议	给出推荐答案和简短理由	只问“你想怎么做”
有顺序	先术语和上游决定，再问下游边界	前提未定就讨论实现细节
有场景	用具体角色、状态和时间点压边界	只问“异常怎么处理”
有沉淀	术语确认后立即更新glossary	所有结论只停留在聊天记录
克制写 ADR	同时满足三个门槛才建议记录	每个小决定都生成ADR

七项中，只要“有依据”“有顺序”或“有沉淀”明显不合格，这次grill就应该继续修正，不能直接进入 /to-spec。

常见误区

直接要求它恢复 /grilling 的规则：一次只问一个，等待回答后再继续。

先退回目标、术语和状态边界。实现方案依赖这些决定，不能提前替它们占位。

让它先检索仓库并引用证据，再提出真正需要人判断的问题。

删除接口、字段和验收细节，只保留项目特有词汇及其定义。

用“难回滚、反直觉、有取舍”三个门槛重新筛选。多数session没有ADR完全正常。

区分“必须现在决定”和“可以标记为待确认”。外部依赖无法当场回答时，记录负责人和后续动作，不要靠猜测强行闭环。