grill-with-docs：一次会话完成设计拷问与文档沉淀

1. 从一次真实的“设计拷问”说起第一次接触 grill-with-docs 这个技能是在一个订单履约系统的重构项目里。当时团队已经连续开了三次设计评审会每次都是两小时起步白板上画满了架构图会议纪要写了七八页但真正落到代码里的决策却少得可怜。更麻烦的是两周之后有人问“为什么当时不用事件溯源而选了状态机”在场的人面面相觑谁也说不清楚。这种场景我相信做过中大型系统的人都遇到过——设计讨论的过程信息量极大但沉淀下来的往往只有结论甚至只有代码本身。grill-with-docs 解决的正是这个问题。它的核心思路很直接在一次会话里先对设计方案进行高强度的“拷问”grilling把每个决策背后的假设、权衡、风险都逼出来然后立刻把这些讨论结果沉淀成结构化的领域文档包括 CONTEXT.md 和 ADRArchitecture Decision Record架构决策记录。整个过程不跨会话、不切换工具、不需要事后补文档一次坐下来就把“想清楚”和“写下来”两件事一起干了。这个技能适合谁我认为三类人收益最大。第一类是技术负责人或架构师需要频繁做设计决策并且对决策质量负责第二类是刚接手复杂系统的工程师需要通过文档快速理解既有设计的来龙去脉第三类是团队里负责技术写作或知识管理的人一直在找一种“不额外增加负担”的文档沉淀方式。哪怕你只是一个人做 side project这套方法也能帮你把脑子里的设计思路理清楚避免三个月后自己都忘了当初为什么这么写。接下来我会把这套技能的完整实操过程拆开讲包括每一步的设计意图、具体怎么问、文档怎么写、踩过哪些坑以及我实测下来最稳的一套流程。2. grill-with-docs 的整体设计与核心思路2.1 为什么是“拷问”而不是“讨论”普通的设讨论和 grilling 有本质区别。讨论是发散性的大家你一言我一语很容易跑偏到实现细节或者无关话题上。而 grilling 是有结构的、带压力的追问它的目标不是达成共识而是暴露分歧和盲区。我在实践中总结了一个判断标准如果一场设计讨论结束后没有人感到“被问住了”或者“有个地方我之前没想清楚”那这场讨论大概率是低效的。grill-with-docs 里的 grilling 环节通常围绕几个固定维度展开这个设计的核心假设是什么如果假设不成立会怎样有没有更简单的方案边界条件在哪里失败模式有哪些每个维度都会追问到具体场景和具体数据不接受“一般来说”“应该没问题”这种模糊回答。这种压力测试的价值在于很多设计缺陷在写代码之前就能被发现而不是等到线上出问题才回头改。2.2 文档沉淀为什么必须“当场完成”我试过很多种文档沉淀方式会后补、周末补、迭代结束补结论是——只要不是当场写信息损耗至少 40%。原因很简单讨论过程中的犹豫、争论、被否决的方案这些“负空间”信息在事后回忆时几乎必然丢失。而恰恰是这些信息对后来接手的人最有价值。比如“我们考虑过用消息队列解耦但考虑到运维复杂度放弃了”这句话如果不在当场记下来三个月后新来的工程师一定会再提一次同样的方案。grill-with-docs 把文档沉淀嵌入到会话流程里grilling 结束之后立刻进入文档生成环节中间不隔夜、不切工具。CONTEXT.md 负责记录领域模型和上下文边界ADR 负责记录每个关键决策的背景、选项、结论和后果。两者配合形成一个完整的决策档案。2.3 CONTEXT.md 和 ADR 的分工逻辑很多人会把这两个东西搞混或者干脆只写一个。我的经验是它们解决的是不同层次的问题。CONTEXT.md 回答的是“这个系统里有哪些核心概念它们之间是什么关系”偏向静态的领域知识。ADR 回答的是“我们为什么做了这个选择当时还考虑了哪些方案”偏向动态的决策过程。举个例子在一个支付系统里CONTEXT.md 会定义“支付单”“交易流水”“结算批次”这些概念及其关系而 ADR 会记录“为什么选择最终一致性而不是强一致性”“为什么把对账逻辑放在独立服务而不是主流程里”。前者是地图后者是旅行日志。两者缺一不可只有地图不知道路是怎么走出来的只有日志又缺乏全局视角。2.4 一次会话完成的流程设计整个流程我实测下来最顺的是四段式准备阶段10 分钟、grilling 阶段40-60 分钟、文档生成阶段20-30 分钟、校验阶段10 分钟。准备阶段主要是明确本次要拷问的设计范围把相关的代码、旧文档、会议记录快速过一遍。grilling 阶段是核心按照预设维度逐项追问每个问题都要落到具体场景。文档生成阶段把讨论结果结构化CONTEXT.md 和 ADR 同步产出。校验阶段检查文档之间是否一致、是否有遗漏的关键决策。这个时间分配不是死的复杂系统可以拉长到两小时简单模块可以压缩到四十分钟。关键是不要跳过任何一个阶段尤其是校验阶段我见过太多因为文档之间自相矛盾导致后来人误入歧途的案例。3. 核心细节解析与实操要点3.1 grilling 环节的提问框架提问框架是整个技能的灵魂。我经过多次迭代固定下来一套“五层追问法”每一层都有明确的意图。第一层是事实层这个设计涉及哪些核心实体它们的状态如何流转数据从哪里来到哪里去这一层的问题必须能用具体例子回答不能用抽象概念糊弄。比如问“订单状态有哪些”不能只说“待支付、已支付、已完成”要追问“退款中的订单算哪个状态”“部分支付怎么表示”。第二层是假设层这个设计成立的前提是什么比如“假设下游服务响应时间在 200ms 以内”“假设用户不会在支付过程中修改收货地址”。每个假设都要评估如果被打破会怎样以及有没有监控手段能及时发现假设被打破。第三层是权衡层为什么选 A 不选 B当时考虑了哪些替代方案每个方案的优缺点是什么这一层最容易挖出隐藏的决策因为很多选择是“默认”做的当事人自己都没意识到做了选择。第四层是边界层什么情况下这个设计会失效极端流量、数据量增长十倍、依赖服务不可用这些场景下系统会怎么表现这一层的问题往往能直接转化为 ADR 里的“后果”部分。第五层是演进层如果未来要改改哪里改动成本有多大有没有预留扩展点这一层帮团队判断当前设计是否具备足够的弹性。3.2 CONTEXT.md 的结构与写法CONTEXT.md 不是 README不需要写安装步骤和 API 文档。它的核心是领域模型和上下文边界。我通常按四个部分组织核心概念、关系图、上下文边界、术语表。核心概念部分用一句话定义每个实体然后列出它的关键属性和状态。比如“支付单一次支付请求的聚合根包含金额、币种、支付方式、状态四个核心属性状态流转为 created → processing → succeeded/failed/refunded”。关系图部分用文字描述实体之间的关联比如“一个订单可以对应多个支付单一个支付单只能属于一个订单”。上下文边界部分说明这个领域模型适用于哪些场景、不适用于哪些场景。术语表统一团队内部的叫法避免“支付单”和“交易单”混用。写 CONTEXT.md 最容易犯的错误是写得太细把字段类型、索引设计都塞进去。我的原则是只写“如果不知道就会理解错”的信息。字段类型看代码就知道但“为什么支付单和订单是一对多而不是一对一”这种信息代码里看不出来必须写进文档。3.3 ADR 的模板与关键字段ADR 我用的模板包含六个字段标题、状态、背景、决策、替代方案、后果。标题用“动词对象原因”的格式比如“选择状态机而非事件溯源来管理订单状态”。状态标记为 proposed、accepted、deprecated、superseded 四种。背景部分说明为什么需要做这个决策通常是一个具体的业务或技术问题。决策部分写最终选了什么。替代方案部分列出考虑过但没选的方案及原因。后果部分写这个决策带来的正面和负面影响。这里有个细节很多人忽略ADR 要编号并且不可修改。一旦 accepted后续要改只能新建一个 ADR 并把旧的标记为 superseded。这样做的好处是保留了完整的决策历史后来人能看到设计是怎么一步步演变的。我见过团队直接改旧 ADR 的内容结果导致不同时期的人对同一个决策的理解完全对不上。3.4 两个文档之间的交叉引用CONTEXT.md 和 ADR 不是孤立的它们之间需要交叉引用。CONTEXT.md 里每个核心概念如果涉及关键决策要链接到对应的 ADR。ADR 里如果引用了领域概念要链接回 CONTEXT.md 的对应章节。这种双向链接在文档数量少的时候感觉多余但一旦超过十个 ADR没有交叉引用就会变成灾难。我通常会在 CONTEXT.md 的每个概念定义后面加一行“相关决策ADR-003、ADR-007”在 ADR 的背景部分加一行“涉及概念支付单、结算批次”。这样无论是从概念出发还是从决策出发都能快速找到关联信息。3.5 实操中的三个关键注意事项第一个注意事项grilling 阶段一定要有记录员。如果只有一个人既问又记注意力会被打断追问的深度会下降。我的做法是让一个人主导提问另一个人专门记录关键点和待确认项。记录不需要完整只需要记下“问题-回答-待定”三要素。第二个注意事项不要试图一次覆盖所有设计。一个会话聚焦一个模块或一个决策域贪多嚼不烂。我试过在一次会话里同时拷问订单和支付两个模块结果两个都问得不深文档也写得含糊。后来改成一次只搞一个模块质量明显提升。第三个注意事项文档生成后一定要让参与者过一遍。不是走形式而是逐条确认“这是不是当时讨论的意思”。我遇到过好几次记录员理解偏差导致文档写错的情况如果没人校验错误信息就会一直传下去。4. 实操过程与核心环节实现4.1 准备阶段十分钟快速对齐准备阶段的目标是让所有参与者对本次拷问的范围和背景有共同理解。我通常做三件事第一用一句话说明本次要拷问的设计是什么比如“订单状态机的状态定义和流转规则”。第二快速过一遍相关代码和旧文档标记出有疑问的地方。第三确认参与者的角色分工谁提问、谁记录、谁负责最终文档。这个阶段不需要深入讨论就是对齐信息。我习惯在白板上画一个简单的上下文图标出本次涉及的实体和外部依赖让所有人一眼就能看到边界在哪里。如果之前有相关的 ADR也在这个阶段快速回顾一下避免重复讨论已经决策过的事情。4.2 grilling 阶段逐层追问的完整记录grilling 阶段我按五层追问法逐层推进每层大概十到十五分钟。下面用一个真实案例来展示追问过程。案例背景是一个优惠券系统设计目标是支持多种优惠券类型和叠加规则。事实层的追问从“优惠券有哪些类型”开始回答是“满减券、折扣券、立减券”。追问“满减券的满和减分别是什么含义”回答“满 100 减 20”。继续追问“如果订单金额是 99.5 元能不能用”回答“不能必须大于等于 100”。再追问“如果订单里有退款商品金额怎么算”这时候回答开始犹豫了说明这里存在未定义的行为。假设层的追问围绕“优惠券叠加规则”展开。假设“同一订单最多用两张券”追问“如果两张券都是满减券门槛怎么算”回答“分别计算”。追问“如果第一张券使用后金额降到门槛以下第二张券还能用吗”这个问题直接暴露了设计缺陷——原设计没有考虑券使用后的金额变化对后续券的影响。权衡层的追问聚焦“为什么选择在订单创建时锁定优惠券而不是支付时”。回答是“避免支付时券已被用完”。追问“锁定后用户不支付怎么办”回答“设置过期时间”。追问“过期时间设多长依据是什么”回答“15 分钟参考了行业惯例”。这里就挖出了一个隐藏假设——15 分钟是否适合所有场景比如大促期间支付拥堵时是否够用。边界层的追问针对“优惠券系统的并发处理”。追问“同一张券被两个请求同时使用时怎么保证不超发”回答“数据库唯一索引”。追问“如果用了缓存呢”回答“缓存和数据库的一致性怎么保证”。这一层的问题往往需要具体的技术方案不能停留在“应该没问题”。演进层的追问关于“未来要支持跨店优惠券怎么改”。回答“需要引入店铺维度”。追问“改动涉及哪些模块”回答“券模板、券实例、订单计算、结算分账”。追问“有没有预留扩展点”回答“没有需要改表结构”。这个回答直接转化为 ADR 里的“后果”部分——当前设计不支持跨店场景未来扩展成本较高。整个 grilling 阶段我建议全程录音征得同意的前提下因为追问节奏很快记录员不可能记下所有细节。录音可以在文档生成阶段回听确保没有遗漏关键信息。4.3 文档生成阶段从讨论记录到结构化文档文档生成阶段我通常分三步走。第一步把 grilling 阶段的记录整理成“决策清单”每条包含决策内容、背景、替代方案、后果四个要素。第二步从决策清单中提取领域概念更新或新建 CONTEXT.md。第三步把每个决策写成独立的 ADR编号并建立交叉引用。以优惠券系统为例决策清单里有一条“选择在订单创建时锁定优惠券”。背景是“避免支付时券已被用完”。替代方案是“支付时校验并扣减”。后果是“需要处理锁定后未支付的过期释放增加了状态管理的复杂度”。这条决策对应一个 ADR同时在 CONTEXT.md 的“优惠券实例”概念下添加链接。CONTEXT.md 的更新要特别注意术语一致性。grilling 阶段大家可能用不同的词指代同一个东西比如“券模板”和“券定义”、“券实例”和“用户券”。文档生成阶段必须统一术语并在术语表里记录曾用名方便后来人搜索。4.4 校验阶段一致性检查与遗漏补全校验阶段我固定做四项检查。第一项CONTEXT.md 里的每个概念是否都有定义有没有出现未定义的术语。第二项每个 ADR 是否都有编号、状态、背景、决策、替代方案、后果六个字段有没有缺项。第三项CONTEXT.md 和 ADR 之间的交叉引用是否双向可达有没有断链。第四项决策清单里的每条决策是否都有对应的 ADR有没有遗漏。我还会做一个“新人测试”找一个没参与 grilling 的同事让他只看文档回答几个关键问题比如“优惠券叠加时金额怎么算”“锁定后未支付怎么处理”。如果他能答对说明文档合格如果答错或答不上来说明文档有歧义或遗漏需要补充。4.5 一个完整的 ADR 示例下面是我在实际项目中写的一个 ADR脱敏后分享出来。标题是“ADR-012选择状态机而非事件溯源管理订单状态”。状态为 accepted。背景是“订单状态流转复杂涉及支付、退款、履约多个环节需要保证状态变更的可追溯性和一致性”。决策是“采用有限状态机管理订单状态状态变更通过显式的事件触发每次变更记录操作日志”。替代方案有两个一是事件溯源优点是天然可追溯、可重放缺点是查询需要投影、运维复杂度高二是直接更新状态字段优点是简单缺点是丢失变更历史、无法审计。后果是“状态机实现简单、查询直接但变更历史需要额外日志表记录且不支持状态回放”。这个 ADR 写完之后后来接手订单模块的工程师反馈说这是他理解订单状态设计最快的一次因为背景和替代方案把“为什么不用事件溯源”讲清楚了他不用再自己猜。5. 常见问题与排查技巧实录5.1 grilling 冷场或跑偏怎么办冷场通常是因为问题太抽象参与者不知道怎么回答。我的应对方法是立刻降维把抽象问题换成具体场景。比如“这个设计有什么风险”没人回答就换成“如果数据库挂了这个流程会怎样”。跑偏则是因为有人开始讨论实现细节这时候要果断拉回来说“这个点我们记下来grilling 结束后单独讨论”。我还会准备一些“万能追问句”来救场比如“能举个例子吗”“如果反过来呢”“最坏情况是什么”“有没有更简单的做法”。这几句话几乎适用于任何设计讨论能快速把话题拉回正轨。5.2 文档写得太空或太细怎么平衡太空的典型表现是“本系统采用微服务架构具有高可用、可扩展的特点”这种废话。太细的典型表现是把数据库字段类型都写进 CONTEXT.md。我的平衡标准是文档应该回答“为什么”和“是什么”不回答“怎么做”。“怎么做”看代码“为什么”和“是什么”代码里看不出来。具体操作上我会在文档生成阶段问自己三个问题这条信息如果删掉后来人会不会理解错这条信息如果保留会不会很快过时这条信息能不能在代码里直接看到如果答案是“不会理解错”“很快过时”“能直接看到”那就删掉。5.3 ADR 编号冲突和状态管理多人协作时 ADR 编号容易冲突。我的做法是每个 ADR 文件用“ADR-编号-标题.md”命名编号由一个人统一分配其他人新建 ADR 时先申请编号。如果团队用 Git可以在合并时检查编号是否重复重复的重新编号并更新所有引用。状态管理方面我建议只保留 accepted 和 superseded 两种状态proposed 和 deprecated 在实际使用中容易造成混乱。一个 ADR 要么生效要么被取代没有中间状态。如果某个决策还在讨论中那就不要写 ADR等确定了再写。5.4 常见问题速查表问题现象可能原因排查方法解决技巧grilling 问不出深度问题太抽象或参与者准备不足检查是否提前发了背景材料降维到具体场景用万能追问句CONTEXT.md 和 ADR 对不上文档生成阶段没有交叉校验逐条检查交叉引用建立双向链接校验阶段做新人测试ADR 编号重复多人同时新建 ADR检查文件名和内容编号统一分配编号合并时检查文档写完没人看文档太长或找不到问团队成员最近是否查阅过控制篇幅建立索引在代码注释里链接grilling 时间失控话题跑偏或追问太细记录每个话题的耗时设定每层追问的时间上限跑偏就记下来决策清单遗漏记录不完整回听录音对照决策清单记录员只记“问题-回答-待定”不追求完整5.5 我踩过的三个坑第一个坑是第一次用这个技能时我试图在一次会话里同时产出 CONTEXT.md 和 ADR结果两个都写得很粗糙。后来我调整了顺序先集中精力把决策清单整理清楚再从清单派生两个文档质量明显提升。第二个坑是忽略了 ADR 的“替代方案”字段。一开始我觉得既然已经选了 A写 B 和 C 为什么没选是浪费时间。后来发现替代方案恰恰是后来人最关心的部分因为它回答了“我想到的方案是不是已经被考虑过了”。现在我会强制要求每个 ADR 至少写两个替代方案。第三个坑是文档生成后没有让参与者校验。有一次记录员把“最终一致性”写成了“强一致性”导致后来人在设计对账系统时基于错误前提做了决策。从那以后我坚持文档生成后必须让至少一个参与者逐条确认。6. 工具链与协作方式的选型建议6.1 文档存放位置的选择CONTEXT.md 和 ADR 放哪里我试过三种方案。第一种是放在代码仓库的 docs 目录下优点是版本管理和代码同步缺点是产品经理和设计师不方便看。第二种是放在 Wiki 里优点是访问方便缺点是容易和代码脱节。第三种是放在独立的文档仓库优点是专注缺点是又多了一个地方要维护。我最终选择放在代码仓库的 docs 目录下因为这套文档的主要读者是工程师而且和代码一起做 code review 能保证文档更新及时。如果团队有非技术角色需要查阅可以用 CI 自动同步到 Wiki 或内部文档平台。6.2 会话记录工具的选择grilling 阶段的记录我推荐用最简单的工具一个共享文档加一支录音笔。共享文档用来实时记录关键点录音用来回听细节。不要用太复杂的工具否则记录员会花时间在工具操作上而不是记录内容上。如果团队是远程协作共享文档加录屏就够了。我试过用专门的会议记录工具自动转录的准确率在技术讨论场景下并不理想专业术语经常识别错误反而增加校对成本。6.3 与现有工作流的集成grill-with-docs 不需要独立的工作流它可以嵌入到现有的设计评审或迭代规划里。我的做法是在每个迭代的设计阶段安排一次 grilling 会话产出文档后直接进入开发。如果团队有设计评审流程可以把 grilling 作为评审的前置步骤评审时直接看文档而不是听讲解效率更高。对于紧急需求可以简化流程只做 grilling 和 ADRCONTEXT.md 后续补充。但我不建议长期这样因为缺少 CONTEXT.md 会导致领域概念逐渐模糊ADR 也会失去上下文。6.4 团队推广的实操建议推广这套方法最大的阻力是“没时间”。我的应对策略是先在一个小模块上试点用实际效果说话。试点完成后把产出的文档给团队看特别是让后来接手的人反馈“看文档省了多少时间”。有了具体案例推广就容易多了。另外不要把 grilling 搞成正式会议那样会增加心理负担。我通常把它包装成“设计冲刺”或“架构工作坊”氛围轻松一点参与者更愿意说真话。记录员也不要固定一个人轮流担任能让每个人都熟悉这套方法。7. 从单次会话到持续沉淀的扩展思路7.1 建立 ADR 索引和检索机制当 ADR 数量超过二十个之后查找就变成一个问题。我的做法是维护一个 ADR 索引文件按模块和状态分类每条包含编号、标题、状态、涉及概念四个字段。索引文件放在 docs 目录的根目录下方便快速浏览。检索方面我依赖代码仓库的搜索功能在 ADR 标题和背景里埋关键词。比如所有涉及支付的 ADR 标题里都包含“支付”二字搜索“支付”就能找到所有相关决策。CONTEXT.md 里的概念定义也包含关键词搜索同一个词能同时找到概念和决策。7.2 定期回顾与文档更新文档不是写完就完了需要定期回顾。我通常在每个季度末花半天时间过一遍所有 ADR检查有没有状态需要更新、有没有被新决策取代、有没有内容过时。CONTEXT.md 则跟着领域模型的变化走每次有新的核心概念加入或旧概念废弃时更新。回顾时我会特别关注“superseded”状态的 ADR看看被取代的原因是什么有没有形成模式。比如如果多个 ADR 都是因为性能问题被取代说明当初的性能评估方法有问题需要改进。7.3 新人上手场景的应用这套文档对新人上手特别有价值。我通常让新人第一周只做一件事读 CONTEXT.md 和所有 accepted 状态的 ADR然后回答几个问题比如“这个系统的核心领域概念有哪些”“为什么订单和支付是分开的”“如果要加一个新支付方式需要改哪些地方”。能答对这些问题的基本就理解了系统的设计思路。我还会让新人在读完文档后提三个问题这些问题往往能发现文档的盲区。新人没有历史包袱能看到老人忽略的模糊之处。把这些问题补进文档文档质量会持续提升。7.4 多模块协作时的文档组织当系统有多个模块时我建议每个模块有自己的 CONTEXT.md但 ADR 是全局共享的。模块间的交互在各自的 CONTEXT.md 里说明跨模块的决策写在全局 ADR 里。这样既保持了模块的独立性又保证了决策的全局一致性。如果模块之间有概念重叠比如订单模块和支付模块都涉及“金额”我会在全局 CONTEXT.md 里定义“金额”的统一含义各模块引用这个定义而不是各自解释。这样可以避免同一个词在不同模块里含义不同导致的沟通成本。7.5 我个人的使用体会用了大半年之后我最大的体会是这套方法的价值不在于文档本身而在于 grilling 过程逼着团队把问题想清楚。很多时候文档写不出来不是因为不会写而是因为设计本身还有模糊地带。grilling 把这些模糊地带暴露出来文档只是顺带的结果。另一个体会是不要追求一次完美。我早期的 CONTEXT.md 和 ADR 写得很粗糙但后来不断迭代现在回头看第一版和最新版的差距非常大。重要的是开始做然后在实践中调整。如果等到“准备好”再开始大概率永远不会开始。最后分享一个小技巧每次 grilling 结束后花五分钟让参与者用一句话总结“今天最大的收获是什么”。这句话往往能捕捉到最有价值的洞察而且适合放在文档的开头作为摘要。我试过很多次这句话的质量比事后写的总结高得多。