RFC 与设计文档

jonjia
6 阅读1分钟

RFC 与设计文档

原始链接: blog.pragmaticengineer.com/rfcs-and-de…

RFC（征求意见稿）或设计文档是工程团队常用的一种工具。通过提前理清假设和同步计划，它们能帮助团队更快地构建软件。在启动重要项目之前编写 RFC，就像为你的代码编写自动化测试一样重要。

这些文档大多属于公司内部资料。跳槽的工程师通常会把前东家行之有效的文档规范和结构带到新公司。

本文收集了一些公开的 RFC 模板、案例，以及使用该流程的公司名单。 建议以此为灵感，提取与你产生共鸣的部分，按需调整并尝试使用。

想了解更多关于软件工程团队成功规划的细节，请阅读我的长文：使用 RFC、设计文档和 ADR 进行工程规划。

此外，产品需求文档（PRD）通常与工程设计文档并行使用。如果产品经理不明确说明团队需要构建什么，这通常意味着公司缺乏写作文化。你可以参考 Lenny’s Newsletter（最受产品经理欢迎的读物）作者 Lenny Rachitsky 收集的 PRD 模板集合。

使用 RFC 或设计文档的公司

我整理了一些普遍采用 RFC 或设计文档流程的公司。文章末尾有更详细的列表，包含一些公司如何使用该方法的具体细节。

使用 RFC 或设计文档流程的公司

值得注意的是，名单中没有 Facebook/Meta。虽然公司内部有些团队会写单页文档，但 Facebook 是大型科技公司中最不重视文档的。正如我在《深入 Facebook 工程文化，第 2 部分》中所写：

“Facebook 的文档和测试比大多数科技公司都要少。这种模式能行得通有几个原因：历史因素、工程师任期长、拥有顶尖人才，以及他们构建了专门的系统来弥补文档和测试的不足。但我不建议刻意效仿这种方法，尤其是在异步工作和远程办公的时代。”

RFC 案例与模板

Google

设计文档概述。常见文档结构：

  • 背景和范围
  • 目标与非目标
  • 实际设计
  • 系统上下文图
  • API 接口
  • 数据存储
  • 代码与伪代码
  • 限制程度
  • 考虑过的备选方案
  • 跨领域关注点

Uber

RFC 流程概述（约使用至 2019 年）。

后端服务常见结构：

  • 审批人名单
  • 摘要（项目是关于什么的？）
  • 架构变更
  • 服务 SLA（服务等级协议）
  • 服务依赖
  • 负载与性能测试
  • 多数据中心考量
  • 安全考量
  • 测试与发布
  • 指标与监控
  • 客户服务考量

移动端常见结构：

  • 摘要（项目是关于什么的？）
  • UI & UX
  • 架构变更
  • 网络交互细节
  • 库依赖
  • 安全考量
  • 测试与发布
  • 数据分析
  • 客户服务考量
  • 无障碍设计

Sourcegraph

RFC 流程概述 及 公开 RFC 列表。示例：明确的仓库权限模型。

常见文档结构：

  • 摘要
  • 背景
  • 问题
  • 提案
  • 成功的定义

HashiCorp

RFC 流程概述。示例：[RFC] 在产品中启用小组件

常见文档结构：

  • 背景
  • 提案
  • 放弃的想法
  • (自定义部分，例如：)
  • 实施方案
  • 交互设计 (UX)
  • 界面设计 (UI)

SoundCloud

RFC 流程详解。 常见结构：

  • 头部信息（作者、评审人、复审日期、状态）
  • 需求
  • 方案
  • 收益
  • 完成情况或备选方案

RazorPay

文档模板 及 RFC 集合。示例：空间系统 RFC。常见结构：

  • 摘要
  • 动机
  • 详细设计
  • 缺点与限制
  • 备选方案
  • 落地策略
  • 遗留问题
  • 如何对人员进行培训？
  • 参考资料

Monzo

