Agent Skills 工程化实践 02：先对齐问题，再让 Agent 动手

先说结论

很多 AI 返工并不是因为实现能力不够，而是因为双方从一开始就没有在讨论同一件事。grill-with-docs 处理的正是这个入口：它把需求当成一棵 design tree，按轮次询问当前已经可以回答的 frontier，并在过程中把稳定下来的术语和决定留在项目文档里。

它的约束也很明确：在 codebase 中工作时，不能只做一次无状态的问答；要留下能让下一次 session 继续使用的 paper trail。

grill-me 与 grill-with-docs 的分界

没有 working directory，或者讨论的是一项还没有代码载体的产品、写作或业务决策，可以使用 /grill-me。它是 stateless interview，目标是把 loose idea 变成真实 decisions。

一旦问题属于某个 repo，就使用 /grill-with-docs。它复用 grilling 的分轮机制，同时调用 domain-modeling：挑战 overloaded terms，用 concrete scenarios 压测概念边界，必要时更新 CONTEXT.md 和 ADR。

两者都不是“多问几句再开始写代码”。真正的产物是共享理解：不在场的人只读这些上下文，也能知道我们讨论的对象、边界和选择。

一轮 interview 应该问什么

好的问题有两个特征：它们依赖已经确定的前提，而且答案会改变后续路径。

例如“给后台加一个导出按钮”看起来很小，但至少可能包含这些分叉：导出当前筛选结果还是全量数据？同步下载还是异步任务？权限按页面还是按数据行判断？失败时用户得到什么状态？文件格式是否属于已有 domain language？

这些问题不应该一次性全部丢给用户。grilling 会先询问当前 frontier；用户回答之后，依赖这个答案的下一层问题才会出现。这样可以避免 Agent 把后续决策偷偷当成默认值。

可以把它理解成：

已知事实 → 当前 frontier → 用户决策 → 新 frontier

Agent 负责查事实，用户负责做决定。这个分工很关键：文件结构、已有 API 和测试状态可以自行探索；产品边界、风险承受和取舍不能被模型从沉默中推断出来。

CONTEXT.md 不是项目百科

共享上下文最有价值的部分通常很短：项目里反复出现的术语、容易被误解的关系、以及会影响后续工作的约定。它不应该变成 spec、scratch notes 或实现细节的垃圾场。

一个好的 glossary 会让后续对话直接使用项目自己的词。例如，如果项目把一次“材料审查”分成 submission、review 和 decision，就不应该让 Agent 每次都用泛化的 request、task 和 result 重新命名。

ADR 也不应该记录所有讨论。只有 hard-to-reverse、surprising、trade-off-based 的决定，才值得留下为什么这样选。否则文档会沉积成一层越来越难维护的背景噪声。

一个可复用的对齐检查

在进入实现前，可以用四句话检查结果：

1. 我们正在解决的用户问题是什么？
2. 哪些词在这个项目里有专门含义？
3. 哪些决定已经确定，哪些仍在 frontier？
4. 下一个人只读 CONTEXT.md、spec 和现有代码，能否复述边界？

如果第四句的答案是否定的，继续写代码通常只会把误解变成更多文件。先让共享语言变清楚，后面的规格和 ticket 才有可靠输入。

我的判断

这组 Skill 最值得借鉴的不是“必须问多少个问题”，而是把对齐从一次性聊天变成可追踪的工作阶段：事实可以由 Agent 查，决策必须由人确认，稳定的语言要沉淀，尚未解决的分叉不能被悄悄填空。

来源与版本

• 相关 Skill：grill-with-docs
• 共享语言：domain-modeling
• Interview primitive：grilling
• 参考分支：main · 核验 commit：022fcc3 · 核验日期：2026-08-12