grill-with-docs：拷问之后，把答案写进代码仓库
grill-with-docs：拷问之后，把答案写进代码仓库

什么是 grill-with-docs？

grill-with-docs 是 TypeScript 大神 Matt Pocock 开发的另一个 AI 技能，和 grill-me 是“亲兄弟”。

grill-me 做的事情是：AI 通过持续提问，帮你在动手之前把所有模糊的地方想清楚。但 grill-me 有一个“缺点”——它不写任何文件。拷问结束，对话一关，刚才理清楚的思路就只停留在你的脑子里，下次打开一个新的 AI 会话，一切又要重来。

grill-with-docs 解决了这个问题。它运行的是和 grill-me 完全一样的拷问流程——一次一个问题，给出推荐答案，等你回答完再问下一个。但区别在于：每敲定一个术语，它就写进 CONTEXT.md；每做一个难以逆转的决策，它就生成一条 ADR（架构决策记录） 。

截至 2026 年 8 月，grill-with-docs 在 skills.sh 技能排行榜上以超过 58 万次的安装量排名第六。

主要功能

1. 有状态的拷问——会留“纸面记录”

grill-with-docs 的核心定位是 stateful（有状态的） 。其他拷问类技能只存在于对话会话中，会话结束就消失了；grill-with-docs 会把拷问过程中达成的共识写进代码仓库的实体文件里。

术语一旦敲定，立刻写入 CONTEXT.md 词汇表；决策一旦通过三道门槛，立刻生成一条 ADR。所有成果都保存在仓库里，下一次打开 AI 会话，这些文件还在。

2. 基于现有领域模型的压力测试

grill-with-docs 不会从零开始拷问你。它会先探索你的代码库，读取已有的 CONTEXT.md 词汇表、docs/adr/ 架构决策记录，以及项目中的实际代码。

你在规划中使用的任何术语，如果和词汇表里已有的定义冲突，AI 会立刻指出：“你的词汇表将‘取消’定义为 X，但你似乎指的是 Y——到底是哪个？”

你在陈述某个功能的工作方式时，AI 会去检查代码是否一致。如果发现矛盾，它会直接暴露出来：“你的代码取消了整个订单，但你刚才说部分取消是可能的——哪个是正确的？”

3. 一次只问一个问题

和 grill-me 一样，grill-with-docs 严格遵守“一次只问一个问题”的原则。等用户回答完，再问下一个。一次性抛出十几个问题只会让人不知所措。

每个问题 AI 都会先给出自己的推荐答案。你不需要面对空白的输入框发呆，只需要对 AI 的建议说“同意”或“不同意，应该是这样”。

4. 能查代码的绝不问你

如果某个问题可以通过查看代码库或现有文档找到答案，AI 会自己去查，而不是问你。你只需要回答那些需要人类做决策的事情。

5. 文档内联更新，不批量处理

grill-with-docs 最鲜明的特征之一：文档是“内联更新”的，而不是等到拷问结束再批量生成。术语一敲定，立刻写进 CONTEXT.md；决策一通过三道门槛，立刻生成 ADR。不攒、不等、不拖。

6. ADR 只给真正重要的决策

grill-with-docs 不会为每一个小决定都生成 ADR。它有三道门槛：

  • 难以逆转——以后改主意的成本是有意义的

  • 没有上下文时令人惊讶——未来的读者会想知道“他们当时为什么这样做？”

  • 真正权衡的结果——存在真正的替代方案，你出于特定原因选择了一个

三个条件全部满足，才生成 ADR。大多数会话产生的是一份更清晰的词汇表，几乎没有 ADR——这才是它设计的初衷。

如何安装 grill-with-docs

安装命令

在终端中执行以下命令：

bash
npx skills add mattpocock/skills --skill grill-with-docs

备选安装方式

你也可以通过完整 URL 安装：

bash
npx skills add https://github.com/mattpocock/skills --skill grill-with-docs

重要提醒

安装 grill-with-docs 本身是不够的。 这个技能的 SKILL.md 只有一行，它本身不包含拷问逻辑，而是把工作委托给另外两个技能：

  • grilling —— 提供拷问流程

  • domain-modeling —— 提供文档写入能力

所以你需要确保这两个依赖技能也可用。最简单的方式是直接安装完整的 Matt Pocock 技能包：

bash
npx skills add mattpocock/skills

这会一次性安装所有技能，包括 grill-me、grill-with-docs 及其所有依赖。

验证安装

安装完成后，通过以下命令确认：

bash
npx skills list

如何使用

安装后，在你的 AI 编程助手（Cursor、Claude Code、Codex 等）中输入斜杠命令：

text
/grill-with-docs 我想做一个XXX

然后 AI 就会开始拷问你，并在拷问过程中把共识写进代码仓库。

注意：grill-with-docs 不会主动调用自己，必须由你手动通过 /grill-with-docs 触发。

应用场景

场景一：在代码仓库中启动一个新功能

你有一个现有的代码仓库，现在要加一个新功能。需求还比较模糊，领域术语还没定下来，架构方向也不确定。用 /grill-with-docs，AI 会基于你现有的代码和文档来拷问你，并在过程中把所有敲定的术语和决策记录到仓库里。

