带文档的烧烤炉

grill-with-docs

分类编程

作者Alireza Rezvani

许可MIT

评分4.50/5

使用11.2K

Grill with Docs (基于文档的深度质询)

> 源自 Matt Pocock 的 grill-with-docs (MIT, © 2026 Matt Pocock)。在 MIT 协议下原封不动地保留了 Matt 的面试纪律 + 基于文档的质询规则。本仓库的新增内容：3 个标准库验证器（CONTEXT.md 检查器、ADR 扫描器、术语表↔代码一致性检查）、3 篇深度参考资料（每篇引用 7 个以上权威来源）、cs-grill-with-docs 智能体、/cs:grill-with-docs 命令。详见下文的 Wrapper additions。

<what-to-do>

就该方案的每一个方面对我进行不懈的质询，直到我们达成共识。沿着设计树的每个分支深入，逐一解决决策之间的依赖关系。针对每个问题，请提供你的建议答案。

一次只问一个问题，在继续之前等待对每个问题的反馈。

如果可以通过探索代码库来回答问题，请优先探索代码库。

</what-to-do>

<supporting-info>

领域感知

在探索代码库期间，同时寻找现有文档：

文件结构

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

code

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

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

code

/
├── 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 —— 究竟是哪个？”

锐化模糊语言

当用户使用模糊或过载的术语时，提出一个精确的规范术语。“你提到了‘账户’ —— 你是指‘客户 (Customer)’还是‘用户 (User)’？这两者是不同的概念。”

讨论具体场景

在讨论领域关系时，用具体场景对其进行压力测试。设计能够探测边缘情况的场景，迫使用户精确定义概念之间的边界。

与代码交叉引用

当用户陈述某项工作原理时，检查代码是否一致。如果发现矛盾，请将其揭示：“你的代码取消的是整个订单 (Order)，但你刚才说支持部分取消。”
possible — 哪个是对的？"

实时更新 CONTEXT.md

当某个术语得到明确定义时，请立即更新 CONTEXT.md。不要批量处理，而是在发生时即时记录。请使用 CONTEXT-FORMAT.md 中定义的格式。

CONTEXT.md 应当完全不包含实现细节。不要将 CONTEXT.md 视为技术规范、草稿本或实现决策的存储库。它仅仅是一个术语表。

谨慎提供 ADR

仅在同时满足以下三个条件时，才建议创建 ADR：

1. 难以逆转 —— 以后更改决定的成本很高。
2. 缺乏上下文则令人费解 —— 未来的阅读者会疑惑“为什么当时要这么做？”
3. 是真实权衡的结果 —— 存在真正的替代方案，而你出于特定原因选择了其中一个。

如果缺少上述任何一项，则跳过 ADR。请使用 ADR-FORMAT.md 中的格式。

</supporting-info>

Wrapper 增强功能

以下增强内容不属于 Matt 的上游技能。它们将上游规则转化为确定性的、仅依赖标准库（stdlib）的验证器，以便与面试循环自然结合。

工作流（配合 Wrapper 工具）

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、讨论的场景以及待办事项。

工具（仅限标准库）

| 工具 | 一句话功能描述 |
|---|---|
| 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-statements, 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) + 本仓库的封装层