Grill with Docs

Grill with Docs 是什么

Grill with Docs 是面向代码仓库规划阶段的深度访谈 Skill。它不会急着生成一份看似完整的方案，而是围绕目标、约束、失败模式、术语歧义和不可逆决策持续追问；随着答案变清晰，把真正需要跨会话保留的信息写进仓库文档。它把“口头讨论”和“长期工程记忆”分开管理，适合设计仍有大量隐含假设的项目。

适用场景与不适用场景

适合在新功能、系统迁移、领域建模或跨团队接口设计前使用，也适合接手一个术语混乱、决策理由缺失的旧项目。不适合把它当成自动写规范、自动改代码或多轮项目管理器；如果只想快速头脑风暴，持续追问会显得过重。跨多个会话长期推进时，上游文档建议改用具备导航与恢复能力的工作流。

核心能力与工作机制

它组合 grilling 与 domain-modeling 两个依赖：前者负责不留情面地追问假设，后者负责识别领域术语和决策。已经确认的术语会立即加入 CONTEXT.md；难以撤销、反直觉或存在重大权衡的选择写成 docs/adr/ 下的架构决策记录。普通讨论不落盘，从而避免把上下文文件膨胀成第二份规格书。

实际工作流与产物

典型流程是先读取仓库现有 CONTEXT、上下文映射和 ADR，再从用户给出的目标开始逐层追问。每当某个词获得稳定定义，立即更新词汇表；当出现必须解释“为什么这样选”的决定时，建立 ADR。最终产物不是完整方案，而是一组经过澄清的对话结论、更新后的术语上下文和少量真正重要的决策记录。若要保留全部功能细节，应再把对话交给规格生成流程。

安装、依赖与权限

单独安装本 Skill 不足以完整运行，还需要 grilling 和 domain-modeling。代理需要读取仓库、创建或修改 CONTEXT.md 与 docs/adr/ 的权限；这些文件按需创建，不会无条件污染项目。它不要求外部账号或 API，但在某些编排器中，子流程写文件可能静默失败，因此结束前要实际检查文件差异。

限制、风险与使用建议

最大的误用是把 CONTEXT.md 当成需求文档，或把每个小决定都写成 ADR。前者会造成重复真相源，后者会形成没人愿意维护的决策墓地。另一个限制是，访谈中未落盘的普通结论会随会话结束而丢失。使用后应检查上下文是否真的变化、ADR 是否解释了备选方案与取舍，并把其余结论转入正式规格。

上手建议

先给出仓库范围、目标用户、现有约束和你最不确定的三件事，并允许 Skill 读取现有设计文档。回答追问时区分事实、偏好和假设；遇到不确定项可以明确标记待验证。结束前逐项审阅 CONTEXT 与 ADR，确认术语没有被代理自行发明，决策状态、日期和替代方案都准确。

来源、版本与许可

本条目依据 mattpocock/skills 固定提交中的完整 SKILL.md 与近万字使用文档整理，仓库声明 MIT 许可证。来源还明确记录了依赖缺失和编排环境下可能不写文件的已知问题。

常见问题

1. 它最终会生成一份完整技术方案吗？

不会。它的核心产物是经过追问的对话、术语上下文和少量 ADR，普通功能细节仍留在会话里。若需要可执行规格，应在访谈结束后把完整对话交给规格生成流程，不能只拿 CONTEXT.md 充当方案。

2. CONTEXT.md 应该写哪些内容？

只写在项目中具有稳定含义、后续代理和开发者需要共同理解的术语、实体与边界。验收标准、任务列表、临时讨论和实现步骤不应塞进去，否则它会与正式规格产生冲突并快速失去可维护性。

3. 什么决定值得建立 ADR？

适合记录难以回滚、反直觉、存在真实备选方案或未来维护者很可能再次追问原因的选择。简单命名、常规库用法和随时可改的局部实现不必建 ADR；没有 ADR 也不代表访谈失败。

4. 为什么单独安装后可能没有文档产物？

因为入口 Skill 依赖 grilling 与 domain-modeling 执行访谈和落盘逻辑。缺少依赖时，代理可能仍能提问，却不会形成 CONTEXT 或 ADR；此外某些编排环境存在文件写入未发生的已知问题，必须检查实际差异。

5. 适合跨多个会话持续使用吗？

它主要为单次仓库规划会话设计，能沉淀少量长期信息，但不会管理多阶段进度、恢复点和下一步队列。若任务要持续数天或由多名代理接力，应搭配专门的项目导航或交接机制。

6. 访谈过程中可以跳过不确定问题吗？

可以，但应把未知项明确标成假设、风险或待验证问题，而不是为了推进而编造答案。真正的价值在于暴露认知空白；对关键未知项最好记录验证方法、负责人和会阻塞的决定。

7. 如何判断本次使用是否成功？

检查术语是否比开始时更少歧义，关键权衡是否能从 ADR 追溯，团队是否知道哪些仍是假设。ADR 数量可以为零；如果只是生成了很多文件，却没有改变理解或决策质量，反而说明使用方式偏离目标。

8. 会自动修改业务代码吗？

不会，它定位于设计澄清和知识沉淀。文件权限应限制在上下文与决策文档范围；若后续要实施方案，应另开实现任务并重新确认改动范围、测试要求和风险，避免把访谈授权扩大成代码变更授权。