场景二：跨模块重构

你要改一个数据模型或 API 的形态，影响范围跨越多个模块。这种重构最怕的就是“以为想清楚了，做着做着发现漏了什么”。grill-with-docs 会帮你把每个决策点都过一遍，确保没有隐藏的坑。

场景三：现有项目缺少领域文档

一个老项目，代码在，但没有人维护过 CONTEXT.md 或 ADR。你想理解这个项目的领域模型，但没有文档可读。用 /grill-with-docs，AI 会通过拷问你（以及阅读代码）来帮你们一起把文档补齐。

场景四：团队知识沉淀

不止是你自己用。grill-with-docs 生成的 CONTEXT.md 和 ADR 是实体文件，可以提交到代码仓库，团队成员都能看到。一个人用 grill-with-docs 理清的需求和决策，整个团队都能受益。

使用案例

案例一：从“想做个功能”到“有了词汇表和 ADR”

一位开发者在现有的电商仓库中想加一个“部分退款”功能。他输入 /grill-with-docs 我想加一个部分退款功能。

AI 先读取了仓库中已有的 CONTEXT.md，发现“退款”已经被定义为“整单全额退款”。于是第一轮拷问就是：“你的词汇表将‘退款’定义为整单全额退款，但你说的是‘部分退款’——这是一个新的概念，还是你要修改现有的定义？”

经过几轮问答，团队敲定了“部分退款”的定义，AI 立即更新了 CONTEXT.md。后续又讨论了退款审批流程、与支付系统的交互方式等决策，其中“是否允许部分退款后修改订单状态”这个决策通过了三道门槛，AI 生成了一条 ADR 保存在 docs/adr/ 中。

整个流程结束后，不仅需求理清了，仓库里还多了两份永久文档。下一次任何人打开这个仓库的 AI 会话，这些文档都在。

案例二：术语不一致的发现与统一

一个团队在规划一个“用户账户合并”功能。产品文档里用的是“合并”，代码里用的是“关联”，词汇表里写的是“绑定”——同一个概念，三个名字。

用 grill-with-docs 拷问时，AI 发现了这个术语冲突，直接指出来：“你的词汇表将‘绑定’定义为 X，代码中‘关联’函数做的是 Y，而你的方案里说的是‘合并’——这三者是同一个概念还是不同的概念？”

团队这才意识到术语不统一的问题。经过讨论，统一为“合并”，AI 更新了 CONTEXT.md，并建议在代码中做相应的重命名。

案例三：与代码矛盾的方案被及时发现

一位开发者在规划一个“批量删除订单”功能时，对 AI 说：“用户可以批量选择订单并删除，删除后订单状态变为‘已取消’。”

AI 去读了一下代码，发现现有的 Order.cancel() 方法会触发一系列副作用——发送通知、更新库存、记录审计日志。而“批量删除”显然不应该触发这些。AI 直接指出：“你的代码中取消订单会触发通知和库存更新，但你刚才说批量删除只是改状态——这两个操作是一回事吗？如果不是，你应该创建一个新的‘批量删除’流程，而不是复用取消逻辑。”

这个矛盾如果在写代码之前没发现，等代码写了一半再来改，成本就高多了。

案例四：Vercel 社区的真实案例

在 Vercel 社区中，有团队分享了他们使用 grill-with-docs 的真实经历：用它来创建了一个组件库，“规则直接活在代码里” 。这不是写一份文档然后指望大家去看，而是把设计决策、术语定义、架构原则全部以 CONTEXT.md 和 ADR 的形式保存在仓库中，与代码同源、同步、同库。

grill-with-docs 与 grill-me 的区别

维度grill-megrill-with-docs
有无状态无状态（stateless），不写任何文件有状态（stateful），写文件到仓库
输出只存在于对话中CONTEXT.md + ADRs
适用场景通用场景（生活、工作、创意项目）有代码库的场景
会话结束后成果只在你脑子里成果在仓库里，可提交、可共享

社区用户的实际反馈是：“最大的不同就是 grill-with-docs 会在你敲定决策后把要点写进文档，解决了 grill-me 不会同步写文档容易丢上下文的问题。实际用下来个人感觉后者体验确实更好。简而言之对于大部分的开发环境，grill-with-docs 可以替掉 grill-me。”

总结

grill-with-docs 解决的是一个非常实际的问题：AI 帮你理清了思路，但思路只存在于对话里。下次打开一个新的 AI 会话，一切又要重来。

grill-with-docs 的本质，就是把 grill-me 的拷问成果固化到代码仓库里。术语写进 CONTEXT.md，决策写进 ADR。拷问结束，仓库里多了两份文档——下一次任何人打开这个项目的 AI 会话，这些文档都在。

  • 拷问流程不变：和 grill-me 一样，一次一个问题，带推荐答案

  • 成果会落地：术语和决策写进仓库文件，可提交、可共享

  • 基于现有代码：AI 会先读你的代码和文档，再提问

  • 生态验证：58 万+安装量，全榜第六

如果你在代码仓库里工作，并且希望 AI 帮你理清需求的同时还能留下文档，grill-with-docs 应该是你首选的拷问技能。