chore: import zh skill grill-with-docs

2026-07-13 21:36:22 +08:00
commit de8276d84b
4 changed files with 204 additions and 0 deletions
@@ -0,0 +1,47 @@
+# ADR 格式
+
+ADR 文件存放在 `docs/adr/` 目录下，采用顺序编号：`0001-slug.md`、`0002-slug.md`，以此类推。
+
+`docs/adr/` 目录采用懒创建方式——仅在需要编写第一个 ADR 时才创建。
+
+## 模板
+
+```md
+# {决策的简短标题}
+
+{1-3 句话：上下文是什么，我们做了什么决定，以及为什么。}
+```
+
+仅此而已。一条 ADR 可以只有一个段落。其价值在于记录*做出了*什么决定以及*为什么*——而不是填写各个章节。
+
+## 可选章节
+
+只有在确实能增加价值时才包含以下内容。大多数 ADR 不需要它们。
+
+- **Status** 前置元数据（`proposed | accepted | deprecated | superseded by ADR-NNNN`）——当决策被重新审视时很有用
+- **Considered Options**（考虑过的方案）——仅当被否决的替代方案值得记住时
+- **Consequences**（影响/后果）——仅当存在需要指出的非显而易见的后续影响时
+
+## 编号
+
+扫描 `docs/adr/` 目录，找到当前最大编号并加一。
+
+## 何时需要提交 ADR
+
+以下三个条件必须全部满足：
+
+1. **难以逆转**——后续改变主意的代价很大
+2. **脱离上下文会令人困惑**——未来的读者看到代码后会想"他们到底为什么要这样做？"
+3. **是真正权衡后的结果**——存在切实可行的替代方案，而你出于特定原因选择了其中一个
+
+如果某个决策很容易逆转，那就跳过——反正你以后也会推翻它。如果不会令人困惑，那也没有人会追问原因。如果没有真正的替代方案，那么除了"我们做了显而易见的事"之外，也没有什么可记录的了。
+
+### 哪些情况符合条件
+
+- **架构形态**。"我们使用了单体仓库。"写模型采用事件溯源，读模型投影到 Postgres。"
+- **上下文之间的集成模式**。"订单和计费通过领域事件通信，而非同步 HTTP。"
+- **具有锁定效应的技术选型**。数据库、消息总线、认证服务商、部署目标。不是每个库都要记录——只记录那些替换起来需要花一个季度的。
+- **边界和范围决策**。"客户数据归客户上下文所有；其他上下文仅通过 ID 引用。"明确说*不*的东西，与说*是*的东西同等重要。
+- **刻意偏离常规路径的做法**。"我们因 X 原因使用手写 SQL 而非 ORM。"任何合理读者可能会假设相反情况的事情。这样可以阻止后来的工程师去"修正"那些本就刻意为之的做法。
+- **代码中不可见的约束**。"由于合规要求，我们不能使用 AWS。""由于合作方 API 合约限制，响应时间必须低于 200ms。"
+- **被否决的替代方案（否决理由非显而易见时）**。如果你考虑过 GraphQL 但出于微妙原因选择了 REST，请记录下来——否则六个月后又会有人提议使用 GraphQL。
@@ -0,0 +1,60 @@
+# CONTEXT.md 格式
+
+## 结构
+
+```md
+# {上下文名称}
+
+{一两句话说明这个上下文是什么以及为什么存在。}
+
+## 术语
+
+**订单**：
+{对该术语的一两句话描述}
+_避免_：Purchase、transaction
+
+**发票**：
+在交付后发送给客户的付款请求。
+_避免_：Bill、payment request
+
+**客户**：
+下单的个人或组织。
+_避免_：Client、buyer、account
+```
+
+## 规则
+
+- **要有立场。** 当同一个概念有多个词语可选时，挑选最合适的一个，并将其余的列在「_避免_」下。
+- **定义要精炼。** 最多一两句话。定义它「是什么」，而非它「做什么」。
+- **只包含该项目上下文特有的术语。** 即使项目大量使用了通用编程概念（超时、错误类型、工具模式），它们也不应出现在这里。在添加一个术语之前，先问自己：这是该上下文独有的概念，还是通用编程概念？只有前者才适合收录。
+- **当自然聚类出现时**，将术语分组放在子标题下。如果所有术语同属一个连贯的领域，平铺列表也可以。
+
+## 单上下文 vs 多上下文仓库
+
+**单上下文（大多数仓库）：** 仓库根目录下放一个 `CONTEXT.md`。
+
+**多上下文：** 仓库根目录下放一个 `CONTEXT-MAP.md`，列出各上下文、它们的位置以及相互关系：
+
+```md
+# 上下文地图
+
+## 上下文
+
+- [订单](./src/ordering/CONTEXT.md) — 接收并跟踪客户订单
+- [计费](./src/billing/CONTEXT.md) — 生成发票并处理付款
+- [履约](./src/fulfillment/CONTEXT.md) — 管理仓库拣货与发货
+
+## 关系
+
+- **订单 → 履约**：订单模块发出 `OrderPlaced` 事件；履约模块消费该事件以开始拣货
+- **履约 → 计费**：履约模块发出 `ShipmentDispatched` 事件；计费模块消费该事件以生成发票
+- **订单 ↔ 计费**：`CustomerId` 和 `Money` 的共享类型
+```
+
+技能会根据以下规则推断适用的结构：
+
+- 如果存在 `CONTEXT-MAP.md`，则读取它来查找各上下文
+- 如果只存在根目录的 `CONTEXT.md`，则为单上下文
+- 如果两者都不存在，则在解析第一个术语时懒加载创建根目录的 `CONTEXT.md`
+
+当存在多个上下文时，技能会推断当前主题属于哪一个。如果不确定，它会询问用户。
@@ -0,0 +1,9 @@
+# WeHub 来源说明
+
+- Skill 名称：`grill-with-docs`
+- 中文类目：计划拷问式文档化决策复核
+- 上游仓库：`mattpocock__skills`
+- 上游路径：`skills/engineering/grill-with-docs/SKILL.md`
+- 上游链接：https://github.com/mattpocock/skills/blob/HEAD/skills/engineering/grill-with-docs/SKILL.md
+- 本仓库为 WeHub 中文 Skill 汉化包，基于 skill 市场筛选 Top200 清单整理
+- 原作者、版权和许可证信息以上游仓库为准
@@ -0,0 +1,88 @@
+---
+name: grill-with-docs
+description: 烧烤式讨论——针对现有领域模型拷问你的方案，打磨术语表述，并在决策逐步明确时同步更新文档（CONTEXT.md、ADR）。适用于用户希望针对项目的领域语言和已有决策记录，对某个方案进行压力测试的场景。
+---
+
+<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` 中已有的领域语言相冲突时，立即指出。"你的术语表将 'cancellation' 定义为 X，但你似乎指的是 Y——究竟是哪个？"
+
+### 打磨模糊的语言
+
+当用户使用模糊或过载的术语时，提出一个精确的规范术语。"你说了 'account'——你指的是 Customer 还是 User？这是两个不同的概念。"
+
+### 讨论具体场景
+
+当讨论领域关系时，用具体场景来检验。设计能够探测边界情况的场景，迫使你对概念之间的界限做出精确说明。
+
+### 对照代码进行交叉验证
+
+当用户描述某个功能的工作原理时，检查代码是否与之一致。如果发现矛盾，指出来："你的代码取消了整个 Order，但你刚才说可以部分取消——哪个是对的？"
+
+### 实时更新 CONTEXT.md
+
+当一个术语确定后，立即更新 `CONTEXT.md`。不要批量处理——每发生一次就记录一次。使用 [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md) 中的格式。
+
+`CONTEXT.md` 中应完全不包含实现细节。不要把 `CONTEXT.md` 当作规格说明书、草稿本或实现决策的仓库。它只是一个术语表，仅此而已。
+
+### 审慎提供 ADR
+
+仅在以下三个条件同时满足时，才提议创建 ADR：
+
+1. **难以逆转**——事后改变主意的成本很高
+2. **脱离上下文会令人费解**——未来的读者会想"他们为什么这样做？"
+3. **真正权衡后的结果**——存在真正的备选方案，你出于特定原因选择了其中之一
+
+如果三个条件中有任何一个不满足，则跳过 ADR。使用 [ADR-FORMAT.md](./ADR-FORMAT.md) 中的格式。
+
+</supporting-info>