常见文档结构：

  • 为什么现在解决，而不是以后
  • 目标与非目标
  • 客户端 API 以及各平台的交互方式
  • 新的内部工具
  • 法律与隐私
  • 风险（必填项！）
  • 可观测性与优雅降级
  • 我们仍然未知的事项

Dune Analytics

公司采用此方法的概述。

Couchbase

新增 API 的 RFC 模板 及 所有 RFC 列表。优秀示例：错误处理 SDK。

常见结构：

  • 摘要
  • 动机
  • 总体设计
  • 错误处理
  • 文档
  • 语言特定细节
  • 问题
  • 更新日志
  • 签字确认

Incident.io

RFC 模板。“我们也将它用于非技术领域（如销售流程变更）。但我们不强制使用，为了保持早期阶段的速度，我们不总是写它们。” - Stephen Whitworth

RiskLedger

RFC 模板。常见结构：

  • 太长不看 (TL;DR)
  • 需求
  • 成功标准
  • 方案
  • 意识
  • 技术设计
  • 后端
  • 前端
  • 里程碑
  • 超出范围

Stedi

以下节选自长文《使用 RFC、设计文档和 ADR 进行工程规划》：

Stedi 在早期就引入了 RFC，以 GitHub 上的 .MD 文件编写并进行评论。通常用于广泛复杂的项目、公司级技术规范或 API 变更。模板包含：

  • 状态: 草案 | 提议 | 已发布
  • 类型: 实验性 | 信息性 | 当前最佳实践 | 强制要求
  • 范围: 受影响的工作范围。
  • 符号约定: 遵循 BCP 14 等标准。
  • 背景: 描述问题空间或需求。
  • 决策: 提议方案的详细描述。
  • 后果: 决策落地后的任何影响。

决策记录（Decision Records）是引入 RFC 后推出的更轻量级格式，通常使用 Google Docs 编写。涵盖技术决策及招聘、培训等多种任务。使用它的两个主要原因：

  1. 固化已做出的决策。
  2. 强制对需要做出的决策达成一致。

这是该公司使用的决策记录模板。

Stedi 内部备忘录这样解释为何强调“先想后写，先写后码”：

“写文档不是敷衍了事，要求提供文档也不是惩罚或控制机制。写文档是为了：i) 明确需求和假设，ii) 理清基于这些需求和假设的逻辑。**没有这一步，我们的软件很难长期交付理想的结果。**如果你只想执行，那就去执行别人文档里的计划。我们的领域太复杂，不能随便乱建软件。”

CockroachDB

数据库的主设计文档。这是用简明文字概述复杂系统的极佳例子。涵盖： 概述 / 架构 / 键 / 版本值 / 无锁分布式事务 / 逻辑映射内容 / 存储 / 自我修复 / 重新平衡 / Range 元数据 / Raft 一致性 / Range 租约 / 拆分与合并 / 节点分配 / 指标 / Zones / SQL。

使用 RFC 或设计文档的公司详情

