决策文档就是解这个问题的。叫 ADR、RFC 还是决策日志都无所谓，关键是在做选择的那一刻，把背景、备选方案和推理写下来。今年开始带开发团队之后，我对它的价值体会得更深了：它决定了团队拥有的是组织记忆，还是组织传说。

为什么值得花这个功夫

#

最直接的回报是不用把同一场架吵两遍。“API 版本策略不是已经定了吗？”只要决定了什么、为什么决定有清楚的记录，尘埃落定的问题就能保持落定，团队可以把力气花在执行上，而不是原路折返。

更安静的回报要过一段时间才显现。项目一跑就是几个月甚至几年，人来人往，最后留下的只有代码——代码能告诉你决定了“什么”，却永远不会告诉你“为什么”。决策文档保存的正是推理本身：当时存在的约束、被否掉的备选方案、拍板的人是谁。新人得到的是上下文而不是传说；跨团队的决策因为所有人都能看到权衡的因素而更容易获得真正的认同；决策者和参与者都写着名字，后续落实也就有了明确的主人。

什么时候写

#

不是每个决策都配得上一份文档。我会在决策属于以下情况时动笔：

• 回头代价高的 — 技术栈选择（框架、数据库、云服务商）、架构模式（微服务还是单体、事件驱动还是请求-响应）、第三方供应商选型、安全与合规方案
• 影响长期存在的 — 外部系统依赖的 API 契约、跨多个服务的数据模型、对既定模式的破坏性变更
• 需要跨团队的 — 需要多个团队或非技术相关方认同的事项、资源分配和优先级取舍
• Spike（技术预研）的结论 — 限时调研结束后，趁发现和决定还没蒸发，赶紧落成文档

反过来，容易撤销的决定、团队内部的实现细节、对自己范围之外几乎没有影响的选择，就别走形式了。没人需要的文档只是作业。

生命周期

#

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│    草稿     │ ──► │    评审     │ ──► │    批准     │ ──► │    实施     │
│    提议     │     │   反馈      │     │    接受     │     │    完成     │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │   否决/     │
                    │   取代      │
                    └─────────────┘

作者起草问题和候选方案，相关方进行评审——整套流程的价值主要就在评审这一步，因为假设被挑战、盲点被暴露都发生在这里。然后由决策者（通常是技术负责人、架构师或产品负责人）拍板，团队实施；实施中如果现实逼着改了方案，文档也要跟着更新。有的文档死在评审里，有的日后随情况变化被取代——两种都要清楚标记，一份过期却还挂着“已批准”的文档，是给下一个发现它的人挖的坑。

什么样的文档才值得读

#

从问题开始，而不是从你心仪的方案开始。我们在解决什么？为什么是现在？什么都不做会怎样？如果大家对问题本身都没有共识，讨论方案就是演戏。

然后给出真正的备选项——哪怕你已有强烈倾向，也至少写两三个。每个选项配上简短描述、优缺点、粗略的工作量估算（T 恤尺码就够用：S/M/L/XL），以及风险和应对办法。把落选方案写下来，未来的读者才能明白胜者为什么胜出。

把取舍大声说出来。“我们选择上市速度，放弃架构纯粹性。”“我们接受运维复杂度上升，换取更好的扩展性。”“我们把开发者体验放在原始性能之前。”这样的句子对未来读者的帮助，超过几页纸的分析。

让讨论落在具体的东西上：展示方案实现样子的代码片段、系统交互图、指向 Spike 概念验证的链接。抽象的讨论只会产出抽象的决定。

最后，给它一个期限：什么时候必须定下来，谁在什么时间前要给意见，拖着不决会卡住什么。没有期限的决策会永远飘着。

示例：架构决策记录（ADR）

#

下面是一个实际的决策文档示例：

# ADR-001: API Authentication Strategy

**Status:** Accepted
**Date:** 2024-11-15
**Decision Maker:** Sarah Chen (Platform Architect)
**Contributors:** Backend Team, Security Team, Mobile Team

## Context

Our public API currently uses API keys for authentication. As we expand to
support third-party integrations and mobile apps, we need a more robust
authentication mechanism that supports:
- Token expiration and refresh
- Scoped permissions
- User-level authentication (not just service-level)

## Decision

