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

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

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

“给用户加一个取消订阅入口”“后台支持批量导出”“订单失败后自动重试”，这些话听起来都像需求，实际上只说了一个方向。业务术语、状态变化、异常路径和验收边界还没有被讲清楚。此时 Agent 写得越快，通常只是把猜测更快地变成代码。

第二课只解决一个问题：怎样用 /grill-with-docs 让 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，而不是等会话结束再批量整理。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

应该写：

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

不应该写：

• 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。

常见误区

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

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

Agent 问了代码里已经存在的事实。 让它先检索仓库并引用证据，再提出真正需要人判断的问题。

CONTEXT.md 变成了需求说明书。 删除接口、字段和验收细节，只保留项目特有词汇及其定义。

每次讨论都生成很多 ADR。 用“难回滚、反直觉、有取舍”三个门槛重新筛选。多数 session 没有 ADR 完全正常。

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