Grill-with-Docs：让 AI Agent 在动手前先把你问倒

Smars
Agent skill , AI 效率
08 Jun, 2026

你让 AI Agent 建一个功能，它跑了一天，最后你一看——不是你要的。

不是 bug，不是性能问题，是根本理解错了。你以为 Agent 懂你的业务逻辑，它以为你在说另一件事。这种错位不是偶然的，它是 AI 编码的默认状态。

Matt Pocock 的 skills 仓库有 12 万星，但最核心的技能不是哪个代码生成器或测试框架，而是一个叫 grill-with-docs 的东西——它的工作很简单：在你动手之前，用一连串追问逼你把每个设计决策想清楚。

问题不在 Agent，在沟通

大多数 AI 编码失败源于一个基本问题：你和 Agent 之间缺少共享语言。

你脑子里有一个业务模型——“用户”指什么、“取消”意味着什么、“订单完成”的边界在哪。Agent 脑子里是另一套东西——它从代码里猜，从 README 里猜，从你的 prompt 里猜。两个模型对不上，代码自然跑偏。

grill-with-docs 的做法是反直觉的：它不让 Agent 写代码，反而让它问你问题。一个接一个，一次一个分支，直到整个设计树被走完。

它怎么工作

grill-with-docs 是 Matt Pocock 的 skills 仓库中的一个 engineering skill。安装后，你在会话中触发它，它会：

先探索你的代码库——如果答案能从现有代码中获取，它不会问你，自己去看
对照你的领域模型挑战你的方案——你用了某个术语，它翻出 CONTEXT.md 看你是否和已有定义冲突
用具体场景测试设计决策——不只是问”你觉得怎么处理边界情况”，而是直接说”用户 A 在订单 B 的状态 X 下执行操作 Y，会发生什么”
实时更新 CONTEXT.md 和 ADR——术语一旦澄清就立刻写进去，不做事后总结

CONTEXT.md 是一个纯术语表，不包含实现细节。它和代码无关，只记录你们对领域概念达成了什么共识。

/
├── CONTEXT.md          ← 领域术语表
├── docs/
│   └── adr/            ← 架构决策记录
│       ├── 0001-event-sourced-orders.md
│       └── 0002-postgres-for-write-model.md
└── src/

为什么要先问再做

这听起来很慢。但对比一下正常流程：

没有 grill-with-docs： 你描述需求 → Agent 理解（可能错了）→ Agent 写代码 → 你发现不对 → 你纠正 → Agent 重写 → 你发现又不对 → 再纠正 → 再重写。一个功能来回三四轮是常态。

有 grill-with-docs： Agent 问你 20-40 个问题 → 你逐一回答 → 术语和决策被记录 → Agent 开始写代码 → 一次做对。

前者看起来快，因为追问阶段不产出代码。但后者省掉了所有返工。

Matt Pocock 的原话说得很直接：

“The most common failure mode in software development is misalignment. You think the dev knows what you want. Then you see what they’ve built — and you realize it didn’t understand you at all.”

这套逻辑在 AI 编码时代同样成立，甚至更严重。人类开发者可以通过代码评审发现理解偏差，AI Agent 不会主动质疑你的需求。

什么时候用它

grill-with-docs 不是每次交互都需要，但在以下场景价值巨大：

新功能设计：在写第一行代码前，用追问把边界条件、数据流向、异常处理全部理清
重构现有模块：Agent 先读你的代码和文档，确认它理解现有行为后再动手
多模块交互：当变更涉及多个模块时，追问能暴露模块间的依赖和契约
团队共享上下文：如果多人用同一个 Agent 工作，CONTEXT.md 成为唯一事实来源

它不擅长的事

小改动：改个变量名、调个参数，不需要 30 轮追问
探索性原型：你本来就想让 Agent 试几个方向看看，追问反而拖慢节奏
从零开始的空白项目：没有代码库可探索，没有现有术语可对照，grill-with-docs 的价值有限
快速验证想法：5 分钟跑个 demo 的时候，你不需要 ADR

安装

一行命令，自动安装到 30+ agent：

npx skills@latest add mattpocock/skills --skill grill-with-docs

安装后运行 /setup-matt-pocock-skills 配置 issue tracker 和标签词汇。

实际效果

grill-with-docs 最强大的地方不在于它问了什么问题，而在于它产出了什么——一份不断进化的领域模型文档。

假设你在设计一个电商系统的取消流程。正常对话中你可能会说”用户应该能取消订单”，Agent 会按自己的理解实现。grill-with-docs 会追问：

“取消是部分取消还是整个订单取消？”
“已发货的订单能取消吗？”
“取消后库存怎么回滚？”
“退款是立即还是异步？”
“用户取消和商家取消的处理一样吗？”

每个答案都会更新到 CONTEXT.md。下次你或你的团队再提到”取消”，所有人（包括 Agent）用的都是同一个定义。

这种共享语言的效果是复利的。每一次对话都在完善领域模型，下一次对话的起点就比上一次高。

真实使用示例

假设你在为一个 SaaS 项目添加”团队邀请”功能。你触发 grill-with-docs，对话大致是这样的：

你：我想加一个团队邀请功能，用户可以邀请别人加入自己的团队。

Agent： 先看一下你的代码库。你已经有 Team 和 Member 的概念了。“邀请”是指发送一个链接让陌生人注册后自动加入，还是先发送邀请，对方接受后才成为 Member？

你：先发送邀请，对方接受后成为 Member。

Agent： 好。邀请的有效期多长？

你： 7 天。

Agent： 一个团队最多能有多少个待处理邀请？

你：没限制，但超过 50 个以后我会警告团队管理员。

Agent： 记录一下。如果团队已经有 5 个待处理邀请，再发第 6 个，是拒绝还是覆盖最早的？

你：允许同时存在，不需要覆盖。

Agent： 接受邀请后，新成员的角色是什么？

你：默认是 member。团队管理员在发邀请时可以指定角色。

Agent： 如果邀请链接被泄露，别人拿到链接后在 7 天内没接受，第 8 天来用会怎样？

你：过期了，应该拒绝。

Agent： 好。还有几个边界情况：如果邀请发送者的团队权限被回收了，已发送的邀请还有效吗？

你：有效。邀请一旦发出就独立于发送者了。

Agent： 最后一个：如果两个人同时邀请了同一个邮箱，会怎样？

你：合并成一条邀请记录，不要重复。

对话结束。整个过程 Agent 问了 9 个问题，没有写一行代码。但 CONTEXT.md 已经更新了：

## 邀请 (Invitation)

- **定义**：发送给未注册用户的加入团队的凭证，接受后才成为 Member
- **有效期**：7 天，过期后不可接受
- **角色**：发送时可指定，默认 member
- **独立性**：邀请发出后独立于发送者，发送者权限变更不影响已有邀请
- **去重**：同一邮箱的重复邀请自动合并

然后你让 Agent 开始写代码。它基于 CONTEXT.md 里的定义实现，不会出现”过期处理不对”或”重复邀请没合并”这种漏网之鱼。