We will implement OAuth 2.0 with JWT tokens for API authentication.

## Options Considered

### Option 1: OAuth 2.0 with JWT (Recommended)
**Description:** Industry-standard protocol with self-contained tokens

| Pros | Cons |
|------|------|
| Industry standard, well-documented | More complex initial implementation |
| Self-contained tokens reduce database lookups | Tokens cannot be revoked instantly |
| Broad library support | Requires refresh token management |

**Effort:** Medium (2-3 sprints)

### Option 2: Session-based Authentication
**Description:** Traditional server-side sessions with cookies

| Pros | Cons |
|------|------|
| Simple to implement | Not suitable for mobile apps |
| Easy to revoke sessions | Requires sticky sessions or shared session store |
| Familiar to most developers | Doesn't scale as well |

**Effort:** Small (1 sprint)

### Option 3: Custom Token System
**Description:** Build our own token-based authentication

| Pros | Cons |
|------|------|
| Fully customizable | Reinventing the wheel |
| No external dependencies | Security risks from custom implementation |

**Effort:** Large (4+ sprints)

## Consequences

- Mobile team can implement standard OAuth flows
- We'll need to set up a token refresh mechanism
- API documentation will need updates for OAuth flows
- Existing API key users will need a migration path (6-month deprecation)

## References

