技术决策记录（ADR）示例的价值在于让团队看到一份写完的记录长什么样：背景写到什么程度、备选方案列几项、结论和后果如何落笔。本文给出一份虚构团队完成缓存方案选型后的完整ADR，逐字段解释写法与取舍，并说明哪些结构可以迁移到自己的决策场景、哪些边界需要按组织实际调整。示例情景为演示用途，不代表真实项目。
要点总览（TL;DR）
- 技术决策记录（ADR）示例的骨架是“背景—选项—决策—后果”，再加状态、日期、决策者等元信息，让记录可评审、可追溯。
- 背景段要写清触发原因与约束，备选方案按同一组维度横向比较，决策理由与评估要点一一对应。
- 后果段把已确定影响与待观察风险分开写，风险尽量附观察指标或复盘时间。
- 示例为虚构演示，可迁移的是结构与写法；轻量决策可精简字段，重大决策需补充成本、迁移与回滚方案。
示例要解决什么问题：一份技术决策记录该留下什么
技术决策记录的目标读者通常有两类：当时参与决策的人，以及半年后接手这块系统的同事。前者需要确认记录与记忆一致，后者需要在没有上下文的情况下理解决策为什么这样定、改动它会牵动什么。因此一份可用的ADR要固定四类信息：决策是在什么约束下被触发的、当时比较过哪些选项、最终选了哪个及理由、这个选择带来哪些确定影响和待观察风险。
这四类信息对应一个稳定骨架：背景—选项—决策—后果。骨架之外还需要元信息，包括状态、日期、决策者和参与评审的角色，用来回答“这份记录还有效吗”“谁有权改它”。缺少元信息的记录，几个月后很难判断它是仍在执行的结论，还是已被推翻的旧稿。
本文示例的假设情景如下，全文标注为示例：一个虚构的订单服务团队，在促销期间遇到接口响应变慢的问题，需要在本地缓存、分布式缓存和数据库读优化之间做选择。团队规模、系统规模和流量数字均为演示设定，不对应任何真实客户。读者读完应能对照示例，写出自己团队的一份记录。
完整示例：一次缓存方案选型的技术决策记录
以下为一份已填写的技术决策记录示例。标题、状态、日期、人名与系统名均为虚构，仅用于展示字段如何落笔。
示例记录全文
标题：订单查询接口采用分布式缓存承载热点商品数据
状态：已接受 日期：2025-03-14 决策者：订单服务技术负责人 参与评审：后端开发两名、SRE一名、产品经理一名
背景。订单查询接口在大促期间平均响应时间从180ms上升到620ms，其中商品详情与库存状态的重复查询占数据库读请求的七成。数据库主库CPU在峰值时段接近饱和，扩容一次可缓解约两周，但下一次促销前仍会复现。团队需要在下一个促销季前确定读路径的承载方式，约束条件是：改造周期不超过四周、不改变现有订单写入链路、缓存失效时接口仍能返回可用结果。
候选方案。
| 方案 | 做法 | 评估要点 |
|---|---|---|
| 方案A：本地缓存 | 在应用进程内缓存热点商品数据，设置短过期时间 | 改造量最小；多实例之间数据不一致，库存类数据风险高；实例扩容后命中率下降 |
| 方案B：分布式缓存 | 引入集中式缓存集群，订单服务读缓存、写后失效 | 多实例共享同一份数据，一致性可控；需新增运维对象与失效策略；改造周期约三周 |
| 方案C：数据库读优化 | 增加只读副本，读请求分流 | 不引入新组件；只读副本存在复制延迟，热点数据仍反复读库；扩容成本随流量线性增长 |
决策。采用方案B。理由有三点：第一，库存与商品状态需要多实例看到同一份数据，方案A的不一致风险超出团队可接受范围；第二，方案C的读副本无法消除热点重复查询，峰值时仍会打满主库，属于推迟问题而非解决；第三，方案B的改造周期与四周约束匹配，且缓存层可在后续复用。方案A保留为降级手段：缓存集群不可用时，接口回退到短时本地缓存并降低刷新频率。
后果。已确定的影响：新增一个缓存集群需要纳入监控与值班范围；订单服务增加缓存读写代码路径，发布时需同步检查失效逻辑；商品数据更新后存在最长5秒的可见延迟，产品侧已确认可接受。待观察的风险：缓存击穿在极端热点下的表现尚未压测；失效策略在批量改价场景下可能产生集中回源，需在上线后两周内观察回源指标。后续动作：由SRE在两周内补齐缓存集群的告警规则；后端在下次迭代补充击穿保护；本记录在促销结束后复盘，必要时更新状态。
逐项解释：每个字段为什么这样写
示例中的每一段都承担不同任务，照抄文字意义不大，理解取舍才有用。下面按字段说明写法要点。
背景段：写清触发原因与约束
背景段回答“为什么现在要决策”。示例先给可观察的现象（响应时间从180ms到620ms、读请求占比七成），再给时间压力（下次促销前），最后列约束（四周周期、不改写入链路、缓存失效仍可用）。这三类信息让读者能判断决策的紧迫程度和可选空间。常见问题是背景写成系统介绍，读者看完不知道问题出在哪；或者只写“性能不佳”，没有数字和范围，后续无法验证决策是否奏效。
备选方案：按同一口径比较，不写流水账
示例用表格呈现三个方案，每个方案固定写“做法”和“评估要点”两栏，评估要点围绕同一组维度展开：一致性、改造量、运维成本、是否真正解决热点问题。这样比较才有意义。如果每个方案各写各的优点，读者无法横向判断。方案数量以能覆盖真实可选路径为准，两个到四个都合理；把明显不可行的方案凑数反而稀释重点。
决策理由：与评估要点一一对应
决策段不是重复结论，而是把选择与前面的评估维度挂钩。示例的三条理由分别对应一致性、问题是否被真正解决、周期约束，读者可以逐条核对。写法上建议先给结论句，再列理由，理由尽量指向可核验的事实或约束，避免“更先进”“更主流”这类无法验证的表述。同时写清被放弃方案的处理方式，示例把方案A保留为降级手段，这能减少后续“为什么不选另一个”的反复讨论。
后果段：区分确定影响与待观察风险
后果段最容易写成空话。示例把它拆成三层：已确定的影响（监控、代码路径、5秒可见延迟）、待观察的风险（击穿表现、批量改价回源）、后续动作（告警规则、击穿保护、复盘时间）。确定影响是决策直接带来的、可以现在承诺的；待观察风险是尚不确定、需要上线后验证的。两者分开写，读者才知道哪些是既定代价、哪些还需要跟踪。每条风险尽量带一个观察指标或时间点，否则复盘时无从判断。
元信息与状态：让记录可被判断是否仍有效
状态、日期、决策者和参与评审角色看似形式，实际决定这份记录能否被正确引用。状态标明记录处于草案、已接受还是已废弃；日期帮助读者判断结论是否早于某次架构调整；参与角色说明谁有修改权、找谁确认。示例中“促销结束后复盘、必要时更新状态”一句，把状态维护写进了记录本身，避免记录长期停留在过期状态。
可迁移规律：把这份示例用到自己的决策场景
示例的具体内容不可复制，但结构与写法可以迁移。以下规律按结构、写作、协作三个层面整理，团队可据此建立自己的记录习惯。
结构规律：固定骨架，字段可增减
- 骨架保持“背景—选项—决策—后果”四段，顺序稳定，便于读者快速定位。
- 元信息至少包含状态、日期、决策者；参与评审角色按决策影响面决定是否列出。
- 轻量决策可省略表格，用两三句话写清选项与取舍；重大决策再补充评估维度和风险跟踪项。
写作规律：结论前置、理由可核验、风险显式化
- 标题直接写决策内容，读者从标题就能知道选了什么。
- 决策段先给结论句，理由对应评估维度，尽量引用数字、约束或已确认事实。
- 后果段把确定影响与待观察风险分开，风险附观察指标或复盘时间。
- 被放弃方案写明处理方式，减少后续重复讨论。
协作规律：评审、状态流转与后续引用
决策记录写完后需要进入团队的文档流程：评审阶段由受影响角色确认约束与风险描述是否准确，接受后由决策者更新状态，后续相关需求与设计文档引用这份记录的标题或编号，而不是各自复述结论。当决策被推翻时，新记录应链接旧记录并说明变更原因，旧记录状态改为已废弃，保留可追溯的链条。
在文档协作平台中沉淀这类记录，重点是把评审、状态和引用放在同一处。以ONES Wiki为例，页面支持富文本、Markdown与代码块，成员可以在线添加注释和评论，评审意见能直接落在记录页面上；页面模板库支持一键创建制式化文档模板，团队可以把ADR骨架固化为模板，减少每次从零起草；文档实时同步并记录所有页面版本，支持查看与回滚，决策记录的修改过程可追溯；页面组可关联项目，需求与文档互相对应，文档还能嵌入任务进度与报表，便于把后续动作与记录放在一起跟踪。状态字段的流转方式可按团队习惯在页面内约定，具体配置以实际使用版本为准。
适用边界：哪些情况不适合照搬这份示例
这份示例是一份中等重要程度的技术选型记录，字段完整度偏高。直接照搬到所有场景会造成两种浪费：轻量决策写得过重，重大决策写得不够。
按决策重要程度调整深度
可逆、影响范围局限在单个模块内的决策，例如某个工具函数的实现方式，用一段话写清背景与选择即可，不必列候选表格和风险跟踪项。涉及跨团队接口、数据模型、基础设施选型等难以回退的决策，示例的深度仍不够，需要补充成本估算、迁移路径和回滚方案。判断标准可以简单化为两条：改回来要多久、会影响多少团队。
示例情景不能当作真实证据
本文中的团队、系统、流量数字和选型结果均为虚构演示，用于说明字段写法，不构成真实案例，也不能用来证明某种缓存方案的效果。读者引用时应只借鉴结构与写法，具体结论需基于自己系统的测量数据。
合规、安全类决策需额外评审
涉及数据合规、安全边界、外部依赖引入的决策，除本文骨架外通常还需要补充合规评估结论、安全评审意见和审批记录，并按组织规定走相应流程。这类记录的证据链要求高于普通技术选型，示例中的字段只能作为起点。
记录粒度与团队规模匹配
小团队可以只保留标题、状态、背景、决策、后果五项，评审通过评论完成；团队规模扩大、决策影响面变宽后，再逐步补充参与角色、风险跟踪和引用关系。粒度随协作复杂度增长而增加，一开始就套用完整模板，容易让记录变成负担而无人维护。
常见问题
技术决策记录和需求文档、设计文档是什么关系？
三者回答的问题不同：需求文档说明要做什么、验收标准是什么；设计文档说明系统怎么实现；技术决策记录说明为什么选这个方案、放弃了哪些选项。实践中常见做法是设计文档在关键选型处引用对应的决策记录，避免把选型理由散落在多处。决策被推翻时，新记录链接旧记录并说明变更原因，旧记录状态改为已废弃，形成可追溯的链条。
团队刚开始写ADR，应该从多细的粒度起步？
建议从可逆性低、影响面宽的决策开始写，例如数据模型、跨团队接口、基础设施选型。这类决策一旦定下，改动成本高，记录的价值最直接。可逆、局限在单个模块内的决策先用一段话写清背景与选择即可。等团队形成习惯后，再按需要补充参与角色、风险跟踪和引用关系，避免一开始就套用完整模板导致记录无人维护。
决策记录写完由谁维护状态，过期了怎么处理？
通常由决策者负责状态更新，评审角色确认约束与风险描述是否准确。可以在记录里直接写明复盘时间点，例如示例中“促销结束后复盘，必要时更新状态”，让状态维护成为记录的一部分。当后续架构调整使原结论不再成立时，应新建记录说明变更，并把旧记录标记为已废弃，保留历史链条供追溯。
用文档协作平台沉淀决策记录，需要关注哪些能力？
重点看三件事：评审意见能否落在记录页面上、修改过程能否追溯、记录能否与需求和任务关联。以ONES Wiki为例，页面支持富文本、Markdown与代码块，成员可在线添加注释和评论；页面模板库支持一键创建制式化文档模板，可把ADR骨架固化为模板；文档实时同步并记录所有页面版本，支持查看与回滚；页面组可关联项目，文档还能嵌入任务进度与报表。模板库是否预置ADR类模板、状态字段如何流转，需按实际使用版本确认。
涉及安全或合规的决策，这份示例还够用吗？
不够。涉及数据合规、安全边界、外部依赖引入的决策，除背景—选项—决策—后果骨架外，通常还需补充合规评估结论、安全评审意见和审批记录，并按组织规定走相应流程。这类记录的证据链要求高于普通技术选型，示例中的字段只能作为起点，具体补充项以所在组织的评审要求为准。
