grill-with-docs

grill-with-docs 技能概览

grill-with-docs 是一款面向规划与文档协作的技能，适合希望把设计方案放到仓库里现有语言和既有决策下“拷问”一遍的团队。它尤其适合 Technical Writing、以产品思维推进的工程协作，以及 AI 辅助的架构工作——在这些场景里，术语必须和 CONTEXT.md 以及 ADR 保持一致，而不是漂移成空泛的“只靠 prompt”的说法。

它的核心工作很直接：一次只问用户一个问题，给出推荐答案，并在问题能从源码或文档中解决时，优先使用代码库或文档。这让 grill-with-docs 比通用头脑风暴 prompt 更有用，因为真正的风险往往不是“想不出点子”，而是术语对不上、隐含假设没写明，或者决策记录已经过时。

grill-with-docs 的不同之处

它围绕的是领域感知，而不只是对话本身。这个技能会推动你检查已有上下文文件、扫描 ADR，并在决策逐渐明确时同步更新文档；也正因为如此，它在 grill-with-docs for Technical Writing 以及其他文档密集型流程里表现尤其好。

最适合的使用场景

当你需要以下事情时，使用 grill-with-docs：

• 验证方案是否符合现有领域模型，
• 选择准确的项目术语，
• 在决策形成时同步记录下来，
• 或者在实现开始前，先让草案和既有文档保持一致。

不适合的情况

如果你只想要快速摘要、润色过的规格说明，或者不依赖仓库上下文的自由发散，这个技能会比普通 prompt 显得慢。它的价值来自有纪律的追问和面向文档的核对。

如何使用 grill-with-docs 技能

安装 grill-with-docs

使用仓库标准的技能管理器，把 grill-with-docs 安装到你的 skills 目录中，然后在目标项目上下文里打开技能文件。基础安装方式如下：

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

可以把这一步视为 grill-with-docs install 的起点，然后确认这个技能在你实际使用的 agent 环境里可用。

从正确的输入开始

如果你的第一条消息包含以下信息，这个技能的效果最好：

• 你正在规划的目标，
• 系统或功能名称，
• 任何重要的已知术语，
• 以及你想要厘清的决策边界。

不够好的提法是：“帮我设计这个功能。”
更强的提法是：“用 grill-with-docs 把这个功能方案放到当前 billing 域里过一遍。我需要确认 ‘subscription period’ 的正确叫法、数据结构，以及在写文档前哪些决策值得进入 ADR。”

先读这些文件

对于 grill-with-docs usage，建议先看：

• SKILL.md，了解访谈行为和工作流，
• CONTEXT.md 或 CONTEXT-MAP.md，了解当前领域模型，
• docs/adr/，查看之前的决策，
• 如果需要新建或更新文件，再看 ADR-FORMAT.md 和 CONTEXT-FORMAT.md。

这些文件会告诉你，哪些信息可以从仓库中推断，哪些内容必须明确写下来。

能提升输出质量的工作流

建议把这个技能放进一个循环里使用：

1. 先给出一个具体方案或粗略草案，
2. 让技能一次只问一个问题，
3. 用你能提供的、最具体且最贴近仓库事实的信息作答，
4. 如果问题能从文件中回答，就允许它继续探索代码库，
5. 把术语和关键决策记录到上下文或 ADR 笔记里。

一个关键实操建议是：把“我们需要一个名字”和“我们需要一个决策”分开。这样可以让 grill 保持聚焦，也能避免不必要地生成 ADR。

grill-with-docs 技能常见问题

grill-with-docs 只适合文档团队吗？

不是。只要方案需要和现有领域词汇保持一致，它就有用，尤其是在产品工程、平台工作，或者 grill-with-docs for Technical Writing 这类流程中——在这些场景里，措辞和结构会直接影响后续的清晰度。

它和普通 prompt 有什么不同？

普通 prompt 可以生成想法，但 grill-with-docs 的目标是追问假设、检查仓库，并把术语收紧到已有上下文上。这能降低命名冲突，以及“文档和代码库互相打架”的风险。

使用它一定要有成熟的文档体系吗？

不一定，但如果已经有 CONTEXT.md 和 ADR，效果会最好。即使还没有，它也可以随着决策逐步出现，帮助你按需定义这些内容。

什么时候不该用它？

如果任务纯粹是探索性的、仓库里没有有意义的领域上下文，或者你需要的是一个快速的一锤子答案而不是结构化访谈，那就不适合用它。

如何改进 grill-with-docs 技能

给它更好的决策材料

提升效果最大的一步，是给这个技能一个更窄、更像决策题的 prompt。把功能名称、它影响系统的哪一部分、以及你想解决的具体歧义都写出来。比如：“在 accounting 上下文里，我们应该把这个叫做 invoice、billing record 还是 charge？这个决定应该记录在哪里？”

尽早提供仓库证据

如果你已经知道相关文件，开头就直接说明。把技能指向 CONTEXT.md、某个具体 ADR，或者像 src/billing/ 这样的目录，能让它少问泛泛的问题，多问真正有用的问题。对于 grill-with-docs usage 来说，这一点尤其重要，因为这个技能最强的地方，就是能把你的方案和现有术语、结构直接对照起来。

注意常见失败模式

最常见的失败模式，是把领域说得太宽，导致访谈始终停留在抽象层面。另一个问题是，在语言模型还没抓住正确术语之前，就急着问实现。如果第一次输出显得太泛，就把决策重新收窄，并让技能从上一个已经解决的分支继续往下问。

从第一轮结果继续迭代

第一轮结束后，把答案整理成三种输出之一：一条清晰的术语表项、一份简短 ADR，或者一版修订后的实现简报。然后再用 grill-with-docs 继续追问剩余未决问题。第二轮通常才是这个技能最有价值的时候，因为这时术语和边界已经更清楚了。