- [OAuth 2.0 RFC 6749](https://tools.ietf.org/html/rfc6749)
- Internal spike document: [Authentication Options Spike](/spikes/auth-spike-2024)
- Security team review: SEC-2024-042

一份可以直接拿走的模板

#

把它当起点，按团队需要往下删：

问题描述

#

我们要解决什么问题？为什么重要？不采取行动的代价是什么？

背景

#

提供上下文、历史和相关细节。链接到相关文档、过去的决策或Spike结果。

约束条件

#

所有方案必须遵守哪些限制或要求？

• 预算约束
• 时间线要求
• 技术约束（现有系统、技能储备）
• 合规或安全要求

考虑的方案

#

建议

#

说明推荐的选项，并总结在约束和取舍条件下为什么它是最佳选择。

决定

#

做出决定后记录最终决策。如果与建议不同，说明原因。

后果

#

这个决策有什么影响？需要哪些后续工作？

行动项

#

参考资料

#

相关文档、外部资源、Spike结果或过去决策的链接。

让习惯扎根

#

文档放在固定的地方——仓库里的专用文件夹也好，Wiki 空间也好——找不到的决策等于不存在。保持轻量：一份要写好几天的文档根本不会被写出来。在代码注释、提交信息和 PR 里引用决策文档，让“为什么”一直贴着“是什么”。决策被取代时别删旧文档，标记为已取代并链接到新决策，历史本身就是价值。另外，在回顾会上时不时翻翻过去的决策：哪些经受住了考验，哪些换成今天你会做得不一样。

失败的方式也同样好预测。分析瘫痪：定个期限，用手头的信息做决定，大多数决策以后都能再议。橡皮图章式评审从来提不出真正的批评，只加流程不加价值。写了却从未落地的孤儿文档，比没有文档更糟。细节过多也是病：文档管“为什么”和“是什么”，不管“怎么做”，实现细节属于技术规格书。还有，当有人不同意时，把反对意见也写进去——决定也许照旧，但那条异议恰恰是一年后某个人最需要的上下文。

从你的下一个重要决策开始吧。写得糙一点没关系，流程边用边磨。每一场因为有人直接读了 ADR 而没开成的“我们当初为什么选 X”会议，都是还给团队的时间。

延伸阅读

#

本站相关文章：

• 理解敏捷软件开发中的Spike - 在做重大决策前用 Spike 收集信息
• 回顾会：反馈循环的力量 - 把审视过去的决策纳入持续改进
• API规划 - 把决策文档的思路用在 API 设计上
• 用GitHub做项目管理 - 让决策文档和代码放在一起

外部资源：

• Documenting Architecture Decisions - Michael Nygard - 让 ADR 流行起来的那篇经典博文
• ADR GitHub Organization - 架构决策记录的工具、模板和示例
• Design Docs at Google - Google 的设计文档实践
• RFC Process at Rust - Rust 语言完善的 RFC 流程
• Spotify’s Decision Record Template - Spotify 关于何时写 ADR 的思考

Alan 为什么放弃了开会

#

他们的起点你一定不陌生：没人做准备，会议迟迟开不起来，嗓门最大的人不管对错总能拍板。一小时后，你比进会议室之前更糊涂，开始琢磨抽屉里还有没有止痛药。

Alan 一开始也想修好会议这台机器——最长 15 分钟、议程明确、必须产出决策。没用。讨论照样跑题，说过什么没人记得，缺席的和远程的同事干脆被排除在外。于是他们干脆把整件事搬进了文字里。

他们列举的好处我基本都认。写作逼你停下来真正思考，讨论因此更细致、论证更扎实；一切都有记录，不用靠七零八落的记忆；也不再是一场口才竞赛。而且论坛对全公司公开，谁都能参与讨论——不再只属于碰巧坐在会议室里的那几个人。

把 GitHub 当公司论坛用

#

这个"论坛"就是 GitHub。一个本为代码评审而生的平台，被 Alan 理直气壮地挪作他用。搭建过程简单得有点不好意思：

1. 注册一个 GitHub 账号。
2. 建一个没有代码的私有仓库（他们的叫"Topics"）。
3. 建一套标签体系，给对话分类。
4. 用 Issues 标签页：open 的是进行中的讨论，closed 的是已定的决策。

他们的 issue 已经超过 17,000 个。这意味着 17,000 场没必要开的会，而最让我心动的是：每一个决策为什么这么定，都留下了可搜索的历史。想推翻一个老决定？先去读读上次是哪些论据赢了。

什么时候开 issue

#

不是每个决策都配得上一个 issue。他们的过滤器是四个问题：谁会受影响？可逆性如何？急不急？做决定前还需要更多背景吗？

大体上，影响大、难回头的决策进论坛，其余留在 Slack。他们也用"单向门/双向门"的说法：单向决策（撤销代价太大，他们举的例子是涨价）走完整的书面流程；双向决策（撤销便宜，最坏不过损失点精力）就不必兴师动众。

LOCI：谁干什么

#

每场讨论都按 LOCI 模型分配角色——Lead、Owner、Consulted、Informed。

Lead 对决策的成败负责，确保决策背后的来龙去脉在团队里讲清楚。他会在讨论开头说明自己想介入到什么程度，之后信任 Owner、为团队的产出兜底，只在强烈反对时才出声。每场讨论只有一个 Lead。

Owner 拍最终的板，推着项目往目标走。他要保证每个参与者知情并按时发言，调查问题、收集答案、跟进进展，负责开 issue 也负责关 issue，最后做出决定并公之于众。碰到自己迈不过去的坎，就去找 Lead。每个决策也只有一个 Owner。

Consulted 是那些意见真正影响权衡的人。他们必须按时发言——哪怕只是一句"我没有补充"——如果认为决策错得离谱，就要拉响警报，最坏的情况上报给 Lead。Alan 把这个群体控制在六人左右，再多，进度就要付出代价。

Informed 通常在决策定了之后才被告知。沟通是单向的，不需要他们做任何事。通知谁，由 Owner 根据影响范围来定。

这是针对单个决策的做法。放到整个项目上，我会把同样的事一次性写成一份项目沟通计划：谁需要知道什么、多久一次、由谁来告诉他们。

一个 issue 的解剖图

#

每个 issue 都用同一套模板。这既能磨利思路，也悄悄教会了初级同事怎么拆解问题：

• 范围——讨论的"为什么"，其中最被低估的一行是"这个 issue 不讨论……"
• 背景和材料——链接到之前的讨论和文档
• LOCI——谁是 Lead、Owner、Consulted、Informed
• 截止时间——发言截止日、issue 关闭日、必须拿出方案的日期
• 方案提议——推荐一个方案，或列几个供选择
• 提问——把具体的问题抛给具体的人，去证实或推翻具体的假设，免得 issue 变成一只"漂流瓶"

让讨论不拖沓的写作规矩

#

文字辩论拖起来一点不比口头的差，所以他们有规矩。首先是简洁——他们引用布瓦洛：“构思清晰的内容，表达也清晰。“写不简单，说明你自己还没想清楚。其次，每写一段都做一次"那又怎样？“测试：如果你这条评论的言下之意不明显，就把它写明白。

对 Owner 来说，开完 issue 之后的经营同样重要。让讨论始终对准那个"百万美元问题”——真正要紧的那一个卡点——别让它溶解在细节的海洋里；定期总结哪些已达成一致、哪些还悬着；Slack 提醒留作最后手段，只用于发言逾期或真正紧急的情况。

Owner 还可以隐藏那些没有推动对话的评论。另外，标题、脚注、表格、键盘快捷键这些 GitHub 排版功能，默认人人都要会用——在书面世界里，形式和内容几乎同等重要。

不搞共识，不养观众

#

有两条规矩防止这套系统沦为"委员会决策”。

第一，Owner 以 Alan 所说的"开明专制者"身份做决定。他去调研新想法、衡量风险、分析数据、追问同事——但不寻求共识，也没义务采纳听到的每一条建议。Alan 说得很直白：公司不是民主制。人人都是股东，公司利益排在团队和个人之前。当然他们也不要孤立、仓促、拍脑袋的决定。当 Owner 对这一注有了足够把握，就拍板，大家一起试；等影响逐渐清晰，再回头复盘，看下次怎么做得更好。

第二，控制参与人数。贝佐斯的"两个披萨"规则在异步世界照样成立：人越多，每个人的贡献越少。超过六个参与者，旁观者效应就开始冒头，参与质量随之下滑。通知也遵循同样的哲学，渐进式来——Alan 信任每个人都配置好了自己的 GitHub 通知（Settings 里把"Participating"和"Watching"下的"Web and Mobile"勾上），所以 issue 提问区里的 @ 能省则省。

我打算带走什么

#

一场会议的内容，永远没法向缺席的人复述完整；但一份写下来的决策，谁都能读。Alan 自己也说，这不是最好的、更不是唯一的方案，只是最合他们脾性的那一个：打断变少了，旁观者效应变淡了，做决策时能先退一步，事实也都写在纸面上。我不打算把团队的每个决定都搬进 GitHub issue，但下面这个模板，马上就进我们的仓库。

做成 GitHub issue 模板

#

把下面这段存成 .github/ISSUE_TEMPLATE/decision.md，放进你拿来当论坛的那个仓库，以后每次有人新建 issue，GitHub 都会把它列出来供选择。各个部分是 Alan 的，LOCI 那几行和标签是我加的。

---
name: 决策
about: 提出一个决策，以书面形式收集意见
title: "[决策] "
labels: decision
---

## 范围
- 这个 issue 的目标是……
- 这个 issue **不**讨论……

## 我为什么开这个 issue

## LOCI
- Lead：
- Owner：
- Consulted：
- Informed：

## 时间线
- 发言截止日：
- 决策截止日：

## 背景和材料

## 方案提议

## 提问

GitHub Issues 还是 GitHub Projects？

#

如果你在更大的范围里考虑拿 GitHub 做项目管理，这两样东西分工不同。Issues 承载讨论，关闭之后承载的就是决策本身。GitHub Project 则是铺在一个或多个仓库的 issue 之上的看板或表格，状态、负责人、截止日期这些字段都可以自己定义。像 Alan 这样的决策论坛，标签加上 issue 列表就够了。等你想把所有还没定的决策放在一个屏幕上、按必须拍板的日期排好序，或者开始在同一个地方跟踪交付工作时，再加一个 Project。大多数团队最后都是走到这一步，两样一起用。

人为什么想要自己想要的那些东西？这个问题我想得比自己预期的多。最早写这篇的时候，我在做一个大家整天讨论化妆品的平台。两件几乎一样的产品，为什么一件被人惦记、另一件无人问津，这基本就是整个生意的核心。品味当然因人而异，但底下的规律出奇地一致。

合意性、可行性和可持续性

#

这三个视角出自设计思维，如今已经是产品团队在拍板之前检验一个想法的常用方法。它有用的地方在于，三者失败的方式各不相同。一个做得出来、也赚得了钱、却没人想要的产品，是最典型的创业失败：工程扎实，定价合理，然后无人问津。一个让人想要、却做不出来或者赚不了钱的产品，至少败得明明白白，你早就能看到它会栽在哪儿。

合意性是团队最常跳过的一项，因为它最难衡量，也最容易想当然。团队里每个人本来就想要自己在做的东西。这说明不了别人想不想要。

这篇剩下的部分，先讲合意性由什么构成，再讲怎么去验证它。

得管用，而且一直管用

#

想要的念头，通常从朴素的实用开始：真能帮你省下十分钟的厨房小工具，一直稳稳保持在线的手机。但光有实用，只能到“还行”为止。真正被人惦记的东西，把自己的活儿干得出奇地好，而且一直干下去。让一次购买变成一件舍不得撒手的私藏，靠的是质量和耐用：一辆老爷车，一把比主人还长寿的刀。没有人会渴望一件自己觉得快要坏掉的东西。

得让人心里动一下

#

审美的拉力比我们愿意承认的大得多。跑车的线条、一道菜的摆盘，在理性来得及投票之前就先抓住了你。而最强烈的想要，都是情绪上的：快乐、怀旧、归属感。一只破旧的童年玩具，任何实用指标都不及格，却怎么也扔不掉。个性化戳的是同一根神经。为你量身定制的东西，会给你一种“这是我的”的感觉，量产版永远给不了。

别人替我们做的决定，比想象中多

#

想不想要，一部分是社会建构出来的。潮流、同伴的认可、文化习惯，都在悄悄给我们的欲望掌舵。稀缺也一样：限量版、稀有宝石、独一无二的物件。稀有传递的信号是，想要这件东西，本身就等于加入了一个小圈子。然后声誉把这一切再放大一层：清一色的好评和口碑，让人觉得想要它是安全的。在那个化妆品平台上，我每天都看着这个循环转一圈：一位人气很高的测评博主，一款限量产品，一周后就卖断货了。

账还是得算得过来

#

价格杀不死欲望，但“不划算”可以。人们愿意为奢侈品掏溢价，却会毫不犹豫地放弃任何让辛苦钱显得不值的东西。而且越来越多的人把价值观也放进了同一笔账里：一样东西是不是以可持续、合乎道德的方式生产出来的，如今会直接影响它在愿望清单上的位置。我自己也算一个。

怎么验证一样东西让不让人想要

#

合意性的陷阱在于，直接问是问不出来的。“你会用这个吗？”几乎每个人都会客客气气地说会，因为说“会”不花任何代价。真正管用的测试，都是让人放弃点什么，比如时间、钱、一个邮箱地址或者一个习惯，然后看他们肯不肯。

问过去，别问将来。“说说你上一次遇到这个问题是什么时候，当时是怎么办的”，这样能问出真实的行为。如果谁都想不起上一次是什么时候，说明这个问题还没痛到让人想要一个解决办法。

摆一扇假门。为一个还不存在的东西做个落地页，或者在现有产品里加个按钮，然后数数有多少人点进来、留下邮箱。这么做感觉有点狡猾，但它是你能拿到的最便宜、也最诚实的信号。门后面要老老实实写清楚：这个功能即将推出。

要一个承诺。候补名单是弱信号，预购或者交定金是强信号。人们什么都肯报名，但只会为真正想要的东西掏钱。

如果是大家已经在用的东西，就问他们：要是以后再也用不了，会是什么感觉。产品圈里有条常见的经验法则：如果大约 40% 的用户会“非常失望”，你手里的东西就是大家真心想要的。这个衡量方式很粗糙，但比问人家喜不喜欢强多了。

还有，看人们做了什么，而不是听他们说了什么。哪些功能会被用第二次，哪些功能不用提醒大家也会回来用，东西坏了的时候大家抱怨什么。抱怨在这件事上被严重低估了。没有人会为失去一样自己本来就不想要的东西而抱怨。

把这些放在一起

#

这些特质，单拎哪一条都撑不起一件产品。但叠上几条，真有用、做工好、好看、稍微难买到、还有你信任的人背书，就成了让人排队的东西。剩下的部分，大多是营销的活儿。

简单来说

#

合意性就是人们有多想要一样东西，而不只是需不需要。放到产品上，它是“大家想不想要这个？”这个视角，和技术可行性、商业可持续性并列。它来自经久耐用的实用性、情感或审美上的吸引力、社会认同和稀缺性，以及让人觉得公道的价格。靠问人家会不会用，是找不到它的。要验证它，就让人放弃一点真实的东西，然后看他们怎么做。