grill-with-docs

使用文档进行深入探讨

源自 Matt Pocock 的 grill-with-docs（MIT，© 2026 Matt Pocock）。Matt 的访谈准则和以文档为依据的深入探讨规则在 MIT 许可下原样保留。本仓库新增内容：3 个标准库验证器（CONTEXT.md 检查器、ADR 扫描器、词汇表与代码一致性检查）、3 份深入参考资料（各自引用 7+ 个权威来源）、cs-grill-with-docs Agent、/cs-grill-with-docs 命令。详见下方的封装新增内容。

针对计划的各个方面持续深入地采访我，直到我们达成共识。沿着设计树的每个分支逐一讨论，逐个解决决策之间的依赖关系。每个问题都要提供你推荐的答案。

一次只问一个问题，等待我反馈后再继续。

如果可以通过探索代码库来回答某个问题，就改为探索代码库。

领域认知

探索代码库时，也要查找现有文档：

文件结构

大多数仓库只有一个上下文：

/
├── CONTEXT.md
├── docs/
│   └── adr/
│       ├── 0001-event-sourced-orders.md
│       └── 0002-postgres-for-write-model.md
└── src/

如果根目录下存在 CONTEXT-MAP.md，说明仓库包含多个上下文。该映射文件会指出每个上下文的位置：

/
├── CONTEXT-MAP.md
├── docs/
│   └── adr/                          ← system-wide decisions
├── src/
│   ├── ordering/
│   │   ├── CONTEXT.md
│   │   └── docs/adr/                 ← context-specific decisions
│   └── billing/
│       ├── CONTEXT.md
│       └── docs/adr/

按需创建文件——只有在有内容可写时才创建。如果不存在 CONTEXT.md，就在确定第一个术语时创建。如果不存在 docs/adr/，就在需要记录第一个 ADR 时创建。

会话期间

对照词汇表进行检查

当用户使用的术语与 CONTEXT.md 中现有的表述冲突时，立即指出来。“你的词汇表将‘取消’定义为 X，但你似乎指的是 Y——到底是哪一个？”

明确模糊的表述

当用户使用模糊或含义宽泛的词语时，提出一个精确的规范术语。“你说的是‘账户’——你指的是 Customer 还是 User？它们是不同的概念。”

讨论具体场景

讨论领域关系时，用具体场景检验它们。设计能探测边界情况、迫使用户明确概念边界的场景。

与代码交叉验证

当用户陈述某项功能的工作方式时，检查代码是否一致。如果发现矛盾，就指出来：“你的代码会取消整个 Order，但你刚才说可以部分取消——哪一种才是正确的？”

当场更新 CONTEXT.md

确定术语后，立即更新 CONTEXT.md。不要攒到之后再处理——边讨论边记录。使用 CONTEXT-FORMAT.md 中的格式。

CONTEXT.md 中不得包含任何实现细节。不要把 CONTEXT.md 当作规范、草稿或实现决策的存放处。它只用于记录词汇表。

谨慎提出 ADR

只有以下三项条件全部满足时，才提出创建 ADR：

1. 难以撤销——日后改变主意的代价很大
2. 缺少上下文时会令人意外——未来的读者会疑惑“为什么要这样做？”
3. 源于真实的权衡——存在真正的替代方案，并且你基于具体原因选择了其中一种

缺少任何一项，就跳过 ADR。使用 ADR-FORMAT.md 中的格式。

封装新增内容

以下新增内容并非 Matt 上游技能的一部分。它们将上游规则落实为确定性的、仅使用标准库的验证器，与访谈流程自然配套。

工作流（使用包装工具）

1. 预检（第一个问题之前）：

   • 如果存在 CONTEXT.md，运行 scripts/context_md_linter.py CONTEXT.md——确认在围绕术语提问前，术语表格式正确。
   • 如果存在 docs/adr/，运行 scripts/adr_scanner.py docs/adr/——发现编号缺漏、ADR 格式错误和状态 frontmatter 不一致等问题。
   • 运行 scripts/glossary_code_consistency.py --context CONTEXT.md --code src/——标记已定义但未使用的术语（僵尸术语表），以及可能需要定义、仅在代码中出现的常见名词。将这些标记作为开场提问。

2. 会话期间（遵循 Matt 的规则）：

   • 每轮只提一个问题，按深度优先顺序推进。
   • 术语得到明确后：立即编辑 CONTEXT.md；如果编辑涉及结构，则重新运行 context_md_linter.py。
   • 需要编写 ADR 时：将其写入 docs/adr/；重新运行 adr_scanner.py 以确认编号。

3. 收尾：

   • 最后运行 glossary_code_consistency.py，确认没有引入新的孤立术语。
   • 总结：新增或细化的术语、编写的 ADR、讨论过的场景、未解决的事项。

工具（仅使用标准库）

工具	一句话说明
scripts/context_md_linter.py	根据 CONTEXT-FORMAT.md 的结构验证 CONTEXT.md。按规则给出 PASS/WARN/FAIL。
scripts/adr_scanner.py	遍历 docs/adr/，检查 NNNN-slug.md 格式、编号完整性和正文完整性。
scripts/glossary_code_consistency.py	交叉比对 CONTEXT.md 中的粗体术语与代码库用法。标记僵尸术语表和仅在代码中出现的常见名词。

参考资料（每条规则的引文来源）

• references/ubiquitous_language.md — 术语表为何应纳入源代码管理（Evans、Vernon、Khononov、Wlaschin、Brandolini、Avram & Marinescu、Fowler）
• references/adr_practice.md — ADR 何时能发挥作用（Nygard、Tyree & Akerman、Zimmermann 的 Y 语句、MADR、ThoughtWorks Radar、adr-tools、Backstage）
• references/context_md_as_artifact.md — 将 CONTEXT.md 作为持续演进的产物（Khononov 关于语言漂移的论述、Kernighan 关于命名的论述、BoundedContext bliki、Confluent 关于数据契约的论述、Brandolini 关于 EventStorming 术语表的论述）

配套项

• Agent：cs-grill-with-docs（参见 ../../agents/cs-grill-with-docs.md）
• 命令：/cs-grill-with-docs（参见 ../../commands/cs-grill-with-docs.md）

---

版本： 1.0.0 衍生自： Matt Pocock 的 grill-with-docs（MIT）+ 本仓库的包装工具