文档深度审查

源自 Matt Pocock 的 grill-with-docs（MIT 许可，© 2026 Matt Pocock）。Matt 的访谈纪律和基于文档的审查规则在 MIT 许可下原样保留。本仓库的补充内容：3 个标准库验证器（CONTEXT.md 检查器、ADR 扫描器、术语表↔代码一致性检查）、3 份深度参考资料（每份引用 7+ 权威来源）、cs-grill-with-docs 代理、/cs:grill-with-docs 命令。详见下方封装补充。

<what-to-do>

针对这个方案的每个方面对我进行深入追问，直到我们达成共识。沿着设计树的每个分支逐步深入，逐一解决决策之间的依赖关系。对于每个问题，请提供你的推荐答案。

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

如果某个问题可以通过探索代码库来回答，请直接探索代码库。

</what-to-do> <supporting-info>

领域感知

在探索代码库时，同时查找现有文档：

文件结构

大多数仓库有单一上下文：

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

如果根目录存在 CONTEXT-MAP.md，则仓库有多个上下文。该映射文件指向每个上下文的位置：

/
├── CONTEXT-MAP.md
├── docs/
│   └── adr/                          ← 系统级决策
├── src/
│   ├── ordering/
│   │   ├── CONTEXT.md
│   │   └── docs/adr/                 ← 上下文特定决策
│   └── billing/
│       ├── CONTEXT.md
│       └── docs/adr/

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

会话过程中

对照术语表质疑

当用户使用的术语与 CONTEXT.md 中现有语言冲突时，立即指出。"你的术语表将'取消'定义为 X，但你似乎指的是 Y——到底是哪个？"

精确化模糊语言

当用户使用含糊或多义的术语时，提出一个精确的规范术语。"你说的'账户'——是指客户还是用户？这是两个不同的概念。"

讨论具体场景

当讨论领域关系时，用具体场景进行压力测试。构造探测边界情况的场景，迫使用户精确定义概念之间的边界。

与代码交叉验证

当用户陈述某个功能的工作方式时，检查代码是否一致。如果发现矛盾，提出来："你的代码取消的是整个订单，但你刚才说可以部分取消——哪个是对的？"

即时更新 CONTEXT.md

当一个术语被确定后，立即更新 CONTEXT.md。不要积攒这些更新——在发生时就记录下来。使用 CONTEXT-FORMAT.md 中的格式。

CONTEXT.md 应该完全不包含实现细节。不要将 CONTEXT.md 当作规格说明、草稿本或实现决策的存储库。它只是一个术语表。

谨慎提供 ADR

只有在以下三个条件全部满足时才提供 ADR：

1. 难以逆转 ——事后改变主意的成本很高
2. 缺少上下文会令人困惑 ——未来的读者会疑惑"他们为什么这样做？"
3. 真正的权衡结果 ——确实存在替代方案，且你因特定原因选择了其中一个

如果三个条件中任何一个不满足，跳过 ADR。使用 ADR-FORMAT.md 中的格式。

</supporting-info>

封装补充

以下补充内容不属于 Matt 的上游技能。它们将上游规则转化为确定性的、仅使用标准库的验证器，与访谈循环自然配合。

工作流程（使用封装工具）

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

   • 如果 CONTEXT.md 存在，运行 scripts/context_md_linter.py CONTEXT.md ——在审查前确认术语表格式正确。
   • 如果 docs/adr/ 存在，运行 scripts/adr_scanner.py docs/adr/ ——发现编号间隙、格式错误的 ADR、状态前置信息不一致等问题。
   • 运行 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、剩余的开放问题。