根据反馈和调研，以下知名公司都在工程团队内部使用 RFC 或设计文档：

  • Airbnb: “我们为产品和工程都会写规范和设计文档。” - Manish Maheshwari
  • Affirm
  • Algolia: “我们发现 RFC 非常有价值。” - Praagya Joshi
  • Amazon: 工程团队会使用技术文档进行架构设计审查，这独立于产品需求文档（PR/FAQ）。部分组织遵循得极其严格。详情见《亚马逊的工程文化》。
  • AutoScout24
  • Asana
  • Atlassian
  • Blue Apron: 设有每周的架构实验室。详情。
  • Bitrise: 也用于非技术提案。
  • Booking.com: 详情。
  • Brex: 详情。
  • BrowserStack: “有助于理清成本/隐私/合规性需求，并找出最佳实现方式。”
  • Canonical
  • Caroussel
  • Catawiki: “这不仅增加了可见性、支持大规模协作，还能很好地对齐设计与开发周期。” - Özgen Güngör
  • Cazoo
  • Cisco: 至少部分团队在使用。
  • CockroachDB
  • Coinbase
  • Comcast Cable: 使用 ADR。
  • Container Solutions
  • Contentful
  • Couchbase
  • Criteo: 他们称之为 kick-offs。
  • Curve
  • Daimler
  • Delivery Hero
  • Doctolib
  • DoorDash
  • Dune Analytics: 附带 一个示例。
  • eBay
  • Ecosia: 详情
  • Elastic
  • Expedia
  • Faire
  • Flexport
  • Glovo: “我们写 RFC，同时也在代码库里用 ADR 记录架构设计。” - 来源
  • Gojek: “我们早就该这么做了。” - 前工程高级副总裁的 引言
  • Grab
  • GitHub
  • GitLab: 前端 RFC 流程详情。
  • GoodNotes: “我们在启动中大型项目前会制定实施计划，分享工程师的解决方案。” - Juanjo Ramos
  • Google
  • Grafana Labs
  • GrubHub
  • HashiCorp
  • Hopin
  • Hudl: “用于影响多个团队的非关键项目和技术决策。” - Juanjo Ramos
  • Indeed
  • Intercom
  • Kiwi.com
  • Klarna: “刚开始用于公司级变更，对于小规模变更，我们现在使用架构决策记录 (ADR)。” - Lucas Santos
  • LinkedIn: “有着浓厚的编写和评审 RFC 的文化。”
  • MasterCard
  • Mews: 详情
  • MongoDB
  • Monzo: 详情
  • Mollie
  • Miro
  • N26: 详情
  • Netlify: 详情。
  • Nobl9
  • Notion
  • Nubank
  • Oscar Health: “这是任何大型项目的强制要求。”
  • Octopus Deploy: “查阅文档能更好地理解不同场景，这比开会要好得多。” - Colin Bowern
  • OLX
  • Onfido
  • Pave
  • Peloton: “设计文档文化在集权和分权之间摇摆。过去一年引入了 ADR，长篇的‘设计文档’常作为 ADR 的补充。” - Peloton 的核心工程主管
  • Picnic
  • PlanGrid
  • Preply
  • Razorpay
  • Reddit: 详情
  • Red Hat
  • SAP: “有着编写架构概念和设计文档的流程。”
  • Salesforce
  • Shopify
  • Siemens: 详情。
  • Spotify: “RFC 和 ADR 已深深扎根于文化中。有时也用于非技术变更，如组织重组。” - Marcus Frodin
  • Square
  • Stripe: 写作文化详情。
  • Synopsys: “代码冻结后的所有更改都要经过 ECR 流程，并由跨部门团队审查。” - Steve Meier
  • Skyscanner
  • SoundCloud: RFC 流程详情。
  • Sourcegraph
  • Spotify
  • Stedi
  • Stream: 详情
  • SumUp
  • Thumbtack
  • TomTom
  • Trainline
  • TrueBill
  • Trustpilot
  • Twitter
  • Uber
  • VanMoof: “团队根据偏好和用例在 RFC 或 KDD 模板之间进行选择。” - Alexander Papageorgiou
  • Virta Health
  • VMWare
  • Wayfair
  • Wave
  • Wise: 使用更多 ADR。详情。
  • WarnerMedia / HBO / Warner Bros Discovery
  • Zalando: 详情
  • Zapier: “有助于在开工前明确范围并发现问题。”
  • Zendesk
  • Zillow

我参与投资的早期初创公司：

其他采用此方法的早期小型初创公司：

更多示例，请查看这个 Twitter 讨论帖。

希望这些例子对你有用。更多关于工程团队成功规划方法的内容，请阅读长文：使用 RFC、设计文档和 ADR 进行工程规划。

欢迎订阅我的每周简报获取类似文章。它在 Substack 技术类简报中排名第一，非常值得一读。

avatar
文章
阅读
粉丝